Main Page | Data Structures | File List | Globals

saturn.h File Reference

Saturn domain "hacking" and RPL stack manipulation library for the HP-49g+ calculator. More...


Data Structures

struct  _sat_cpu
 The emulated Saturn CPU as a memory area in ARM domain. More...
struct  _sat_stack_element
 A descriptor for an RPL stack element in Saturn notation. More...
struct  _sat_stack_data
 Data structure, that models a single stack element. More...

Defines

#define SWAP4(x)   (((x) << 4) | ((x) >> 4))
 Swap low and high nibbles in a byte.
#define ALIGN(x, a)   (((unsigned)(x)+(a)-1) & (~((unsigned)(a)-1)))
 Align an address 'x' to a 'a' bit boundary.
#define BOOL   int
 Standard definition for BOOLEAN type.
#define FALSE   0
 The BOOLEAN constant FALSE.
#define TRUE   !FALSE
 The BOOLEAN constant TRUE.
#define SAT_STACK_BIAS   1
 How many stack levels are used by the launcher.
#define SAT_PROLOGUE_ZINT   0x2614
 Saturn data prologue: ZINT (Typical Exact Integer).
#define SAT_PROLOGUE_STRING   0x2a2c
 Saturn data prologue: STRING.
#define SAT_PROLOGUE_REAL   0x2933
 Saturn data prologue: REAL.
#define SAT_PROLOGUE_UINT   0x2a4e
 Saturn data prologue: UINT.
#define SAT_DATA_TYPE_INT   28
 HP calculator Data Type: INT.
#define SAT_DATA_TYPE_LONG   10
 HP calculator Data Type: LONG.
#define SAT_DATA_TYPE_STRING   2
 HP calculator Data Type: STRING.
#define SAT_DATA_TYPE_REAL   0
 HP calculator Data Type: REAL.
#define SAT_DATA_TYPE_UNSUPPORTED   -999
 Marker for unsupported Data Type.
#define sat_peek_sat_addr(sat_addr)   sat_peek((sat_addr),5)
 Convenience macro for peeking Saturn addresses (5 nibbles).
#define sat_peek_sat_byte(sat_addr)   ((unsigned char) sat_peek((sat_addr),2))
 Convenience macro for peeking one byte (2 nibbles).
#define sat_poke_sat_byte(sat_addr, val)   sat_poke((sat_addr), (unsigned) (val), 2)
 Convenience macro for poking a single byte (2 nibbles) to Saturn memory.
#define sat_poke_sat_bytes(sat_addr, bytes, n)   sat_poke_nibbles((sat_addr), (bytes), (2*(n)))
 Convenience macro for poking many bytes (2*n nibbles) to Saturn memory.
#define sat_poke_sat_addr(sat_addr, val)   sat_poke((sat_addr), (val), 5)
 Convenience macro for poking a Saturn address (5 nibbles) to Saturn memory.
#define SAT_INTRPPTR   0x8076B
 Saturn CPU storage area: D0.
#define SAT_DSKTOP   0x806F8
 Saturn CPU storage area: D1.
#define SAT_RSKTOP   0x806F3
 Saturn CPU storage area: B.
#define SAT_AVMEM   0x80E9B
 Saturn CPU storage area: D.
#define SAT_TEMPTOP   0x806EE
 Saturn emu storage area: TEMPTOP.

Typedefs

typedef _sat_cpu SAT_CPU
 The emulated Saturn CPU as a memory area in ARM domain.
typedef _sat_cpuSAT_PCPU
 The emulated Saturn CPU as a memory area in ARM domain.
typedef _sat_stack_element SAT_STACK_ELEMENT
 A descriptor for an RPL stack element in Saturn notation.
typedef _sat_stack_elementSAT_PSTACK_ELEMENT
 A descriptor for an RPL stack element in Saturn notation.
typedef _sat_stack_data SAT_STACK_DATA
 Data structure, that models a single stack element.
