OzVM API Description

Table 1. OzVM Exterior API
typedef struct OzVM_struct OzVM;
The structure maintaining the OzVM virtual machine. The following fields may be accessed to modify the state of the virtual machine:
uint64 r[256]; uint32 ip; uint32 mmask; uint8* m;
r is an array of the 256, 64-bit general purpose registers. ip is the instruction pointer. mmask is the bit-mask used to force valid memory access. m points to the allocated interior memory.

typedef void (*OzVM_trap_handler_type)( OzVM*, U4, U4 );
A pointer to an OzVM trap handler. The default trap handler can be replaced at run-time.

typedef void (*OzVM_voidvoid_func_type)( OzVM* );
A pointer to an OzVM function that takes no extra parameters and returns no value.

typedef int (*OzVM_vprintf_func_type)( void* opaque, const char* fmt, __va_list args );
A pointer to an OzVM function that can supercede the behavior of the OzVM printf and vprintf system calls. This may be removed or reworked in future versions of OzVM.

void OzVM_specify_jit_func( OzVM_voidvoid_func_type jit_func );
Specify the function used for just-in-time compilation to the local architecture. If set to null (0), the interior program is executed using the OzVM interpreter. This function applies global configuration, so may be reworked in future versions of OzVM.

void OzVM_specify_bootstrap_path( const char* bootstrap_path, int do_crop_tail );
Specify the directory path where bootstrap OzVM programs may reside, such as the bootstrap used to decompress compressed OzVM programs. If do_crop_tail is nonzero, all characters in bootstrap_path after the last path separator are ignored. This function applies global configuration, so may be reworked in future versions of OzVM.

OzVM* OzVM_alloc();
Allocate and initialize an OzVM.

void OzVM_init( OzVM* oz );
Initialize an already allocated OzVM.

void OzVM_uninit( OzVM* oz );
Uninitialize an OzVM without deallocating it.

void OzVM_free( OzVM* oz );
Unitialize and deallocate an OzVM.

void OzVM_alloc_mem( OzVM* oz, unsigned int membits );
Allocate 2^membits bytes of RAM to be made available to the interior program.

uint32 OzVM_lookup_symbol( OzVM* oz, const char* symbol_name );
Find the symbol symbol_name in the interior program and return its interior address.

void OzVM_trap( OzVM* oz, U4 handle, U4 data );
The default trap handler for OzVM. It services the system calls listed below, in the table "OzVM Interior API".

typedef size_t (*OzVM_read_func_type)( void* opaque, void* dest, size_t len );
A pointer to a general-purpose read function. opaque is an opaque pointer for internal use by the particular function. At most len bytes must be read into the buffer dest. The actual number of byte read must be returned.

OzVM* OzVM_load_image( OzVM* _oz, OzVM_read_func_type read_func, void* read_opaque );
Load an OzVM image. The image data is supplied by read_func and read_opaque. If _oz is null (0), a new OzVM is allocated and initialized. Otherwise, the existing OzVM is initialized with the image data.

void OzVM_run( OzVM* _oz );
Execute the OzVM _oz starting at the current value of the instruction pointer _oz->ip.

