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.

MEMORY MAP

Model CM

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

$FFFF   I-------------------------------I
        I          System ROM           I
$8000   I-------------------------------I
        I           Not Used            I
$6000   I-------------------------------I
        I       Processor Stack         I
$5F00   I-------------------------------I
        I        Language Stack         I
        I         (grows down)          I
        I                               I
        I                               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

$FFFF   I-------------------------------I
        I                               I
$C000   I                               I
        I          System ROM           I
        I                               I
$8000   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

Model LA (multilingual)

$FFFF   I-------------------------------I
        I       System ROM fixed        I
$C000   I-------------------------------I
        I          System ROM           I
        I         bank switched         I
$8000   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

Model POS-350

$FFFF   I-------------------------------I
        I                               I
        I         System ROM            I
        I                               I
$8000   I-------------------------------I I-------------------------------I
        I       System Variables        I I                               I
$7F00   I-------------------------------I I         bank switched         I
        I        Language Stack         I I           extra RAM           I
        I         (grows down)          I I                               I
        I                               I I                               I
$4000   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

Models LZ and LZ 64

$FFFF   I-------------------------------I
        I       System ROM fixed        I
$C000   I-------------------------------I
        I         System ROM            I
        I        bank switched          I
$8000   I-------------------------------I I-------------------------------I
        I       System Variables        I I                               I
$7F00   I-------------------------------I I         bank switched         I
        I        Language Stack         I I           extra RAM           I
        I         (grows down)          I I          (LZ64 only)          I
        I                               I I                               I
$4000   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

RAM MEMORY

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 setup 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).

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 a few differences between device A: and devices B: & C:

The pack header of device A: is undefined.
When an item is deleted the space is recovered (as in a rampack).
Uses PKW_CMAD instead of PKW_CPAK.
The pack size is variable.
Accessing is faster.
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.

NON-RAM MEMORY MAP

In the memory map certain areas contain system registers and I/O rather than RAM.

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 System Board 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.

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.

MEMORY USAGE

OPERATING SYSTEM

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)

SYSTEM VARIABLES

The System Variables are described in detail at the System Variables Page.

BUFFERS

RTT_FILE ($22E9) - File Control Blocks

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

PKT_ID ($20D7) - Pack IDs

Contains 4 pack IDs, these are the 10 bytes header of each pack. See Datapack ID String for details.

RTT_NUMB ($20FF) - Calculator Variables

Each memory, M0 to M9 has 8 bytes allocated to it. The format of each is the same format as a floating point number.

AMT_TAB ($22F9) - Alarm Table

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 canceled, Repeat flags

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.

I/O DRIVER SPACE

At DVT_SPAR ($214F) 56 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.

FREE MEMORY

Every time an OPL operand or operator is executed, it checks that at least 256 bytes is free - no operand or operator can increase the size of the stack by more than 256 bytes. Before increasing the size of an allocated cell the allocator checks there will be, at the end of the operation, at least 256 bytes free.

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 rebooted (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 happens if the language is changed on multilingual organisers.

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 256 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 Records and Fields.

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.

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 .

Lower BTA_SBAS by the amount of memory you want (this can be done in an OPL procedure).
Grow PERMCELL by the amount of memory you want, then poke a new higher address to ALA_FREE. Note that all devices should be rebooted 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.

SYSTEM SERVICES

Services that change the size of a cell will not move the base of the cell. However all cells which come after this cell will be moved.

Warning: The parameters are not checked. If incorrect values for tag or offset are supplied results will be unpredictable and potentially catastrophic. The user may write his own shell to protect against this bug.

AL$FREE

Frees a cell. A cell is freed by making its entry zero in the allocator table. This is the reverse of AL$GRAB.

AL$GRAB

Allocates a new memory 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.

AL$GROW

Increase a 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.

AL$REPL

Increase or decrease a cell.

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.

AL$SHNK

Decrease a cell.

AL$SIZE

Return the size of a cell.

AL$ZERO

Decreases the size of a cell to zero but does not de-allocate the cell.