typedef _sat_stack_dataSAT_PSTACK_DATA
 Data structure, that models a single stack element.

Functions

void sat_poke (int sat_addr, unsigned val, int nibbles)
 Poke up to 8 nibbles of data to Saturn domain.
void sat_poke_nibbles (unsigned sat_addr, const char *data, int nibbles)
 Poke many nibbles to Saturn domain.
unsigned sat_peek (int sat_addr, int nibbles)
 Peek up to 8 nibbles of data from Saturn domain.
void sat_moveup (int satsrc, int satdest, int nibbles)
 C implementation of Saturn MOVEUP.
int sat_createtemp (int objsize)
 Create a temporary object in the Saturn Heap.
BOOL sat_push_string (int type_prolog, int size_nibbles, const char *data)
 Push a string on the RPL stack.
unsigned int sat_map_s2a (unsigned int sat_addr)
 Translate a Saturn memory address to ARM domain.
void * sat_peek_sat_bytes (void *target, unsigned sat_addr, int nbytes)
 Peek many nibbles from Saturn domain into ARM memory.
unsigned sat_stack_init ()
 Initialize RPL stack access This function MUST be called before any other high level stack API function. The returned value is NOT intended for any usage other then storing it!
void sat_stack_exit (unsigned rpl_stack_bias)
 Finalize RPL stack access This function MUST be called before exiting the program Failing this may cause a calculator crash!
int sat_stack_depth ()
 Get number of elements on the RPL stack (DEPTH).
int sat_get_stack_element (int index, SAT_STACK_ELEMENT *element)
 Get a stack element (GET).
int sat_stack_drop ()
 Pop one element off the stack (DROP).
int sat_stack_dropn (int n)
 Pop many elements off the stack (DROPN).
int sat_stack_swap ()
 Swap elements on level 1 and 2 (SWAP).
int sat_stack_nip ()
 Swap then drop (NIP).
int sat_stack_push_string (const char *str)
 Push a string onto the RPL stack.
int _sat_stack_push_int (int z, int radix, int binary)
 Push a string representation of an integer onto the stack The integer is converted to a string and then pushed via sat_stack_push_string().
int sat_stack_push_int (int z)
 Push a string representation (base=10) of an integer onto the stack The integer is converted to a string and then pushed via sat_stack_push_string().
int sat_stack_push_double (double d)
 Push a string representation of a double onto the stack The double value is converted to a string and then pushed via sat_stack_push_string().
BOOL sat_push_zint_llong (long long num)
 Push a long long onto the RPL stack as a ZINT Accepts a number of Type 'long long', and pushes it as an Exact Integer (ZINT).
BOOL sat_push_zint_array (unsigned int digits, unsigned int negative, char *source)
 Helper function for pushing ZINTs onto the Stack Accepts an array of binary digits, and pushes then onto the stack egc {1,2,3,4,5,6,7,8,9} for 123456789. It also accepts a negative flag (if TRUE, number is treated as negative) and number of digits.
int sat_stack_levels_avail ()
 Inquiry function that tells how many stack levels are available for pushing.
char * _sat_decode_string (unsigned sat_addr)
 Decode a Saturn string object.
int sat_decode_stack_element (SAT_STACK_DATA *data, SAT_STACK_ELEMENT *stack)
 Decode a stack element to a SAT_STACK_DATA type.


Detailed Description

Saturn domain "hacking" and RPL stack manipulation library for the HP-49g+ calculator.

This library contains routines, that enable an applications programmer to access the RPL data on the calculator's stack and performing generalized data exchange with the Saturn emulator. The latter - "hacking" functions - consist mainly of a set of "peek" and "poke" functions for various data entities like "nibbles","bytes","words" and "strings" and address translation functions ARM <-> Saturn. There are just a few, easy to remember, high level API functions, which allow for complete control over the stack. The programmer does not need to know about Saturn internals.

Overview

The features include:

Quick Start Example

The following program expects two integer values, converted to strings, on the stack. It performs some operations with them and pushes a result back. As a string as well.

