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.

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

Models CM and XP:


       $FFFF   I-------------------------------I
               I          System ROM           I
       $8000   I-------------------------------I
               I           Not Used            I
$6000  $4000   I-------------------------------I
  XP     CM    I       Processor Stack         I
$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            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
 

Model LA

                                                          multilingual LA
       $FFFF   I-------------------------------I I-------------------------------I
               I                               I I       System ROM fixed        I
       $C000   I                               I I-------------------------------I
               I          System ROM           I I          System ROM           I
               I                               I I         bank switched         I
       $8000   I-------------------------------I I-------------------------------I
               I       Processor Stack         I
       $7F00   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         low ram area          I
               I       used for devices        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

Models POS-350, LZ, LZ64 (LP)

       $FFFF   I-------------------------------I
               I       System ROM fixed        I
       $C000   I-------------------------------I
               I         System ROM            I
               I        bank switched          I
               I       (except POS-350)        I
       $8000   I-------------------------------I I-------------------------------I
               I       System Variables        I I                               I
               I       (except POS-350)        I I         bank switched         I
       $7F00   I-------------------------------I I           extra RAM           I
               I        Language Stack         I I     POS-350 and LZ64 only     I
               I         (grows down)          I I                               I
               I                               I I                               I
       $4000   I-------------------------------I I------------------------------ I
               I                               I
               I          (grows up)           I
               I       Allocated Cells         I
               I...............................I
               I       System Variables        I
               I...............................I
               I        Processor Stack        I
               I...............................I
               I       System Variables        I
       $2000   I-------------------------------I
               I         low ram area          I
               I       used for devices        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:

The top $100 bytes of RAM is reserved for the processor stack in models CM, XP and LA. In models POS-350, LZ and LZ64 the processor stack is situated inmidst the system variables (BTT_MSTACK). Models LZ and LZ64 use the top $100 bytes for additional system variables.

The RAM in an POS-350 and an LZ64 is arranged in 3 (LZ64) or 5 (POS-350) "banks" of 16K which are switched as required.On the LZ64 and the POS-350, the 16K RAM between addresses $4000 and $8000 is used in the same way as on the CM/XP/LZ models, for example to hold the current diary (and on the LZ, the current notepad), except that "PACK A:" starts in the highest RAM bank and, as it grows, works its way through the other banks and then into the main bank which the other functions (diary etc) use. PEEKing and POKEing between addresses $4000 and $8000 on an LZ64 or an POS-350 will only access the bank which is currently selected, and is therefore not recommended.

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 LZ, P350 and multi-lingual XP need more control lines for their memory management, and for this the following semi-custom addresses are used:

$0360   SCA_BANKRESET           Reset ROM and RAM to first banks (LZ/P350/M-XP)
$03A0   SCA_NEXTRAM             Select next RAM bank (LZ/P350)
$03E0   SCA_NEXTROM             Select next ROM bank (LZ/M-XP).  

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 (except that LZ only ignores only bottom 5 bits).

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


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
         ca     calculator (LZ)
         di     diary
         dp     display
         dv     devices
         ed     edit
         er     error handler
         fl     files
         fn     floating poin number functions
         im     maths table actions
         it     table routines
         kb     keyboard
         lg     language translator
         lx     language lexer
         mn     menu
         mt     maths BCD routines
         nt     notepad (LZ)
         pk     datapacks
         rt     run time
         tl     top level
         tm     time
         ut     utilities
         wl     world (LZ)
         xf     extra file functions (LZ)
         xt     extra utilities (LZ)



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 if 2 lines, 0-79 if 4 line mode on an LZ)
$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 (on 2-line machine, or on LZ when in 2-line mode)
$2080   DPT_BLIN        Bottom line screen buffer (on 2-line machine, or on LZ when in 2-line mode)
$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:. This also happenes if the language is changed on multilingual organisers.


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.