Index | PAL Intro | Commands | Registers | Indices | Stack | Macros | Classes | Attributes | Errors

pal_registers - Introduction to PAL registers

CONTENTS

Description
Special Registers
Accumulator
Test Registers
See Also
Author

Registers in PAL are pointers to data units. They may be used in any parameter position to any PAL instruction, in place of indices when required. Be careful to ensure that the type of data pointed to by the register, matches the type of data expected by the instruction. Where a mismatch occurs, an InvalidArgument runtime error will be generated.

There are 16 addressable registers P0 to P15, and 10 special registers (see SPECIAL REGISTERS). Each numbered register can be set to point to a data unit of one of the following types:

PSUNIT_TYPE_NULL (0x00)
	Empty unit, assigned using the NULL special register.
PSUNIT_TYPE_NODE (0x01)
	Pointer to a node in the nexus, assigned using the syntax ![node], where node is a relative or absolute object address in dot-notation.
PSUNIT_TYPE_STRING (0x04)
	Pointer to unique string of bytes of arbitrary length. This data type can be used to represent any kind of data, usually in transit from one operation to another, and may be used in place of any text argument. If a byte string is no longer required, the register must be cleared using the reg/clr instruction, otherwise memory will be leaked. See reg_clr(5). Alternatively, push the register onto the stack and flush the stack.
PSUNIT_TYPE_PALCODE (0x05)
	Pointer to PAL code, identified by a code label, and assigned using the syntax &[.code_label], where code_label is the name of the code label to point to.
PSUNIT_TYPE_PALDATA (0x06)
	Pointer to a PAL data segment, identified by a data label, and assigned using the syntax &[~data_label], where data_label is the name of the data label to point to.
PSUNIT_TYPE_PALTEXT (0x07)
	Pointer to arbitrary text in a binary file, assigned using the syntax [text], where text is any ASCII character string. Backslashes protect the next character from special interpretation, so use \] for a close square bracket, and \\ for a backslash.
PSUNIT_TYPE_RAWIDX (0x08)
	A raw index, assigned using the syntax #index, where index is a 32-bit unsigned integer. If index begins 0x, the value is interpreted as hexadecimal (base 16). If index begins 0, the value is interpreted as octal (base 8). If index begins with neither 0x nor 0, the value is interpreted as decimal (base 10).
PSUNIT_TYPE_WALKER (0x09)
	Pointer to a walker, initialised using reg/load indirect addressing. See reg_load_walker(5).
PSUNIT_TYPE_LOCK (0x0a)
	A stack lock marker, assigned when a lock is peeked on the stack. See pal_stack(5).
PSUNIT_TYPE_INTLOCKL (0x0b)
	An internal stack lock marker, assigned when subroutines are branched to using local/jsr. Behaves exactly like PSUNIT_TYPE_LOCK except they cannot be removed from the stack programmatically, and will only be removed when the branch returns.
PSUNIT_TYPE_INTLOCKF (0x0c)
	Same as PSUNIT_TYPE_INTLOCKL except generated by function calls.
PSUNIT_TYPE_OBJEDIT (0x0d)
	An object edit buffer which may contain a list of classes and attributes to add, delete or modify. See obj_def(5), obj_clone(5) and obj_edit(5).
PSUNIT_TYPE_CLASSDEF (0x0e)
	A pointer to a class definition in the schema, assigned by class/load. See class_load(5).
PSUNIT_TYPE_ATTRDEF (0x0f)
	A pointer to an attribute definition in the schema, assigned by attr/load. See attr_load(5).
PSUNIT_TYPE_READSEG (0x10)
	A data segment read structure, initialised using reg/load indirect addressing. See reg_load_segment(5).
PSUNIT_TYPE_READTAB (0x11)
	A data table read structure, initialised using reg/load indirect addressing. See reg_load_table(5).
PSUNIT_TYPE_READCLASS (0x12)
	An object class read structure, initialised using class/load indirect addressing. See class_load(5).