Table 1. OzVM Exterior API
typedef struct OzVM_struct OzVM; The structure maintaining the OzVM virtual machine. The following fields may be accessed to modify the state of the virtual machine: uint64 r[256]; uint32 ip; uint32 mmask; uint8* m; r is an array of the 256, 64-bit general purpose registers. ip is the instruction pointer. mmask is the bit-mask used to force valid memory access. m points to the allocated interior memory.
typedef void (*OzVM_trap_handler_type)( OzVM*, U4, U4 ); A pointer to an OzVM trap handler. The default trap handler can be replaced at run-time.
typedef void (*OzVM_voidvoid_func_type)( OzVM* ); A pointer to an OzVM function that takes no extra parameters and returns no value.
typedef int (*OzVM_vprintf_func_type)( void* opaque, const char* fmt, __va_list args ); A pointer to an OzVM function that can supercede the behavior of the OzVM printf and vprintf system calls. This may be removed or reworked in future versions of OzVM.
void OzVM_specify_jit_func( OzVM_voidvoid_func_type jit_func ); Specify the function used for just-in-time compilation to the local architecture. If set to null (0), the interior program is executed using the OzVM interpreter. This function applies global configuration, so may be reworked in future versions of OzVM.
void OzVM_specify_bootstrap_path( const char* bootstrap_path, int do_crop_tail ); Specify the directory path where bootstrap OzVM programs may reside, such as the bootstrap used to decompress compressed OzVM programs. If do_crop_tail is nonzero, all characters in bootstrap_path after the last path separator are ignored. This function applies global configuration, so may be reworked in future versions of OzVM.
OzVM* OzVM_alloc(); Allocate and initialize an OzVM.
void OzVM_init( OzVM* oz ); Initialize an already allocated OzVM.
void OzVM_uninit( OzVM* oz ); Uninitialize an OzVM without deallocating it.
void OzVM_free( OzVM* oz ); Unitialize and deallocate an OzVM.
void OzVM_alloc_mem( OzVM* oz, unsigned int membits ); Allocate 2^membits bytes of RAM to be made available to the interior program.
uint32 OzVM_lookup_symbol( OzVM* oz, const char* symbol_name ); Find the symbol symbol_name in the interior program and return its interior address.
void OzVM_trap( OzVM* oz, U4 handle, U4 data ); The default trap handler for OzVM. It services the system calls listed below, in the table "OzVM Interior API".
typedef size_t (*OzVM_read_func_type)( void* opaque, void* dest, size_t len ); A pointer to a general-purpose read function. opaque is an opaque pointer for internal use by the particular function. At most len bytes must be read into the buffer dest. The actual number of byte read must be returned.
OzVM* OzVM_load_image( OzVM* _oz, OzVM_read_func_type read_func, void* read_opaque ); Load an OzVM image. The image data is supplied by read_func and read_opaque. If _oz is null (0), a new OzVM is allocated and initialized. Otherwise, the existing OzVM is initialized with the image data.
void OzVM_run( OzVM* _oz ); Execute the OzVM _oz starting at the current value of the instruction pointer _oz->ip.

Table 2. OzVM Interior Exports
_OzVM_entry
Transfer control to an interior routine specified in register 64, then exit. Specifically, the symbol _OzVM_entry points to the assembly code
link %64, %1 trap %0, %0

This transfers control to the routine at the address stored in REG(64), specifying that the return address is to be saved in REG(1), the standard procedure return address register. When the routine returns, the interior program is terminated with exit code 0.

_OzVM_STACK
This symbol points to the top of the OzVM stack, which is by default 65536 bytes. It is used to initialize register 2 before program execution, the default stack pointer register.

Table 2. OzVM Interior Exports
_OzVM_entry Transfer control to an interior routine specified in register 64, then exit. Specifically, the symbol _OzVM_entry points to the assembly code link %64, %1 trap %0, %0 This transfers control to the routine at the address stored in REG(64), specifying that the return address is to be saved in REG(1), the standard procedure return address register. When the routine returns, the interior program is terminated with exit code 0.
_OzVM_STACK This symbol points to the top of the OzVM stack, which is by default 65536 bytes. It is used to initialize register 2 before program execution, the default stack pointer register.

System calls 0-1023 are reserved for the OzVM runtime. Unless otherwise noted, the system call argument acts as a read-only stack pointer for access to the function parameters.

Table 3. OzVM Interior API
System call C Prototype, Description

0-49 reserved for OzVM specific functions.

0 extern void exit( int );
The system call argument is an exit code. That value is transferred to register 3, the standard function return value. Then, the OzVM program is terminated.

1 extern void OzVM_error( int error_num, const char* error_msg );
Emit an error code and text.

2 extern void *ozvaptr( void * );
Convert a pointer interior to the machine to a "handle" pointer (relative to the host). While not a security risk, this is a hack for varadic system calls. It is deprecated and will be removed as soon as I write a legitimate set of printf routines.

3 extern unsigned int timednumber();
Return a number dependent on time that varies at least once a second. Useful for seeding a pseudo-random number generator.

50-99 reserved for C-library stdio.h style functions.
Because these are varadic functions and I'm lazy :(, pointers (to strings) in the varadic region must be wrapped interior calls of ozvaptr.