Note:
All data exchange is done with strings. This seems to be a limitiation. Actually it's not, since there are the STR-> and ->STR functions at the emulator's end, which are rather powerful. In C we have conversion routines for the basic C data types "int" [atoi()] and "double" [atof()]. Output conversion, for pushing results, is either done with "sprintf", or for simple types with "sat_stack_push_int"/"sat_stack_push_double"
 #include <hpgcc49.h>

 // Template for RPL stack pop/push usage
 // Ingo Blank, 2004-11-24


 int
 main()
 {
     // argument counter
     int argc = 0;

     // Initialize stack access
     unsigned rpl_stack_bias = sat_stack_init();

     // Determine number of elements in the stack
     int level = sat_stack_depth();

     // Dynamically dimension argument vector just as big as needed
     char *argv[level];

     while (sat_stack_depth()) {

         SAT_STACK_ELEMENT e;
         SAT_STACK_DATA d;

         // Get element at level #1, i.e. stack-top
         sat_get_stack_element(1,&e);

         // decode it ...
         sat_decode_stack_element(&d,&e);

         // check validity and store in argument vector

         // Note that elements are stored in *reverse* order, since
         // the stack is a LIFO structure
         if (d.type == SAT_DATA_TYPE_STRING)
                // remove single quotes from algebraic objects (if present)
                argv[++argc,--level] = str_unquote(d.sval,'\'');
         else
                ; // unsupported data type, error message, bail out, ignore ...

         // pop one element off the stack and continue loop
         sat_stack_drop();
     }

     // Now all RPL data is stored in the argv[] vector

     // your program here ...


     // Since the program does no screen output, skip init sequence

     //sys_intOff();
     //sys_slowOn(); 
     //clear_screen();

     // Demo: take two arguments, convert them to integers and apply the 4
     // basic arithmetic operations to them

     if (argc >= 2) {
         int x = atoi(argv[0]);
         int y = atoi(argv[1]);
         char buf[64];

         // print the result formatted as an HP list object {,,,}
         sprintf(buf,"{%d %d %d %d}",x+y,x-y,x*y,y ? x/y : 0);

         // push the string back to the stack
         // the receiving (User)RPL pogram can convert it with STR-> to a
         // proper list object
         sat_stack_push_string(buf);
     }

     // Finalize stack access
     // NEVER forget that, or risk a device crash!
     sat_stack_exit(rpl_stack_bias);

     // Since the program does no screen output, skip exit sequence

     //sys_slowOff();
     //sys_intOn();

     return 0;
 }

Typedef Documentation

typedef struct _sat_cpu SAT_CPU
 

The emulated Saturn CPU as a memory area in ARM domain.

typedef

struct _sat_cpu {
        
        unsigned int    Read[257];
        unsigned int    Write[257];
        unsigned char   unknown_data[260];
        unsigned int    A;
        unsigned int    Ah;
        unsigned int    B;
        unsigned int    Bh;
        unsigned int    C;
        unsigned int    Ch;
        unsigned int    D;
        unsigned int    Dh;
        
        unsigned int    R0;
        unsigned int    R0h;
        unsigned int    R1;
        unsigned int    R1h;
        unsigned int    R2;
        unsigned int    R2h;
        unsigned int    R3;
        unsigned int    R3h;
        unsigned int    R4;
        unsigned int    R4h;
        
        unsigned int    D0;
        unsigned int    D1;
        unsigned int    P;
        unsigned int    ST;
        unsigned int    HST;
        unsigned int    CARRY;
        unsigned int    DECIMAL_MODE;
        
} SAT_CPU, *SAT_PCPU;

typedef struct _sat_cpu * SAT_PCPU
 

The emulated Saturn CPU as a memory area in ARM domain.

typedef

struct _sat_cpu {
        
        unsigned int    Read[257];
        unsigned int    Write[257];
        unsigned char   unknown_data[260];
        unsigned int    A;
        unsigned int    Ah;
        unsigned int    B;
        unsigned int    Bh;
        unsigned int    C;
        unsigned int    Ch;
        unsigned int    D;
        unsigned int    Dh;
        