PSUNIT_TYPE_READATTR (0x13)
	An object attribute read structure, initialised using attr/load indirect addressing. See attr_load(5).
PSUNIT_TYPE_READVAL (0x14)
	An attribute copy read structure, initialised using attr/copy indirect addressing. See attr_copy(5).
PSUNIT_TYPE_XVALUE (0x15)
	Pointer to an encoded attribute value that is currently not attached to an object. Like PSUNIT_TYPE_STRING, this data type can be used to represent any kind of data, usually in transit from one operation to another, and may be used in place of any text argument. If an encoded value is no longer required, the register must be cleared using the reg/clr instruction, otherwise memory will be leaked. See reg_clr(5). Alternatively, push the register onto the stack and flush the stack.
PSUNIT_TYPE_FPARS (0x16)
	A data structure containing a definition of formal parameters accepted by a function.
PSUNIT_TYPE_LIST (0x17)
	Pointer to a list sequence, initialised using list/def. See list_def(5).

The following keywords may be used in place of read registers:

A	The Accumulator. See ACCUMULATOR.
NULL	Return an empty data unit.
PULL	Pull the last item off the program stack, and return it. If the topmost item on the stack is a lock, a PULL will cause a StackLocked runtime error. You must instead use a PEEK if you wish to test to see that it is a lock. If the topmost item on the stack has allocated memory, a PULL will cause a BadStack runtime error. This is to prevent memory leaks. Use the stack/pull instruction instead to pull this item off the stack. There are a few notable exceptions to this rule, as the func/rtn, reg/load, reg/clr and stack/push instructions will accept a PULL. If the stack is empty, a PULL will cause a StackEmpty runtime error.
PEEK	Return the last item from the program stack, but do not pull it off the stack. This is normally used for testing to see if the topmost item is a lock. If the topmost item on the stack has allocated memory, and the instruction would store the pointer in another location, or modify or destroy the pointer, then a PEEK will cause a BadStack runtime error. This is to prevent pointer duplication and corruption. If the stack is empty, a PEEK will cause a StackEmpty runtime error.
PCTX	Return a pointer to the context root.
LOCK	Return a stack lock unit, usually used for comparing with a value just peeked on the stack.
SCMP	Return the current value of the SCMP register. See TEST REGISTERS below.
SFLG	Return the current value of the SFLG register. See TEST REGISTERS below.
PERR	Return a pointer to the last error object.
The following keywords may be used in place of write registers:
A	The Accumulator. See ACCUMULATOR.
NULL	Do nothing (discard the data).
PUSH	Push the data onto the program stack.
PCTX	Set the context root to the given node.
SCMP	Set the value of the SCMP register. See TEST REGISTERS.
SFLG	Set the value of the SFLG register. See TEST REGISTERS.

The Accumulator is a special register that can store a 32-bit integer and is equivalent to the data type PSUNIT_TYPE_RAWIDX. It is represented by the symbol A which may be used in any argument position where a numbered register is valid.

Some instructions, especially the opa maths instructions (see op_maths(5)), are designed to be used with the Accumulator and will run faster as a result.

The SCMP and SFLG special registers are 32-bit integers used to indicate the result of a number of test instructions, such as reg/cmp, attr/test and class/test. See reg_cmp(5). The SCMP register contains the result of the last test. Test results can be one of the following:

PSCMP_NOTEQUAL (no bits set)
	The compared arguments were not equal.
PSCMP_EQUAL (bit 0 set)
	The compared arguments were equal.
PSCMP_LESS (bit 1 set)
	The first argument was less than the second (either by value or lexicographical ordering).
PSCMP_GREATER (bit 2 set)
	The first argument was greater than the second (either by value or lexicographical ordering).

The SFLG register contains the last 32 equality tests with the most recent result in the first bit. Whenever a test is performed, SFLG is shifted left by one position and bit 0 is copied from SCMP.

pal_intro(5), pal_commands(5), pal_stack(5), pal_indices(5),
PROSE Assembly Language at prose.sourceforge.net.

Copyright (c) 2002-2011 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.