The PSION Organiser II Homepage
 
Home
Technical Reference
Introduction
System
Versions
Operating
System
Memory Usage
Filing System
System Timing
System Board
Power Supply Board
Display
Keyboard
Interface Slots
Packs
General
Flashpacks
Low Level
Access
External
Interfacing
Comms Link
Psion Link
Protocol
Utility System
Services
Built-in
Applications
LZ Passwords
Programming
Language
General
Q-Code
Table
Interpreter
System Services
 

Technical Reference Manual

MEMORY USAGE

INTRODUCTION

 

MEMORY MAP

 

RAM MEMORY

NON-RAM MEMORY MAP

 

MEMORY USAGE

SYSTEM SERVICES

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.

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:

  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.

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 .

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

 
first previous   next top