50 extern int printf(const char *, ...);

51 extern int vprintf(const char *, __va_list);

52 extern int snprintf(char *, size_t, const char *, ...);

53 extern int vsnprintf(char *, size_t, const char *, __va_list);

100-149 reserved for C-library stdlib.h style functions.

100 extern double atof(const char *);

101 extern int atoi(const char *);

102 extern int atoll(const char *);

103 extern int rand(void);

104 extern void srand(unsigned int);

150-199 reserved for C-library string.h style functions.
These calls silently guarantee memory is accessed within the valid OzVM memory space.

150 void *memset(void *, int c, size_t);

151 void *memcpy(void *, const void *, size_t);

152 void *memmove(void *, const void *, size_t);

153 char *strcpy(char *, const char *);

154 char *strncpy(char *, const char *, size_t);

155 char *strcat(char *, const char *);

156 char *strncat(char *, const char *, size_t);

157 int memcmp(const void *, const void *, size_t);

158 int strcmp(const char *, const char *);

159 int strncmp(const char *, const char *, size_t);

160 size_t strlen(const char *);

200-249 reserved for C-library math.h style functions.

200 extern double acos(double);

201 extern double asin(double);

202 extern double atan(double);

203 extern double atan2(double, double);

204 extern double cos(double);

205 extern double sin(double);

206 extern double tan(double);

207 extern double exp(double);

208 extern double log(double);

209 extern double log10(double);

210 extern double pow(double, double);

211 extern double sqrt(double);

212 extern double ceil(double);

213 extern double fabs(double);

214 extern double floor(double);

215 extern double fmod(double, double);

Table 3. OzVM Interior API
System call	C Prototype, Description
0-49 reserved for OzVM specific functions.
0	extern void exit( int ); The system call argument is an exit code. That value is transferred to register 3, the standard function return value. Then, the OzVM program is terminated.
1	extern void OzVM_error( int error_num, const char* error_msg ); Emit an error code and text.
2	extern void *ozvaptr( void * ); Convert a pointer interior to the machine to a "handle" pointer (relative to the host). While not a security risk, this is a hack for varadic system calls. It is deprecated and will be removed as soon as I write a legitimate set of printf routines.
3	extern unsigned int timednumber(); Return a number dependent on time that varies at least once a second. Useful for seeding a pseudo-random number generator.
*50-99 reserved for C-library stdio.h* style functions.** Because these are varadic functions and I'm lazy :(, pointers (to strings) in the varadic region must be wrapped interior calls of ozvaptr.
50	extern int printf(const char *, ...);
51	extern int vprintf(const char *, __va_list);
52	extern int snprintf(char , size_t, const char , ...);
53	extern int vsnprintf(char , size_t, const char , __va_list);
*100-149 reserved for C-library stdlib.h* style functions.**
100	extern double atof(const char *);
101	extern int atoi(const char *);
102	extern int atoll(const char *);
103	extern int rand(void);
104	extern void srand(unsigned int);
*150-199 reserved for C-library string.h* style functions.** These calls silently guarantee memory is accessed within the valid OzVM memory space.
150	void *memset(void *, int c, size_t);
151	void *memcpy(void , const void , size_t);
152	void *memmove(void , const void , size_t);
153	char *strcpy(char , const char );
154	char *strncpy(char , const char , size_t);
155	char *strcat(char , const char );
156	char *strncat(char , const char , size_t);
157	int memcmp(const void , const void , size_t);
158	int strcmp(const char , const char );
159	int strncmp(const char , const char , size_t);
160	size_t strlen(const char *);
*200-249 reserved for C-library math.h* style functions.**
200	extern double acos(double);
201	extern double asin(double);
202	extern double atan(double);
203	extern double atan2(double, double);
204	extern double cos(double);
205	extern double sin(double);
206	extern double tan(double);
207	extern double exp(double);
208	extern double log(double);
209	extern double log10(double);
210	extern double pow(double, double);
211	extern double sqrt(double);
212	extern double ceil(double);
213	extern double fabs(double);
214	extern double floor(double);
215	extern double fmod(double, double);

$Revision: 1.1.1.1 $
$Date: 2001/09/18 10:45:25 $