- Home /
- Psion II /
- Technical Reference Manual /
- Chapter 6
CHAPTER 6
____________
MEMORY USAGE
____________
6.1 INTRODUCTION
This chapter covers all aspects of memory usage, RAM, ROM, registers and
I/0. To use an Organiser effectively it is essential to understand the way
memory is used.
There are five operating systems described, each one corresponding to a
machine type:
1. CM/OS which has 8K of RAM. It does not support 128K datapacks,
RAM packs, the bar code reader or the magnetic card swipe.
2. XP/OS which has 16K of RAM.
3. XP2/OS which has 16K of RAM, POS200.
4. LA/OS which has 32K of RAM (see Chapter 5).
5. LA2/OS which has 32K of RAM, POS200 (see Chapter 5).
The variables given in this chapter are guaranteed not to move in future
versions of the operating system. They are the only variables which can be
used safely unless reference is made to the operating system version.
The six scratch registers UTW_S0 to UTW_S5 may be used for local values.
They are used by the operating system and are not guaranteed to be
preserved by operating system calls. The seven scratch register UTW_R0 to
UTW_R6 are maintained values. If they are used, the existing values must
be pushed and restored before returning from that routine.
__________
6.2 MEMORY MAP
$FFFF I-------------------------------I
I System ROM I
$8000 I-------------------------------I
I Not Used (except LA/OS) I
$8000 $6000 $4000 I-------------------------------I
LA/OS XP/OS CM/OS I Processor Stack I
$7F00 $5F00 $3F00 I-------------------------------I
I Language Stack I
I (grows down) I
I I
I (grows up) I
I Allocated Cells I
I...............................I
I System Variables I
$2000 I-------------------------------I
I Not Used (except LA/OS) I
$0400 I-------------------------------I
I Hardware Addresses I
$0100 I-------------------------------I
I Transient Application Area I
$00E0 I-------------------------------I
I System Variables I
$0040 I-------------------------------I
I Not used I
$0020 I-------------------------------I
I Internal Registers I
$0000 I-------------------------------I
__________
6.3 RAM MEMORY
_________
6.3.1 ZERO PAGE
Zero page RAM runs from $40 to $FF. From $40 to $DF is used by the
operating system; from $E0 to $FF is the transient application area. It is
safe to assume that these variables get trashed by all device drivers. In
particular it should be noted that a WARM BOOT uses $F8 to $FF.
For example the RS232 uses $E0 to $FF for the set-up parameters so that the
code is faster and more compact. Every time COMM is re-invoked these
parameters are copied down from the dedicated application space (at DV_SPAR
- $214F).
_____________
6.3.2 NON-ZERO PAGE
On the different models RAM is at the following addresses:
1. CM/OS $2000 - $3FFF
2. XP/OS or XP2/OS $2000 - $5FFF
3. LA/OS or LA2/OS $0400 - $7FFF
The top $100 bytes of RAM is reserved for the processor stack. Just below
is the language stack which grows down in memory.
At $2000 the non-zero page variables start. Immediately thereafter is
allocated space. This consists of 16 pre-allocated cells for use by the
operating system and 16 cells which can be used by applications for
permanent use.
The pre-allocated areas are (in order):
Permanent cell Code/data from booted devices
Top level menu cell
Diary cell
Language text cell Editing/translating OPL/CALC
Symbol table cell Translating OPL/CALC
Global record cell Translating OPL/CALC
QCODE output cell Translating/running OPL/CALC
4 field name tables Field names for files opened in OPL
4 file buffers Buffers for files opened in OPL
Database cell All data held in device A:
Device A: has the same format as a datapack and contains both OPL
procedures and databases. There are just three differences between device
A: and devices B: & C:
1. The pack header of device A: is undefined.
2. When an item is deleted the space is recovered (as in a Rampack).
3. Uses PKW_CMAD instead of PKW_CPAK.
4. The pack size is variable.
5. Accessing is faster.
6. The data is less secure, erased by resetting the machine.
The allocated area grows up towards the language stack. Before any
operation involving memory both the allocator and the language ensure there
is at least $100 bytes between RTA_SP and ALA_FREE. If there isn't 'OUT OF
MEMORY' or 'PACK FULL' is reported. These messages are functionally the
same in the case of device A:, it depends on which routine the out of
memory condition is detected.
__________________
6.4 NON-RAM MEMORY MAP
In the memory map certain areas contain system registers and I/O rather
than RAM.
__________________
6.4.1 INTERNAL REGISTERS
The addresses in the range $01 to $1F are used as internal registers by the
6303 processor. Their use is as follows:
Address Organiser Name Register Read/Write
$01 POB_DDR2 Port 2 data direction register W
$02 Not used Port 1 R/W
$03 POB_PORT2 Port 2 R/W
$04 Not used Port 3 data direction register W
$05 Not used Not used -
$06 Not used Port 3 R/W
$07 Not used Port 4 R/W
$08 POB_TCSR1 Timer Control/Status R/W
$09 POW_FRC Free running counter - high R/W
$0A Not used Free running counter - low R/W
$0B POW_OCR1 Output compare register - high R/W
$0C Not used Output compare register - low R/W
$0D Not used Input capture register - high R
$0E Not used Input capture register - low R
$0F POB_TCSR2 Timer control/Status register 2 R/W
$10 POB_RMCR Rate, mode control register R/W
$11 POB_TRCSR Tx/Rx control status register R/W
$12 POB_RDR Receive data register R
$13 POB_TDR Transmit data register W
$14 POB_RCR RAM/Port 5 control register R/W
$15 POB_PORT5 Port 5 R
$16 POB_DDR6 Port 6 data direction register W
$17 POB_PORT6 Port 6 R/W
$18 Not used Port 7 R/W
$19 Not used Output compare register - high R/W
$1A Not used Output compare register - low R/W
$1B POB_TCSR3 Timer control/Status register 2 R/W
$1C POB_TCONR Timer constant register W
$1D Not used Timer 2 Up counter R/W
$1E Not used Not used -
$1F Not used Test register (do not use) -
See Chapter 2 for a full description of the Organiser use of the timers and
ports and the Hitachi 6303X User Guide for a more detailed general
description of the ports.
_________________
6.4.2 MEMORY MAPPED I/O
In the memory map between $180 and $3FF lie the semi-custom chip
addresses:
Address Organiser Name Description
$0180 SCA_LCDCONTROL Liquid Crystal Display (LCD) registers
$0181 SCA_LCDDATA
$01C0 SCA_SWITCHOFF Switch off
$0200 SCA_PULSEENABLE Pulse enable
$0240 SCA_PULSEDISABLE Pulse disable
$0280 SCA_ALARMHIGH Buzzer
$02C0 SCA_ALARMLOW
$0300 SCA_COUNTERRESET Counter for kybd + clock
$0340 SCA_COUNTERCLOCK
$0380 SCA_NMIMPU Enable NMI to processor
$03C0 SCA_NMICOUNTER Enable NMI to counter
The semi-custom chip does not decode all the address lines. For the LCD
driver $180,$182,$184 up to $1BE are identical, as are $181,$183, up to
$1BF. For the other addresses the bottom 6 bits are ignored.
These addresses should be accessed with great care. To prevent casual
accessing, PEEKing and POKEing from OPL to the range $0182 to $03FF and in
the range $00 to $3F are disallowed.
See Chapter 2 for a full description of how these address are used.
____________
6.5 MEMORY USAGE
________________
6.5.1 OPERATING SYSTEM
The following variables and addresses are guaranteed on all versions of the
operating system after 2.4. Any extra variables added in future
refinements of the operating system will lie between the end of BTA_VECT
and RAMFREE. The variables are followed by allocated space, so the address
at ALT_BASE gives the end of variables.
_________________
6.5.1.1 NAMING CONVENTION -
All variable names have the following format:
XXY_ABCD
where xx is the abbreviated name of the module which uses the variable,
y is either b for byte variables,
or w for word variables,
or t for tables,
or a for address,
and abcd is the name of the variable of which only the first 3 letters
are significant.
The abbreviated module names are:
ac language table actions
al allocator
am alarm
bt boot routines
bz buzzer
di diary
dp display
dv devices
ed edit
er error handler
fl files
fn maths functions
im maths table actions
it table routines
kb keyboard
lg language translator
lx language lexer
mn menu
mt maths BCD routines
pk datapacks
rt run time
tl top level
tm time
ut utilities
_________
6.5.1.2 ZERO PAGE -
$40 UTB_7E JMP instruction for vector in UTW_S0
$41 UTW_S0 General word variables S0 - S5
$43 UTW_S1
$45 UTW_S2
$47 UTW_S3
$49 UTW_S4
$4B UTW_S5
$4D UTW_R0 General word/byte variables R0 - R6
$4D UTB_H0
$4E UTB_L0
$4F UTW_R1
$4F UTB_H1
$50 UTB_L1
$51 UTW_R2
$51 UTB_H2
$52 UTB_L2
$53 UTW_R3
$53 UTB_H3
$54 UTB_L3
$55 UTW_R4
$55 UTB_H4
$56 UTB_L4
$57 UTW_R5
$57 UTB_H5
$58 UTB_L5
$59 UTW_R6
$59 UTB_H6
$5A UTB_L6
$5B BTB_NMFL NMI flag, cleared when NMI executes
$5C BTW_CCNT Time (in seconds) before auto switch off
$5E BTA_RTOP Address of RAMTOP
$60 RTB_LBAT Run time low battery flag
$61 XXB_XXXX Reserved
$62 DPB_CPOS Cursor position (0-31)
$63 DPB_CUST Cursor status byte
$64 DPB_VLIN Scrolling line position
$65 DPB_VSIZ Number of characters to scroll
$66 DPB_VDIR Scroll direction
$67 DPB_SPOS Save cursor position, used in DP_SAVE
$68 DPB_SCUS Save cursor status, used in DP_SAVE
$69 DPW_SPED Delay when scrolling in ticks (default 4)
$6B DPW_DELY Delay before scrolling in ticks (default 10)
$6D DPW_REDY 'Ready to display' timer in ticks
$6F DPA_VADD Address of scrolling string
$71 KBW_TDEL Keyboard polling time in milliseconds
$73 KBB_BACK Offset in KBT_BUFF to oldest key in buffer
$74 KBB_NKYS Number of keys in buffer
$75 KBB_PREV Previous key pressed
$76 KBB_WAIT Unget key, zero if no key else the key
$77 KBB_DLAY Delay before auto-repeating in ticks (default 14)
$78 KBB_REPT Delay on auto-repeat in ticks (default 14)
$79 KBB_CNTR Keyboard counter
$7A KBB_KNUM Offset into keyboard table
$7B KBB_STAT CAPS, NUM and SHIFT lock status
$7C TMB_SWOF Auto-switch off flag, set for auto-switch off
$7D TMW_TOUT Time left in seconds before auto-switch off
$7F EDB_MLEN Maximum input length
$80 EDB_PLEN Prompt length
$81 EDB_FLIN First editable line
$82 EDB_POFF First editable character in first line
$83 EDB_CLIN Current line edit
$84 EDB_STAT Editor cursor status
$85 EDW_CPOS Current position within line
$87 EDW_CB Offset to current line
$89 EDW_BL Total buffer length
$8B PKB_CURP Pack being looked at
$8C PKB_CPAK Actual current pack
$8D PKW_RASI Length of RAM file
$8F PKW_CMAD Offset into RAM file
$91 PKB_HPAD High order byte of pack address
$92 PKW_CPAD Pack address
$94 PKA_PKID Pointer to current pack identifier
$96 FLB_RECT Current record type
$97 FLB_CPAK Current pack
$98 FLB_CONT Device being DIR-ed
$99 FLW_DREC Next directory record number
$9B FLW_CREC Current record number
$9D FLW_FNAD Address of file name
$9F FLW_NREC Number of records
$A1 TLB_RECT Current record type
$A2 TLB_CPAK Current default pack (0-2)
$A3 TLB_MODE Which option: FIND, SAVE or ERASE
$A4 BZB_MUTE Non-zero to mute buzzer
$A5 RTA_SP Run time stack pointer
$A7 RTA_FP Run time frame pointer
$A9 RTA_PC Run time program counter
$AB LGW_CLIN Current line being edited
$AD LXA_CURR Current character pointer
$AF LXB_PTOK Previous token
$B0 ACW_1X Array index
$B2 ACW_2X Maximum string size
$B4 ACW_PREC Pointer to variable
$B6 ACW_CONS Temporary constants
$B8 ACW_GLCD Global O code size
$BA ACW_LEFT Current free O code bytes
$BC ACW_OCSZ Total O code size
$BE ACB_NEST Structure next level
$BF ACW_LABL Next new label number
$C1 ACW_R0 General language word
$C3 ACW_R1 General language word
$C5 MTT_AMAN Accumulator : mantissa
$CC MTB_AEXP Accumulator : exponent
$CD MTB_ASGN Accumulator : sign
$CE MTT_OMAN Operand : mantissa
$D5 MTB_OEXP Operand : exponent
$D6 MTB_OSGN Operand : sign
$D7 ITA_PCNT Table program counter
$D9 ITA_BASE Table base
$DB ITA_SPTR Table stack pointer
$DD ITB_TEST Table flag
$DE IMA_GPTR General pointer
$E0 - $F7 Transient application area
$F8 - $FF Transient application area, trashed on WARM BOOT
Diary variables, overlayed against the maths variables:
$C5 DIB_YEAR Year
$C6 DIB_MONS Month
$C7 DIB_DAYS Day
$C8 DIB_HOUR Hour
$C9 DIB_MINS Mins
Alarm variables, overlayed against the maths variables:
$C5-$CB AMT_TEMP Alarm temporary area
Run time variables, overlayed against the language translator variables:
$B0 RTB_ESCF Escape flag
$B1 RTB_LOGN Current logical name
$B2 RTB_TRAP Trap flag
$B3 RTB_EROR Current error condition
$B4 RTB_CRFL Carriage return flag
$B5 RTB_CDRV Device of top procedure
$B6 RTW_S0 General word variables
$B8 RTW_S1
$BA RTW_S2
$BC RTW_S3
$BE RTW_S4
$C0 RTW_S5
$C2 RTW_S6
The area $00 - $3F is described in Section 6.3.1.
_____________
6.5.1.3 NON-ZERO PAGE -
$2000 ALT_BASE Base of allocator cells
$2000 PERMCELL Permanent cell
$2002 MENUCELL Top level menu cell
$2004 DIRYCELL Diary cell
$2006 TEXTCELL Language text cell
$2008 SYMBCELL Symbol table cell
$200A GLOBCELL Global record cell
$200C OCODCELL QCODE output cell
$200E FSY1CELL Field name symbol table 1
$2010 FSY2CELL Field name symbol table 2
$2012 FSY3CELL Field name symbol table 3
$2014 FSY4CELL Field name symbol table 4
$2016 FBF1CELL File buffer 1
$2018 FBF2CELL File buffer 2
$201A FBF3CELL File buffer 3
$201C FBF4CELL File buffer 4
$201E DATACELL Database cell
$2020 - $203E 16 free cells for use by applications
$2040 ALA_FREE Top of allocator area
$2042 BTA_2IQ IRQ2 re-vector address
$2044 BTA_CMI CMI re-vector address
$2046 BTA_TRP TRAP re-vector address
$2048 BTA_SIO SIO re-vector address
$204A BTA_TOI TOI re-vector address
$204C BTA_OCI OCI re-vector address
$204E BTA_ICI ICI re-vector address
$2050 BTA_1IQ IRQ1 re-vector address
$2052 BTA_SWI SWI re-vector address
$2054 BTA_NMI NMI re-vector address
$2056 BTA_WRM WRM re-vector address
$2058 BTA_SOF SWOF re-vector address
$205A BTA_POLL Keyboard poll routine
$205C BTA_TRAN Keyboard translate routine
$205E BTA_TABL Address of keyboard lookup table
$2060 UTW_FP Frame pointer for ENTER/LEAVE
$2062 BTB_IGNM Flag to ignore an NMI
$2063 BTB_IMSK Save interrupt mask while off
$2064 BTB_TCSR Save TCSR1 while off
$2065 BTA_SBAS Language stack base
$2067 BTA_SAVSTACK Save stack pointer while off
$2069 BTW_1DONTUSE Used in SWI's only
$206B BTW_2DONTUSE " " " "
$206D BTW_3DONTUSE " " " "
$206F BTB_4DONTUSE " " " "
$2070 DPT_TLIN Top line screen buffer
$2080 DPT_BLIN Bottom line screen buffer
$2090 DPT_SAVE Temporary area to save screen
$20B0 KBT_BUFF Type ahead buffer
$20C0 KBB_CLIK Length of keyboard click
$20C1 KBB_PKOF Set for pack switch off in KB_TEST
$20C2 KBB_CAPK Caps key
$20C3 KBB_NUMK Nums key
$20C4 KBB_SHFK Shift key, clear to enable shift key
$20C5 TMB_YEAR Current year 0-99
$20C6 TMB_MONS Current month 0-11
$20C7 TMB_DAYS Current day 0-31
$20C8 TMB_HOUR Current hour 0-23
$20C9 TMB_MINS Current minute 0-59
$20CA TMB_SECS Current seconds 0-59
$20CB TMW_FRAM Frame counter
$20CD TMW_TCNT The auto-switch off time out in seconds
$20CF UTT_TBUF Temporary buffer, used in UT_DISP
$20D6 PKB_IMSK Save interrupt mask while blowing
$20D7 PKT_ID 4 pack ID headers, 10 bytes each
$20FF RTT_NUMB 10 memory slots for calculator (each 8 long)
$214F DVT_SPAR $38 byte reserved for I/O drivers
$2187 RTB_BL Run time buffer length
$2188 RTT_BF Run time buffer ($100 long)
$2288 MTT_WBUF General purpose buffer for maths + overflow
$22C8 RTB_FL Find buffer length
$22C9 RTT_FF Find buffer
$22E9 RTT_FILE 4 file control blocks (each $04 long)
$22F9 AMT_TAB Alarm table, 6 bytes per alarm
$2329 DVA_BOT LA/OS only : lowest addr used in low RAM $0400-$1FFF
$232B DVA_TOP LA/OS only : highest addr ... ...
$232D - $2324 reserved to PSION
$2335 AMB_EI If set then alarm checking is enabled
$2336 AMT_T0 Temporary variable used checking for alarms
$233C AMT_T1 " " " " " "
$2342 AMT_T2 " " " " " "
$2348 AMW_R1 " " " " " "
$234A AMB_DOIT If set then does alarm check on next interrupt
$234B ITA_UVC Table user vector
$234D ITT_REGS Table registers
$236D ITT_STAK Table stack
$23AD IMB_SSGN Saved sign
$23AE FNT_SEED Random number seed
$23B5 ACW_STOP Q code offset to stop at
$23B7 ACW_XTCD External O code size
$23B9 ACT_DDAT Global & local data sizes
$23BD ACT_NVAR Declared variables count
$23C1 ACT_BRAN Current branch label number
$23C9 ACT_PSYM Symbol table data pointer
$23CD LXA_CEND End of text pointer
$23CF LXA_STRT Start of current token
$23D1 LXB_STOK Saved token for un-lex
$23D2 LXB_SCLA Saved class for un-lex
$23D3 LXB_FTYP Function type
$23D4 LGB_FIXP Decimal places in calculator display
$23D5 LGB_NL Last procedure name length
$23D6 LGT_NF Last procedure name
$23E0 LGB_LANT Language type
$23E1 LGB_MENU Set to ignore TRAN option after editing
$23E2 RTA_1VCT Extension O code operator code
$23E4 UTW_RETA Return address used in UT_DDSP
$23E6 PKB_OVBL Overblow factor
$23E7 BTA_VECT Vector to vector table
Overlayed against MTT_WBUF:
$2288 AMT_NOW Copy of current time when checking alarms
$228E AMT_WEEK Time one week from now
The addresses between $23F2 and RAMFREE are used by the operating system
but are unpublished and should not be used.
_______
6.5.1.4 BUFFERS -
________
6.5.1.4.1 RTT_FILE -
RTT_FILE contains 4 file control blocks with the following structure:
Byte 0 Type, the type of that file, between $90 and $FE
Byte 1 Device on which file exists (0 for A:, 1 for B: and so on)
Word 2 Current record number
______
6.5.1.4.2 PKT_ID -
Contains 4 pack IDs, these are the 10 bytes header of each pack. See
Chapter 9 for details.
________
6.5.1.4.3 RTT_NUMB -
Each memory, M0 to M9 has 8 bytes allocated to it. The format of each is
the same format as a floating point number.
_______
6.5.1.4.4 AMT_TAB -
Six bytes for each entry in the format:
Byte 0 Year
Byte 1 Month
Byte 2 Day
Byte 3 Hour
Byte 4 Minutes
Byte 5 Zero if cancelled
1 no repeat
2 weekly, 3 daily, 4 hourly repeat
______
6.5.1.5 TIMING -
There are a number of variables which are measured in ticks. A tick is
(KBW_TDEL + 35) / 921600. The default value of KBW_TDEL is $B3DD, which
gives a tick of 50 milliseconds delay.
________________
6.5.1.6 I/O DRIVER SPACE -
At DVT_SPAR $38 bytes are reserved for I/O drivers. This space is
allocated by PSION to officially supported devices. This area may not be
used for any other purpose.
_________
6.5.1.7 COLD BOOT -
On a cold boot the following steps involving memory are executed:
1. RAM test - the RAM is tested first with $AA, and then with $55.
2. The top of memory is determined.
3. ALA_FREE is set to the end of variables.
4. RTA_SP is set to $100 below the top of memory.
5. The top level menu is initialised in the MENUCELL
6. Devices are booted into PERMCELL.
7. Initialise DATACELL.
8. Initialise DIRYCELL.
For a complete description of booting see Chapter 5.
___________
6.5.2 FREE MEMORY
Memory between the two addresses ALA_FREE and RTA_SP is free. Every time
an OPL operand or operator is executed, it checks that at least $100 bytes
is free - no operand or operator can increase the size of the stack by more
than $100 bytes. Before increasing the size of an allocated cell the
allocator checks there will be, at the end of the operation, at least $100
bytes free.
_________
6.5.2.1 ALLOCATOR -
There are 32 allocator cells available; the first 16 are pre-allocated to
the operating system, the others are available for applications.
The allocator scheme is very simple. Each cell has one word associated
with it (pointed to by a tag). If the cell is assigned it gives the start
address of the cell, otherwise it is zero. The first non-zero word
following gives the length of the cell by subtraction. When a cell is
grown all the allocated cells above it are moved up in memory, when a cell
is shrunk all the cells above are moved down.
You may deduce from this that frequent growing and contracting of cells can
slow an application down considerably.
If any cell is altered in size, for example by calling one of the allocator
functions or by adding or deleting a record from device A:, any of the
other cells may move. It is therefore essential to re-calculate the base
address of a cell every time something could have moved it.
Tag Name Description of cell
--- ---- -------------------
$2000 PERMCELL Permanent cell - for device driver code & data
$2002 MENUCELL Top level menu cell
$2004 DIRYCELL Diary cell
$2006 TEXTCELL Language text cell - used when translating
$2008 SYMBCELL Symbol table cell - used when translating
$200A GLOBCELL Global record cell - used when translating
$200C OCODCELL QCODE output cell - used when translating
$200E FSY1CELL Field name symbol table 1 - only used in OPL
$2010 FSY2CELL Field name symbol table 2 - only used in OPL
$2012 FSY3CELL Field name symbol table 3 - only used in OPL
$2014 FSY4CELL Field name symbol table 4 - only used in OPL
$2016 FBF1CELL File buffer 1 - only used in OPL
$2018 FBF2CELL File buffer 2 - only used in OPL
$201A FBF3CELL File buffer 3 - only used in OPL
$201C FBF4CELL File buffer 4 - only used in OPL
$201E DATACELL Database cell - device A:
$2020 - $203E Free for use by applications
When device drivers are loaded in, the code is fixed up and becomes
non-relocatable. So once a device is loaded it cannot be moved which is
why it is placed in the lowest cell.
When the Organiser is re-booted (by pressing the ON/CLEAR key at the top
level) it first removes all devices currently loaded and then boots in all
the device drivers from the devices B:, C: and D:.
________
6.5.2.2 LANGUAGE -
OPL is a stack based language. Almost every operand/operator has some
effect on the stack size. The one exception is file buffers. When a file
is opened the file buffer cell is grown to $100 and the field names' cell
grown to take the field names. When a file is closed both these cells are
reduced back to zero length.
For details of the buffer structure see section 17.2.10.
When OPL starts running, the stack is initialised to BTA_SBAS. If this is
changed, the next time OPL is run it will start from the new address. The
only thing which resets BTA_SBAS is resetting the machine.
________________
6.5.2.3 PERMANENT MEMORY -
For many applications it is sufficient to have permanent data in an
allocated cell and to access it indirectly from the address of the cell.
For other applications it is desirable to be able to use a permanent fixed
area of memory either for machine code or for data. An application can
grab permanent memory in two different ways. It must be noted that if a
number of applications use these techniques there is no reliable way to
free the space selectively .
1. Lower BTA_SBAS by the amount of memory you want (this can be done
in an OPL procedure).
2. Grow PERMCELL by the amount of memory you want, then poke a new
higher address to ALA_FREE. Note that all devices should be
re-booted after this as their internal addresses will no longer be
valid.
The only way to automatically reset these two allocations are a TOP LEVEL
RESET or, of course, a COLD BOOT.
_______________
6.6 SYSTEM SERVICES
_______
6.6.1 AL$FREE
VECTOR NUMBER: 000
INPUT PARAMETERS: X register - Tag of the cell to be freed.
OUTPUT VALUES: None.
DESCRIPTION
Frees the cell whose tag is in the X register. A cell is freed by
making its entry zero in the allocator table.
This is the reverse of AL$GRAB.
EXAMPLE
To free a cell whose tag is held in CELL:
LDX CELL ; Get the tag
OS AL$FREE
ERRORS: None.
BUGS
If the value of X is not in the correct range ($2000-$203E) results
will be unpredictable and potentially catastrophic.
The user may write his own shell to protect against this bug.
If the cell is already free no harm is done.
_______
6.6.2 AL$GRAB
VECTOR NUMBER: 001
INPUT PARAMETERS: D register - Initial size of cell in bytes.
OUTPUT VALUES: X register - The tag of the cell.
DESCRIPTION
Allocates a new memory cell.
Returns the tag (or address) of the 2 byte location containing the
address of the base of the allocated cell.
As the allocator may move the base of a cell any time a request is made
to the allocator, the base addresses of all cells are held in the table
of addresses starting at ALA_BASE. Thus if the tag returned from this
call is stored in a memory address called CELL then the following code
should always be used to get the base of the memory cell into a memory
address called BASE.
LDX CELL ; Load the tag
LDX 0,X ; Get the de-referenced address
STX BASE ; Save the real address
This procedure should be called any time a routine is called which
could cause the allocator to move the memory cells around.
EXAMPLE
To allocate a new cell of size 100 bytes:
LDD #100 ; The initial size of the cell
OS AL$GRAB
BCS ERROR ; Report error
STX CELL ; Save the tag
REGISTERS CORRUPTED: A,B and X
LOCATIONS CORRUPTED: UTW_S0
ERRORS: ER_AL_NC - No more cells can be allocated.
ER_AL_NR - Not enough memory for the cell to
be allocated.
_______
6.6.3 AL$GROW
VECTOR NUMBER: 002
INPUT PARAMETERS: D register - Number of bytes to grow cell by.
X register - Tag of the cell to be grown.
UTW_S0 - Offset in cell to make space.
OUTPUT VALUES: None
DESCRIPTION
Increase the cell whose base address is held in the two byte address
pointed at by the X register by the number of bytes in the D register.
The gap is opened UTW_S0 bytes from the start of the cell.
The base of the cell will not move as the extra space is added after
the start of the cell. However all cells which come after this cell
will be moved to make room for the extra space.
EXAMPLE
For example, to grow the cell whose tag is held in CELL by 6 bytes at
the
end of the cell:
LDX CELL ; Get the tag
OS AL$SIZE
STD UTW_S0: ; Offset for grow
LDX CELL ; Get the tag
LDD #6 ; Amount to grow cell
OS AL$GROW
BCS ERROR ; Report error
ERRORS: ER_AL_NR - Not enough memory for the cell to
be allocated.
BUGS
If the value of X is not in the correct range ($2000-$203E) results
will be unpredictable and potentially catastrophic.
If the offset in UTW_S0 is bigger than the cell, the grow will still be
performed with unpredictable and potentially catastrophic results.
The user may write his own shell to protect against these bugs.
_______
6.6.4 AL$REPL
VECTOR NUMBER: 003
INPUT PARAMETERS: D register - Size of current item.
X register - Tag of the cell to be shrunk
or expanded.
UTW_S0 - Offset in cell to start shrink
or expand.
UTW_S1 - Size of new item.
OUTPUT VALUES: None
DESCRIPTION
Increase or decrease the cell whose base address is held in the two
byte address pointed at by the X register according to the two sizes in
the D register and location UTW_S1.
The cell is grown or shrunk accordingly by calls to AL$GROW or AL$SHNK.
The base of the cell will not move as the extra space is added or
deleted after the start of the cell. However all cells which come
after this cell may be moved.
EXAMPLE
For example, to replace 8 bytes of a cell by 6 bytes at 10 bytes from
the start of the cell:
LDX #10
STX UTW_S0: ; Offset to replace
LDX #6 ; Number of bytes in new item
STX UTW_S1:
LDX CELL ; get the tag
LDD #8 ; Number of bytes in current item
OS AL$REPL
BCS ERROR ; Report errors
ERRORS: ER_AL_NR - Not enough memory for the cell to
be allocated.
BUGS
If the value of X is not in the correct range ($2000-$203E) results
will be unpredictable.
If the offset in UTW_S0 is bigger than the cell, the shrink/grow will
still be performed with unpredictable results.
The user may write his own shell to protect against these bugs.
_______
6.6.5 AL$SHNK
VECTOR NUMBER: 004
INPUT PARAMETERS: D register - Number of bytes to shrink the
cell by.
X register - Tag of the cell to be shrunk.
UTW_S0 - Offset in cell to start shrink.
OUTPUT VALUES: None
DESCRIPTION
Decrease the cell whose base address is held in the two byte address
pointed at by the X register by the number of bytes in the D register.
The gap is closed at UTW_S0 bytes from the start of the cell.
The base of the cell will not move as the extra space is deleted after
the start of the cell. However all cells which come after this cell
will be moved to take up the extra space.
EXAMPLE:
For example, to shrink a cell whose tag is held in CELL by 6 bytes from
the beginning:
LDX #0
STX UTW_S0: ; Offset for shrink
LDX CELL ; get the tag
LDD #6 ; amount to shrink cell
OS AL$SHNK
ERRORS: None
BUGS
If the value of X is not in the correct range ($2000-$203E) results
will be unpredictable and potentially catastrophic.
If the offset in UTW_S0 is bigger than the cell, the shrink will still
be performed with unpredictable and potentially catastrophic results.
The user may write his own shell to protect against these bugs.
_______
6.6.6 AL$SIZE
VECTOR NUMBER: 005
INPUT PARAMETERS: X register - Tag of the cell to be sized.
OUTPUT VALUES: D register - Size of cell in bytes.
DESCRIPTION
Return the size of the cell whose base address is held in the two byte
address pointed at by the X register.
EXAMPLE
For example, to find the size of a cell:
LDX CELL ; get the tag
OS AL$SIZE
STD CELLSIZ ; Save the cell size
ERRORS: None
BUGS
If the value of X is not in the correct range ($2000-$203E) results
will be unpredictable.
_______
6.6.7 AL$ZERO
VECTOR NUMBER: 006
INPUT PARAMETERS: X register - Tag of the cell to be zeroed.
OUTPUT VALUES: None
DESCRIPTION
Decreases the size of a cell to zero but does not de-allocate the cell.
EXAMPLE
For example, to zero the permanent (device) cell whose tag is $2000:
LDX $2000 ; set X to the device tag
OS AL$ZERO
ERRORS: None
BUGS
If the value of X is not in the correct range ($2000-$203E) result will
be unpredictable.