        unsigned int    R0;
        unsigned int    R0h;
        unsigned int    R1;
        unsigned int    R1h;
        unsigned int    R2;
        unsigned int    R2h;
        unsigned int    R3;
        unsigned int    R3h;
        unsigned int    R4;
        unsigned int    R4h;
        
        unsigned int    D0;
        unsigned int    D1;
        unsigned int    P;
        unsigned int    ST;
        unsigned int    HST;
        unsigned int    CARRY;
        unsigned int    DECIMAL_MODE;
        
} SAT_CPU, *SAT_PCPU;

typedef struct _sat_stack_data * SAT_PSTACK_DATA
 

Data structure, that models a single stack element.

typedef struct _sat_stack_data
{
        int     type;
        union {
                int             ival;
                double          dval;
                long long       lval;
                char            *sval;
        };
} SAT_STACK_DATA, *SAT_PSTACK_DATA;

typedef struct _sat_stack_element * SAT_PSTACK_ELEMENT
 

A descriptor for an RPL stack element in Saturn notation.

typedef struct _sat_stack_element
{
        unsigned        addr;
        unsigned        prologue;
        
} SAT_STACK_ELEMENT, *SAT_PSTACK_ELEMENT;

typedef struct _sat_stack_data SAT_STACK_DATA
 

Data structure, that models a single stack element.

typedef struct _sat_stack_data
{
        int     type;
        union {
                int             ival;
                double          dval;
                long long       lval;
                char            *sval;
        };
} SAT_STACK_DATA, *SAT_PSTACK_DATA;

typedef struct _sat_stack_element SAT_STACK_ELEMENT
 

A descriptor for an RPL stack element in Saturn notation.

typedef struct _sat_stack_element
{
        unsigned        addr;
        unsigned        prologue;
        
} SAT_STACK_ELEMENT, *SAT_PSTACK_ELEMENT;


Function Documentation

char* _sat_decode_string unsigned  sat_addr  ) 
 

Decode a Saturn string object.

Parameters:
sat_addr address of object in Saturn doamin
Returns:
Pointer to decoded string
Note:
Internal primitive, don't use in applications

int _sat_stack_push_int int  z,
int  radix,
int  binary
 

Push a string representation of an integer onto the stack The integer is converted to a string and then pushed via sat_stack_push_string().

Parameters:
z an Integer
radix The base
binary 1=use "#zzz[o|d|h]" representation
Returns:
Number of bytes pushed ( 0 on error )

int sat_createtemp int  objsize  ) 
 

Create a temporary object in the Saturn Heap.

C implementation of the HP49's ROM library routine

Parameters:
objsize Size of object in nibbles
Returns:
Pointer to prologue of newly created object or NULL on error

int sat_decode_stack_element SAT_STACK_DATA data,
SAT_STACK_ELEMENT stack
 

Decode a stack element to a SAT_STACK_DATA type.

Parameters:
data Pointer to decoded structure
stack Pointer to a raw stack element
Returns:
0 = success, -1 = error

int sat_get_stack_element int  index,
SAT_STACK_ELEMENT element
 

Get a stack element (GET).

Parameters:
index Stack Index [1..DEPTH]
element Pointer to a SAT_STACK_ELEMENT structure
Returns:
zero on success or -1 on error

unsigned int sat_map_s2a unsigned int  sat_addr  ) 
 

Translate a Saturn memory address to ARM domain.

Parameters:
sat_addr Memory address in Saturn domain
Returns:
Address in ARM domain

void sat_moveup int  satsrc,
int  satdest,
int  nibbles
 

C implementation of Saturn MOVEUP.

This function moves a number of nibbles in Saturn domain

Parameters:
satsrc The source address in Saturn domain
satdest The destination address in Saturn domain
nibbles Number of nibbles to move

