Functions
void	sat3_poke (SAT_OBJECT sat_addr, unsigned int val, int nibbles)
	Poke up to 8 nibbles of data to Saturn domain.
unsigned int	sat3_peek (SAT_OBJECT sat_addr, int nibbles)
	Peek up to 8 nibbles of data from Saturn domain.
void	sat3_memmove (SAT_OBJECT dest, SAT_OBJECT source, int nibbles)
	Move arbitrary number of nibbles from one location to another.
void	sat3_memset (SAT_OBJECT dest, int value, int nibvalue, int nibbles)
	Fill an area of memory with the given nibble pattern.
SAT_OBJECT	sat3_alloc (SAT_OBJECT where, int nibbles)
	Allocate arbitrary number of nibbles at the specified location.
int	sat3_free (SAT_OBJECT block)
	Releases a block of memory allocated by sat3_alloc.
SAT_OBJECT	sat3_copyobject (SAT_OBJECT dest, SAT_OBJECT source)
	Copy an object to the specified location.
int	sat3_sizeof (SAT_OBJECT obj)
	Get size in nibbles of a calculator object.
int	sat3_getfreetempob ()
	Return the amount of usable tempob memory, in nibbles.
int	sat3_getfreeuserob ()
	Return the amount of usable userob memory, in nibbles.
void	sat3_garbcol ()
	Perform a garbage collection in TEMPOB memory.

Detailed Description

This group includes all functions used to manipulate Saturn memory directly. Most of them are needed only for advanced users.

Function Documentation

SAT_OBJECT sat3_alloc	(	SAT_OBJECT	where,
		int	nibbles
	)

Allocate arbitrary number of nibbles at the specified location.

This function allocates memory either from the Saturn memory or from the C-heap, as requested.

Parameters:

where	Defines where to allocate memory from. Must be one of the following constants: ALLOC_HEAP Allocates from the C-heap using malloc() ALLOC_TEMPOB Allocates memory from the TEMPOB calculator area
nibbles	Number of nibbles to allocate.

Returns:: Allocated address in SAT_OBJECT format, or zero if it fails.

See also:: sat3_free SAT_OBJECT

SAT_OBJECT sat3_copyobject	(	SAT_OBJECT	dest,
		SAT_OBJECT	source
	)

Copy an object to the specified location.

Copy a valid saturn object from one location to another. If destination is ALLOC_TEMPOB or ALLOC_HEAP, memory will be allocated to contain the new object. When a SAT_OBJECT is given, the copy may fail if there's not enough allocated space at the destination. It's the user responsibility to verify the copy was successful by checking the returned value.

Parameters:

dest	Where to copy to. Can be a SAT_OBJECT or one of the following constants: ALLOC_HEAP Allocates from the C-heap using malloc() ALLOC_TEMPOB Allocates memory from the TEMPOB calculator area
source	Object to copy. Must be a valid saturn object.

Returns:: Destination object, or zero if it fails (not enough memory).

See also:: sat3_memmove SAT_OBJECT

int sat3_free ( SAT_OBJECT block )

Releases a block of memory allocated by sat3_alloc.

If the allocated block is in TEMPOB, it verifies if the block is not referenced and then it removes the block from memory (increasing the available memory). If the allocated block is in the C heap, it calls free() to release its memory.

Parameters:

block Memory block to release

Returns:: It returns BLOCK_FREE on success, BLOCK_USED if block is referenced or INVALID_PTR if error.

See also:: sat3_alloc sat3_getfreetempob SAT_OBJECT

void sat3_garbcol ( )

Perform a garbage collection in TEMPOB memory.

The user doesn't need to call this function explicitly unless intensive work was done in TEMPOB and cleanup is needed before program exit. However, every time an arbitrary-sized composite object is allocated directly in TEMPOB, this function must be called to shrink such objects to the proper size.

int sat3_getfreetempob ( )

Return the amount of usable tempob memory, in nibbles.

The amount of memory returned depends on how the HPGCC program was configured to run, and does not necessarily matches the available memory obtained from the calculator.

See also:: layout

int sat3_getfreeuserob ( )

Return the amount of usable userob memory, in nibbles.

The amount of memory returned depends on how the HPGCC program was configured to run, and does not necessarily matches the available memory obtained from the calculator. This function also gives the free space available for stack growth, since USEROB and the stack allocate memory from the same location.

See also:: layout

void sat3_memmove	(	SAT_OBJECT	dest,
		SAT_OBJECT	source,
		int	nibbles
	)

Move arbitrary number of nibbles from one location to another.

This function moves (copies) the specified number of nibbles from source to destination. Automatically chooses direction of copy to avoid overwriting if dest and source regions overlap.

Parameters:

dest	Destination address in SAT_OBJECT format.
source	Source address in SAT_OBJECT format
nibbles	Number of nibbles to move

See also:: sat3_memset sat3_poke sat3_peek SAT_OBJECT

void sat3_memset	(	SAT_OBJECT	dest,
		int	value,
		int	nibvalue,
		int	nibbles
	)

Fill an area of memory with the given nibble pattern.

Use this function to fill an area of memory with a given number. The fill number can have a variable number of nibbles.

Parameters:

dest	Destination address in SAT_OBJECT format.
value	32-bit number to use as fill
nibvalue	Number of significant nibbles in value
nibbles	Number of nibbles to fill

See also:: sat3_memmove sat3_poke sat3_peek SAT_OBJECT

unsigned int sat3_peek	(	SAT_OBJECT	sat_addr,
		int	nibbles
	)

Peek up to 8 nibbles of data from Saturn domain.

This function reads up to 32 bit data in 4 bit chunks (nibbles) from Saturn memory.

Parameters:

sat_addr	Address to read from in SAT_OBJECT format.
nibbles	Number of nibbles to read.

Returns:: Nibbles read, in LSB (little endian) format, packed in a 32-bit number. If less than 8 nibbles were read, the rest are zero-padded.

See also:: sat3_poke sat3_memmove SAT_OBJECT

void sat3_poke	(	SAT_OBJECT	sat_addr,
		unsigned int	val,
		int	nibbles
	)

Poke up to 8 nibbles of data to Saturn domain.

This function stores up to 32 bit data in 4 bit chunks (nibbles) to Saturn memory.

Parameters:

sat_addr	Address to write to in SAT_OBJECT format.
val	Nibbles to write, LSB (little endian) format.
nibbles	Number of nibbles to write

See also:: sat3_peek sat3_memmove SAT_OBJECT

int sat3_sizeof ( SAT_OBJECT obj )

Get size in nibbles of a calculator object.

Parameters:

obj	Object to determine size. Must be a valid object.

Returns:: Total size of object in nibbles, including prolog.

Memory management

Functions

Detailed Description

Function Documentation