unsigned sat_peek int  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 The address in Saturn domain
nibbles Number of nibbles to poke
Returns:
The datum itself

void* sat_peek_sat_bytes void *  target,
unsigned  sat_addr,
int  nbytes
 

Peek many nibbles from Saturn domain into ARM memory.

This function copies 2*strlen(data) nibbles from Saturn to ARM memory.

Parameters:
target Pointer to (allocated) memory in ARM domain
sat_addr Source address in Saturn domain
nbytes Number of bytes to copy

void sat_poke int  sat_addr,
unsigned  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 The address in Saturn domain
val The datum itself
nibbles Number of nibbles to poke

void sat_poke_nibbles unsigned  sat_addr,
const char *  data,
int  nibbles
 

Poke many nibbles to Saturn domain.

This function stores 2*strlen(data) nibbles to Saturn memory. It calls sat_poke() as it's "work-horse".

Parameters:
sat_addr The address in Saturn domain
data The data string
nibbles Number of nibbles to poke

BOOL sat_push_string int  type_prolog,
int  size_nibbles,
const char *  data
 

Push a string on the RPL stack.

This function works with ZINT,HXS,CSTR,LIBDATA and CODE data types

Parameters:
type_prolog The data type's prologue
size_nibbles Number of nibbles to push
data Pointer to data string
Returns:
TRUE on success

BOOL sat_push_zint_array unsigned int  digits,
unsigned int  negative,
char *  source
 

Helper function for pushing ZINTs onto the Stack Accepts an array of binary digits, and pushes then onto the stack egc {1,2,3,4,5,6,7,8,9} for 123456789. It also accepts a negative flag (if TRUE, number is treated as negative) and number of digits.

Parameters:
digits Number of digits in source
negative Set to TRUE for negative numbers
source the number as an array. Include binary values 0-9 ONLY.
Returns:
TRUE if sucessful.

BOOL sat_push_zint_llong long long  num  ) 
 

Push a long long onto the RPL stack as a ZINT Accepts a number of Type 'long long', and pushes it as an Exact Integer (ZINT).

Parameters:
num the number to push as a ZINT (long long).
Returns:
TRUE if sucessful.

int sat_stack_depth  ) 
 

Get number of elements on the RPL stack (DEPTH).

Returns:
Number of elements on stack or zero if empty

int sat_stack_drop  ) 
 

Pop one element off the stack (DROP).

Returns:
Number of dropped elements (1 on success)

int sat_stack_dropn int  n  ) 
 

Pop many elements off the stack (DROPN).

Returns:
Number of dropped elements

unsigned sat_stack_init  ) 
 

Initialize RPL stack access This function MUST be called before any other high level stack API function. The returned value is NOT intended for any usage other then storing it!

Returns:
a transparent pointer to a stack bias element in Saturn memory

int sat_stack_levels_avail  ) 
 

Inquiry function that tells how many stack levels are available for pushing.

Returns:
Number of available levels (0 = stack is full)

int sat_stack_nip  ) 
 

Swap then drop (NIP).

Returns:
Number of dropped elements (1 on success)

int sat_stack_push_double double  d  ) 
 

Push a string representation of a double onto the stack The double value is converted to a string and then pushed via sat_stack_push_string().

Parameters:
d a double
Returns:
Number of bytes pushed ( 0 on error )

int sat_stack_push_int int  z  ) 
 

Push a string representation (base=10) of an integer onto the stack The integer is converted to a string and then pushed via sat_stack_push_string().

Parameters:
z an Integer
Returns:
Number of bytes pushed ( 0 on error )

int sat_stack_push_string const char *  str  ) 
 

Push a string onto the RPL stack.

Parameters:
str Pointer to (zero delimited) string
Returns:
Number of bytes pushed ( 0 on error )

int sat_stack_swap  ) 
 

Swap elements on level 1 and 2 (SWAP).

Returns:
Number of swaps (1 on success)


Generated on Sun Jan 9 01:17:36 2005 for saturn by doxygen 1.3.8