Embryo documentation. About 90% done. Still some extra explanatory stuff to do, and some bugs to iron out, but all the functions in the API now at least have something written about them.
SVN revision: 11722
This commit is contained in:
ncn
ncn
parent
6322c5843d
commit
bfb1076a77
|
|
@ -1,7 +1,7 @@
|
|||
PROJECT_NAME = Embryo
|
||||
PROJECT_NUMBER =
|
||||
OUTPUT_DIRECTORY = doc
|
||||
INPUT = embryo.c
|
||||
INPUT = embryo.c.in src/lib/
|
||||
IMAGE_PATH = doc/img
|
||||
OUTPUT_LANGUAGE = English
|
||||
GENERATE_HTML = YES
|
||||
|
|
@ -57,7 +57,7 @@ MAX_INITIALIZER_LINES = 30
|
|||
OPTIMIZE_OUTPUT_FOR_C = YES
|
||||
OPTIMIZE_OUTPUT_JAVA = NO
|
||||
SHOW_USED_FILES = NO
|
||||
QUIET = NO
|
||||
QUIET = YES
|
||||
WARNINGS = YES
|
||||
WARN_IF_UNDOCUMENTED = YES
|
||||
WARN_FORMAT = "$file:$line: $text"
|
||||
|
|
@ -67,7 +67,7 @@ RECURSIVE = NO
|
|||
EXCLUDE =
|
||||
EXCLUDE_SYMLINKS = NO
|
||||
EXCLUDE_PATTERNS =
|
||||
EXAMPLE_PATH =
|
||||
EXAMPLE_PATH = examples
|
||||
EXAMPLE_PATTERNS =
|
||||
EXAMPLE_RECURSIVE = NO
|
||||
INPUT_FILTER =
|
||||
|
|
@ -137,9 +137,3 @@ MAX_DOT_GRAPH_HEIGHT = 512
|
|||
GENERATE_LEGEND = YES
|
||||
DOT_CLEANUP = YES
|
||||
SEARCHENGINE = NO
|
||||
CGI_NAME = search.cgi
|
||||
CGI_URL =
|
||||
DOC_URL =
|
||||
DOC_ABSPATH =
|
||||
BIN_ABSPATH = /usr/bin/
|
||||
EXT_DOC_PATHS =
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ hand-made tests. embryo_cc may not work if you compile using gcc 3.2.x. gcc
|
|||
we won't be jumping up and down, but be warned - gcc 3.2.x does not agree
|
||||
with embryo.
|
||||
|
||||
To view the API docs, run ./gendoc and view doc/html/index.html.
|
||||
|
||||
OK a lot of people ask this. What is Embryo?
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,3 @@
|
|||
/**
|
||||
@file
|
||||
@brief Embryo virtual machine library & compiler
|
||||
|
||||
These routines are used for Embryo library interaction
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
@mainpage Embryo Library Documentation
|
||||
|
|
@ -14,17 +7,304 @@ These routines are used for Embryo library interaction
|
|||
@date 2004
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@section intro What is Embryo?
|
||||
|
||||
It is a tiny library designed interpret limited small programs compiled by the
|
||||
included scmall compiler. This is mostly cleaning up and reduction in size of
|
||||
the original small abstract machine. the compiler itself has been left alone
|
||||
almost completely.
|
||||
Embryo is a tiny library designed to interpret limited Small programs
|
||||
compiled by the included compiler, @c embryo_cc. It is mostly a cleaned
|
||||
up and smaller version of the original Small abstract machine. The
|
||||
compiler is mostly untouched.
|
||||
|
||||
For more information about the Small language, see @ref Small_Page.
|
||||
|
||||
@section How_to_Use How to Use Embryo?
|
||||
|
||||
To use Embryo in your code, you need to do at least the following:
|
||||
|
||||
@li Include @ref Embryo.h.
|
||||
@li Load the Embryo program using one of the
|
||||
@ref Embryo_Program_Creation_Group.
|
||||
@li Set up the native calls with @ref embryo_program_native_call_add.
|
||||
@li Create a virtual machine with @ref embryo_program_vm_push.
|
||||
@li Then run the program with @ref embryo_program_run.
|
||||
|
||||
@todo Document it all
|
||||
@todo Clean up compiler code.
|
||||
@todo Proper overview of the operation of the interpreter, that is how
|
||||
the heap, stack, virtual machines, etc fit together.
|
||||
*/
|
||||
|
||||
/**
|
||||
@page Small_Page Brief Introduction to Small
|
||||
|
||||
This section describes the basics of Small, as compiled and interpreted
|
||||
with Embryo. For the full documentation, of which this is a summary, see
|
||||
@htmlonly <a href=http://www.compuphase.com/smalldoc.pdf>Small Language Booklet</a>
|
||||
@endhtmlonly
|
||||
@latexonly http://www.compuphase.com/smalldoc.pdf @endlatexonly
|
||||
|
||||
This summary assumes that you are familar with C. For a full list of
|
||||
differences between C and Small, again, see the full documentation.
|
||||
|
||||
@section Small_Variables_Section Variables
|
||||
|
||||
@subsection Small_Type_Subsection Types
|
||||
|
||||
There is only one type, known as the "cell", which can hold an integer.
|
||||
|
||||
@subsection Small_Scope_Subsection Scope
|
||||
|
||||
The scope and usage of a variable depends on its declaration.
|
||||
|
||||
@li A local variable is normally declared with the @c new keyword. E.g.
|
||||
@code new variable @endcode
|
||||
@li A static function variable is defined within a function with the
|
||||
@c static keyword.
|
||||
@li A global static variable is one that is only available within the
|
||||
file it was declared in. Again, use the @c static keyword, but outside
|
||||
of any function.
|
||||
@li A stock variable is one that may not be compiled into a program if it
|
||||
is not used. It is declared using @c stock.
|
||||
@li A public variable is one that can be read by the host program using
|
||||
@ref embryo_program_variable_find. It is declared using @c public
|
||||
keyword.
|
||||
|
||||
Remember that the keywords above are to be used on their own. That is,
|
||||
for example: @code public testvar @endcode not:
|
||||
@code new public testvar @endcode
|
||||
|
||||
@subsection Small_Constants_Subsection Constants
|
||||
|
||||
You can declare constants in two ways:
|
||||
@li Using the preprocessor macro @c #define.
|
||||
@li By inserting @c const between the keyword and variable name of a
|
||||
variable declaration. For example, to declare the variable @c var1
|
||||
constant, you type @code new const var1 = 2 @endcode Now @c var1
|
||||
cannot be changed.
|
||||
|
||||
@subsection Small_Arrays_Subsection Arrays
|
||||
|
||||
To declare an array, append square brackets to the end of the variable
|
||||
name. The following examples show how to declare arrays. Note the
|
||||
use of the ellipsis operator, which bases the array based on the last two
|
||||
declared values:
|
||||
|
||||
@code
|
||||
new msg[] = "A message."
|
||||
new ints[] = {1, 3, 4}
|
||||
new ints2[20] = {1, 3} // All other elements 0.
|
||||
new ints3[10] = {1, ... } // All elements = 1
|
||||
new ints4[10] = {10, 20, ... } // Elements = 10 -> 100.
|
||||
// The difference can be negative.
|
||||
new ints5[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}}
|
||||
@endcode
|
||||
|
||||
@note Array initialisers need to be constant.
|
||||
|
||||
@section Small_Func_Calls_Section Function Calls
|
||||
|
||||
A typical function declaration is as follows:
|
||||
|
||||
@code
|
||||
testfunc(param) {
|
||||
// Do something ...
|
||||
// over a couple of lines.
|
||||
}
|
||||
@endcode
|
||||
|
||||
You can pass by reference. That is, the parameter you pass is changed
|
||||
outside of the function. For example:
|
||||
|
||||
@code
|
||||
testfunc(¶m) {
|
||||
param = 10
|
||||
// The passed variable will be set to 10 outside of the function.
|
||||
}
|
||||
@endcode
|
||||
|
||||
To pass an array:
|
||||
|
||||
@code
|
||||
testfunc(param[]) {
|
||||
// Do something to the array
|
||||
}
|
||||
@endcode
|
||||
|
||||
@note Arrays are passed by reference.
|
||||
|
||||
@section Small_Control_Subsection Control Structures.
|
||||
|
||||
Small has the following control structures, which similar to their C
|
||||
counterparts:
|
||||
@li @code if (expression) statement1 else statement2 @endcode
|
||||
@li @code switch (expression) {
|
||||
case 0:
|
||||
statement1 // Can only be one statement. Look Ma, no breaks!
|
||||
case 1..3: // For values between 1 and 3 inclusive.
|
||||
statement2
|
||||
default: // Optional
|
||||
statement3
|
||||
}
|
||||
@endcode
|
||||
@li @code while(expression) statement @endcode
|
||||
@li @code do statement while (expression) @endcode
|
||||
@li @code for (init_expression; before_iter_test_expression; after_iter_expression) statement @endcode
|
||||
|
||||
@section Small_Preprocessor_Section Preprocessor
|
||||
|
||||
The following preprocessor directives are available:
|
||||
@li @code #assert constant_expression @endcode
|
||||
@li @code #define pattern replacement @endcode
|
||||
@li @code #define pattern(%1,%2,...) replacement @endcode
|
||||
@li @code #include filename @endcode
|
||||
@li @code #if constant_expression
|
||||
// Various bits of code
|
||||
#else
|
||||
// Other bits of code
|
||||
#endif
|
||||
@endcode
|
||||
@li @code #undef pattern @endcode
|
||||
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
@page Available_Native_Calls_Page Available Calls
|
||||
|
||||
Embryo provides a minimal set of native calls that can be used within
|
||||
any Embryo script. Those calls are detailed here.
|
||||
|
||||
@note Some of the "core" functions here are also described in the full
|
||||
Small documentation given
|
||||
|
||||
@todo Finish this section.
|
||||
|
||||
@section Args_ANC_Section Argument Functions
|
||||
|
||||
@subsection Numargs_Desc numargs
|
||||
|
||||
Returns the number of arguments passed to a function. Useful
|
||||
when dealing with variable argument lists.
|
||||
|
||||
@subsection Getargs_Desc getarg(arg, index=0)
|
||||
|
||||
Retrieves the argument number @c arg. If the argument is an array,
|
||||
use @c index to specify the index of the array to return.
|
||||
|
||||
@subsection Setargs_Desc setargs(arg, index=0, value)
|
||||
|
||||
Sets the argument number @c arg to the given @c arg. @c index specifies
|
||||
the index of @c arg to set if @c arg is an array.
|
||||
|
||||
@section String_ANC_Section String Functions
|
||||
|
||||
Functions that work on strings.
|
||||
|
||||
@subsection Atoi_Desc atoi
|
||||
|
||||
Translates an number in string form into an integer.
|
||||
|
||||
@subsection Fnmatch_Desc fnmatch
|
||||
|
||||
Buggered if I know what this does?
|
||||
|
||||
@subsection Strcmp_Desc strcmp
|
||||
|
||||
String comparing function.
|
||||
|
||||
|
||||
@section Float_ANC_Section Float Functions
|
||||
|
||||
@subsection Float_Desc float
|
||||
|
||||
@subsection Atof_Desc atof
|
||||
|
||||
@subsection Float_Mul_Desc float_mul
|
||||
|
||||
@subsection Float_Div_Desc float_div
|
||||
|
||||
@subsection Float_Add_Desc float_add
|
||||
|
||||
@subsection Float_Sub_Desc float_sub
|
||||
|
||||
@subsection Fract_Desc fract
|
||||
|
||||
@subsection Round_Desc round
|
||||
|
||||
@subsection Float_Cmp_Desc float_cmp
|
||||
|
||||
@subsection Sqrt_Desc sqrt
|
||||
|
||||
@subsection Pow_Desc pow
|
||||
|
||||
@subsection Log_Desc log
|
||||
|
||||
@subsection Sin_Desc sin
|
||||
|
||||
@subsection Cos_Desc cos
|
||||
|
||||
@subsection Tan_Desc tan
|
||||
|
||||
@subsection Abs_Desc abs
|
||||
|
||||
Returns the absolute value of the given float.
|
||||
|
||||
@section Time_ANC_Section Time Functions
|
||||
|
||||
@subsection Seconds_Desc seconds()
|
||||
|
||||
@subsection Date_Desc date
|
||||
|
||||
|
||||
@section Rand_ANC_Section Random Functions
|
||||
|
||||
@subsection Rand_Desc rand()
|
||||
|
||||
Returns a random integer.
|
||||
|
||||
@subsection Randf_Desc randf()
|
||||
|
||||
Returns a random float.
|
||||
|
||||
*/
|
||||
|
||||
/**
|
||||
@file Embryo.h
|
||||
@brief Embryo virtual machine library.
|
||||
|
||||
This file includes the routines needed for Embryo library interaction.
|
||||
This is the @e only file you need to include.
|
||||
|
||||
*/
|
||||
|
||||
// The following definitions are in Embryo.h, but I did not want to
|
||||
// mess up the formatting of the file
|
||||
|
||||
/**
|
||||
@def EMBRYO_FUNCTION_NONE
|
||||
An invalid/non-existant function.
|
||||
*/
|
||||
|
||||
/**
|
||||
@def EMBRYO_FUNCTION_MAIN
|
||||
Start at program entry point. For use with @ref embryo_program_run.
|
||||
*/
|
||||
|
||||
/**
|
||||
@def EMBRYO_FUNCTION_CONT
|
||||
Continue from last address. For use with @ref embryo_program_run.
|
||||
*/
|
||||
|
||||
/**
|
||||
@def EMBRYO_PROGRAM_OK
|
||||
Program was run successfully.
|
||||
*/
|
||||
|
||||
/**
|
||||
@def EMBRYO_PROGRAM_SLEEP
|
||||
The program's execution was interrupted by a Small @c sleep command.
|
||||
*/
|
||||
|
||||
/**
|
||||
@def EMBRYO_PROGRAM_FAIL
|
||||
An error in the program caused it to fail.
|
||||
*/
|
||||
|
||||
|
|
@ -1,8 +1,4 @@
|
|||
#!/bin/sh
|
||||
cp ./embryo.c.in ./embryo.c
|
||||
for I in `find ./src/lib -name "*.c" -print`; do
|
||||
cat $I >> ./embryo.c
|
||||
done
|
||||
rm -rf ./doc/html ./doc/latex ./doc/man
|
||||
mkdir -p ./doc/html ./doc/latex ./doc/man
|
||||
doxygen
|
||||
|
|
|
|||
|
|
@ -10,46 +10,48 @@ extern "C" {
|
|||
{
|
||||
EMBRYO_ERROR_NONE,
|
||||
/* reserve the first 15 error codes for exit codes of the abstract machine */
|
||||
EMBRYO_ERROR_EXIT, /* forced exit */
|
||||
EMBRYO_ERROR_ASSERT, /* assertion failed */
|
||||
EMBRYO_ERROR_STACKERR, /* stack/heap collision */
|
||||
EMBRYO_ERROR_BOUNDS, /* index out of bounds */
|
||||
EMBRYO_ERROR_MEMACCESS, /* invalid memory access */
|
||||
EMBRYO_ERROR_INVINSTR, /* invalid instruction */
|
||||
EMBRYO_ERROR_STACKLOW, /* stack underflow */
|
||||
EMBRYO_ERROR_HEAPLOW, /* heap underflow */
|
||||
EMBRYO_ERROR_CALLBACK, /* no callback, or invalid callback */
|
||||
EMBRYO_ERROR_NATIVE, /* native function failed */
|
||||
EMBRYO_ERROR_DIVIDE, /* divide by zero */
|
||||
EMBRYO_ERROR_SLEEP, /* go into sleepmode - code can be restarted */
|
||||
EMBRYO_ERROR_EXIT, /** Forced exit */
|
||||
EMBRYO_ERROR_ASSERT, /** Assertion failed */
|
||||
EMBRYO_ERROR_STACKERR, /** Stack/heap collision */
|
||||
EMBRYO_ERROR_BOUNDS, /** Index out of bounds */
|
||||
EMBRYO_ERROR_MEMACCESS, /** Invalid memory access */
|
||||
EMBRYO_ERROR_INVINSTR, /** Invalid instruction */
|
||||
EMBRYO_ERROR_STACKLOW, /** Stack underflow */
|
||||
EMBRYO_ERROR_HEAPLOW, /** Heap underflow */
|
||||
EMBRYO_ERROR_CALLBACK, /** No callback, or invalid callback */
|
||||
EMBRYO_ERROR_NATIVE, /** Native function failed */
|
||||
EMBRYO_ERROR_DIVIDE, /** Divide by zero */
|
||||
EMBRYO_ERROR_SLEEP, /** Go into sleepmode - code can be restarted */
|
||||
|
||||
EMBRYO_ERROR_MEMORY = 16, /* out of memory */
|
||||
EMBRYO_ERROR_FORMAT, /* invalid file format */
|
||||
EMBRYO_ERROR_VERSION, /* file is for a newer version of the Embryo_Program */
|
||||
EMBRYO_ERROR_NOTFOUND, /* function not found */
|
||||
EMBRYO_ERROR_INDEX, /* invalid index parameter (bad entry point) */
|
||||
EMBRYO_ERROR_DEBUG, /* debugger cannot run */
|
||||
EMBRYO_ERROR_INIT, /* Embryo_Program not initialized (or doubly initialized) */
|
||||
EMBRYO_ERROR_USERDATA, /* unable to set user data field (table full) */
|
||||
EMBRYO_ERROR_INIT_JIT, /* cannot initialize the JIT */
|
||||
EMBRYO_ERROR_PARAMS, /* parameter error */
|
||||
EMBRYO_ERROR_DOMAIN, /* domain error, expression result does not fit in range */
|
||||
EMBRYO_ERROR_MEMORY = 16, /** Out of memory */
|
||||
EMBRYO_ERROR_FORMAT, /** Invalid file format */
|
||||
EMBRYO_ERROR_VERSION, /** File is for a newer version of the Embryo_Program */
|
||||
EMBRYO_ERROR_NOTFOUND, /** Function not found */
|
||||
EMBRYO_ERROR_INDEX, /** Invalid index parameter (bad entry point) */
|
||||
EMBRYO_ERROR_DEBUG, /** Debugger cannot run */
|
||||
EMBRYO_ERROR_INIT, /** Embryo_Program not initialized (or doubly initialized) */
|
||||
EMBRYO_ERROR_USERDATA, /** Unable to set user data field (table full) */
|
||||
EMBRYO_ERROR_INIT_JIT, /** Cannot initialize the JIT */
|
||||
EMBRYO_ERROR_PARAMS, /** Parameter error */
|
||||
EMBRYO_ERROR_DOMAIN, /** Domain error, expression result does not fit in range */
|
||||
};
|
||||
|
||||
/* possible function type values that are enumerated */
|
||||
#define EMBRYO_FUNCTION_NONE 0x7fffffff /* an invalid/non existant function */
|
||||
#define EMBRYO_FUNCTION_MAIN -1 /* start at program entry point */
|
||||
#define EMBRYO_FUNCTION_CONT -2 /* continue from last address */
|
||||
/* an invalid cell reference */
|
||||
#define EMBRYO_CELL_NONE 0x7fffffff /* an invalid cell reference */
|
||||
#define EMBRYO_FUNCTION_NONE 0x7fffffff /* An invalid/non existant function */
|
||||
#define EMBRYO_FUNCTION_MAIN -1 /* Start at program entry point */
|
||||
#define EMBRYO_FUNCTION_CONT -2 /* Continue from last address */
|
||||
/** An invalid cell reference */
|
||||
#define EMBRYO_CELL_NONE 0x7fffffff
|
||||
/* program run return values */
|
||||
#define EMBRYO_PROGRAM_OK 1
|
||||
#define EMBRYO_PROGRAM_SLEEP 2
|
||||
#define EMBRYO_PROGRAM_BUSY 3
|
||||
#define EMBRYO_PROGRAM_FAIL 0
|
||||
|
||||
#define EMBRYO_FLOAT_TO_CELL(f) ( *((Embryo_Cell*)&f)) /* float to Embryo_Cell */
|
||||
#define EMBRYO_CELL_TO_FLOAT(c) ( *((float*)&c)) /* Embryo_Cell to float */
|
||||
/** Float to Embryo_Cell */
|
||||
#define EMBRYO_FLOAT_TO_CELL(f) ( *((Embryo_Cell*)&f))
|
||||
/** Embryo_Cell to float */
|
||||
#define EMBRYO_CELL_TO_FLOAT(c) ( *((float*)&c))
|
||||
|
||||
typedef unsigned int Embryo_UCell;
|
||||
typedef int Embryo_Cell;
|
||||
|
|
|
|||
|
|
@ -210,6 +210,19 @@ _embryo_program_init(Embryo_Program *ep, void *code)
|
|||
|
||||
/*** EXPORTED CALLS ***/
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Program_Creation_Group Program Creation and Destruction Functions
|
||||
*
|
||||
* Functions that set up programs, and destroy them.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Creates a new Embryo program, with bytecode data that can be freed.
|
||||
* @param data Pointer to the bytecode of the program.
|
||||
* @param size Number of bytes of bytecode.
|
||||
* @return A new Embryo program.
|
||||
* @ingroup Embryo_Program_Creation_Group
|
||||
*/
|
||||
Embryo_Program *
|
||||
embryo_program_new(void *data, int size)
|
||||
{
|
||||
|
|
@ -234,6 +247,14 @@ embryo_program_new(void *data, int size)
|
|||
return NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a new Embryo program, with bytecode data that cannot be
|
||||
* freed.
|
||||
* @param data Pointer to the bytecode of the program.
|
||||
* @param size Number of bytes of bytecode.
|
||||
* @return A new Embryo program.
|
||||
* @ingroup Embryo_Program_Creation_Group
|
||||
*/
|
||||
Embryo_Program *
|
||||
embryo_program_const_new(void *data, int size)
|
||||
{
|
||||
|
|
@ -253,6 +274,13 @@ embryo_program_const_new(void *data, int size)
|
|||
return NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a new Embryo program based on the bytecode data stored in the
|
||||
* given file.
|
||||
* @param file Filename of the given file.
|
||||
* @return A new Embryo program.
|
||||
* @ingroup Embryo_Program_Creation_Group
|
||||
*/
|
||||
Embryo_Program *
|
||||
embryo_program_load(char *file)
|
||||
{
|
||||
|
|
@ -300,6 +328,11 @@ embryo_program_load(char *file)
|
|||
return ep;
|
||||
}
|
||||
|
||||
/**
|
||||
* Frees the given Embryo program.
|
||||
* @param ep The given program.
|
||||
* @ingroup Embryo_Program_Creation_Group
|
||||
*/
|
||||
void
|
||||
embryo_program_free(Embryo_Program *ep)
|
||||
{
|
||||
|
|
@ -317,6 +350,19 @@ embryo_program_free(Embryo_Program *ep)
|
|||
free(ep);
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Func_Group Function Functions
|
||||
*
|
||||
* Functions that deal with Embryo program functions.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Adds a native program call to the given Embryo program.
|
||||
* @param ep The given Embryo program.
|
||||
* @param name The name for the call used in the script.
|
||||
* @param func The function to use when the call is made.
|
||||
* @ingroup Embryo_Func_Group
|
||||
*/
|
||||
void
|
||||
embryo_program_native_call_add(Embryo_Program *ep, char *name, Embryo_Cell (*func) (Embryo_Program *ep, Embryo_Cell *params))
|
||||
{
|
||||
|
|
@ -372,6 +418,30 @@ embryo_program_native_call_add(Embryo_Program *ep, char *name, Embryo_Cell (*fun
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Program_VM_Group Virtual Machine Functions
|
||||
*
|
||||
* Functions that deal with creating and destroying virtual machine sessions
|
||||
* for a given program.
|
||||
*
|
||||
* A given embryo program can have multiple virtual machine sessions running.
|
||||
* This is useful when you have a native call that in turn calls a function in
|
||||
* the embryo program. The native call can start a new virtual machine
|
||||
* session to run the function it needs. Once completed, the session can be
|
||||
* popped off the program's stack, and the native call can return its value
|
||||
* to the old session.
|
||||
*
|
||||
* A new virtual machine session is created by pushing a new virtual machine
|
||||
* onto the session stack of a program using @ref embryo_program_vm_push.
|
||||
* The current virtual machine session can be destroyed by calling
|
||||
* @ref embryo_program_vm_pop.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Resets the current virtual machine session of the given program.
|
||||
* @param ep The given program.
|
||||
* @ingroup Embryo_Program_VM_Group
|
||||
*/
|
||||
void
|
||||
embryo_program_vm_reset(Embryo_Program *ep)
|
||||
{
|
||||
|
|
@ -388,6 +458,14 @@ embryo_program_vm_reset(Embryo_Program *ep)
|
|||
ep->stk = ep->stp;
|
||||
}
|
||||
|
||||
/**
|
||||
* Starts a new virtual machine session for the given program.
|
||||
*
|
||||
* See @ref Embryo_Program_VM_Group for more information about how this works.
|
||||
*
|
||||
* @param ep The given program.
|
||||
* @ingroup Embryo_Program_VM_Group
|
||||
*/
|
||||
void
|
||||
embryo_program_vm_push(Embryo_Program *ep)
|
||||
{
|
||||
|
|
@ -400,6 +478,16 @@ embryo_program_vm_push(Embryo_Program *ep)
|
|||
embryo_program_vm_reset(ep);
|
||||
}
|
||||
|
||||
/**
|
||||
* Frees the current virtual machine session associated with the given program.
|
||||
*
|
||||
* See @ref Embryo_Program_VM_Group for more information about how this works.
|
||||
* Note that you will need to retrieve any return data or data on the stack
|
||||
* before you pop.
|
||||
*
|
||||
* @param ep The given program.
|
||||
* @ingroup Embryo_Program_VM_Group
|
||||
*/
|
||||
void
|
||||
embryo_program_vm_pop(Embryo_Program *ep)
|
||||
{
|
||||
|
|
@ -408,6 +496,21 @@ embryo_program_vm_pop(Embryo_Program *ep)
|
|||
ep->base = NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Swap_Group Byte Swapping Functions
|
||||
*
|
||||
* Functions that are used to ensure that integers passed to the
|
||||
* virtual machine are in small endian format. These functions are
|
||||
* used to ensure that the virtual machine operates correctly on big
|
||||
* endian machines.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Ensures that the given unsigned short integer is in the small
|
||||
* endian format.
|
||||
* @param v Pointer to the given integer.
|
||||
* @ingroup Embryo_Swap_Group
|
||||
*/
|
||||
void
|
||||
embryo_swap_16(unsigned short *v)
|
||||
{
|
||||
|
|
@ -416,6 +519,12 @@ embryo_swap_16(unsigned short *v)
|
|||
#endif
|
||||
}
|
||||
|
||||
/**
|
||||
* Ensures that the given unsigned integer is in the small endian
|
||||
* format.
|
||||
* @param v Pointer to the given integer.
|
||||
* @ingroup Embryo_Swap_Group
|
||||
*/
|
||||
void
|
||||
embryo_swap_32(unsigned int *v)
|
||||
{
|
||||
|
|
@ -424,6 +533,13 @@ embryo_swap_32(unsigned int *v)
|
|||
#endif
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the function in the given program with the given name.
|
||||
* @param ep The given program.
|
||||
* @param name The given function name.
|
||||
* @return The function if successful. Otherwise, @c EMBRYO_FUNCTION_NONE.
|
||||
* @ingroup Embryo_Func_Group
|
||||
*/
|
||||
Embryo_Function
|
||||
embryo_program_function_find(Embryo_Program *ep, char *name)
|
||||
{
|
||||
|
|
@ -451,6 +567,23 @@ embryo_program_function_find(Embryo_Program *ep, char *name)
|
|||
return EMBRYO_FUNCTION_NONE;
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Public_Variable_Group Public Variable Access Functions
|
||||
*
|
||||
* In an Embryo program, a global variable can be declared public, as
|
||||
* described in @ref Small_Scope_Subsection. The functions here allow
|
||||
* the host program to access these public variables.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Retrieves the location of the public variable in the given program
|
||||
* with the given name.
|
||||
* @param ep The given program.
|
||||
* @param name The given name.
|
||||
* @return The address of the variable if found. @c EMBRYO_CELL_NONE
|
||||
* otherwise.
|
||||
* @ingroup Embryo_Public_Variable_Group
|
||||
*/
|
||||
Embryo_Cell
|
||||
embryo_program_variable_find(Embryo_Program *ep, char *name)
|
||||
{
|
||||
|
|
@ -480,6 +613,12 @@ embryo_program_variable_find(Embryo_Program *ep, char *name)
|
|||
return EMBRYO_CELL_NONE;
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves the number of public variables in the given program.
|
||||
* @param ep The given program.
|
||||
* @return The number of public variables.
|
||||
* @ingroup Embryo_Public_Variable_Group
|
||||
*/
|
||||
int
|
||||
embryo_program_variable_count_get(Embryo_Program *ep)
|
||||
{
|
||||
|
|
@ -491,6 +630,15 @@ embryo_program_variable_count_get(Embryo_Program *ep)
|
|||
return NUMENTRIES(hdr, pubvars, tags);
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves the location of the public variable in the given program
|
||||
* with the given identifier.
|
||||
* @param ep The given program.
|
||||
* @param num The identifier of the public variable.
|
||||
* @return The virtual machine address of the variable if found.
|
||||
* @c EMBRYO_CELL_NONE otherwise.
|
||||
* @ingroup Embryo_Public_Variable_Group
|
||||
*/
|
||||
Embryo_Cell
|
||||
embryo_program_variable_get(Embryo_Program *ep, int num)
|
||||
{
|
||||
|
|
@ -506,6 +654,18 @@ embryo_program_variable_get(Embryo_Program *ep, int num)
|
|||
return EMBRYO_CELL_NONE;
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Error_Group Error Functions
|
||||
*
|
||||
* Functions that set and retrieve error codes in Embryo programs.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Sets the error code for the given program to the given code.
|
||||
* @param ep The given program.
|
||||
* @param error The given error code.
|
||||
* @ingroup Embryo_Error_Group
|
||||
*/
|
||||
void
|
||||
embryo_program_error_set(Embryo_Program *ep, int error)
|
||||
{
|
||||
|
|
@ -513,6 +673,12 @@ embryo_program_error_set(Embryo_Program *ep, int error)
|
|||
ep->error = error;
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves the current error code for the given program.
|
||||
* @param ep The given program.
|
||||
* @return The current error code.
|
||||
* @ingroup Embryo_Error_Group
|
||||
*/
|
||||
int
|
||||
embryo_program_error_get(Embryo_Program *ep)
|
||||
{
|
||||
|
|
@ -520,6 +686,19 @@ embryo_program_error_get(Embryo_Program *ep)
|
|||
return ep->error;
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Program_Data_Group Program Data Functions
|
||||
*
|
||||
* Functions that set and retrieve data associated with the given
|
||||
* program.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Sets the data associated to the given program.
|
||||
* @param ep The given program.
|
||||
* @param data New bytecode data.
|
||||
* @ingroup Embryo_Program_Data_Group
|
||||
*/
|
||||
void
|
||||
embryo_program_data_set(Embryo_Program *ep, void *data)
|
||||
{
|
||||
|
|
@ -527,6 +706,11 @@ embryo_program_data_set(Embryo_Program *ep, void *data)
|
|||
ep->data = data;
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves the data associated to the given program.
|
||||
* @param ep The given program.
|
||||
* @ingroup Embryo_Program_Data_Group
|
||||
*/
|
||||
void *
|
||||
embryo_program_data_get(Embryo_Program *ep)
|
||||
{
|
||||
|
|
@ -534,6 +718,13 @@ embryo_program_data_get(Embryo_Program *ep)
|
|||
return ep->data;
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieves a string describing the given error code.
|
||||
* @param error The given error code.
|
||||
* @return String describing the given error code. If the given code is not
|
||||
* known, the string "(unknown)" is returned.
|
||||
* @ingroup Embryo_Error_Group
|
||||
*/
|
||||
const char *
|
||||
embryo_error_string_get(int error)
|
||||
{
|
||||
|
|
@ -571,6 +762,19 @@ embryo_error_string_get(int error)
|
|||
return messages[error];
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Data_String_Group Embryo Data String Functions
|
||||
*
|
||||
* Functions that operate on strings in the memory of a virtual machine.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Retrieves the length of the string starting at the given cell.
|
||||
* @param ep The program the cell is part of.
|
||||
* @param str_cell Pointer to the first cell of the string.
|
||||
* @return The length of the string. @c 0 is returned if there is an error.
|
||||
* @ingroup Embryo_Data_String_Group
|
||||
*/
|
||||
int
|
||||
embryo_data_string_length_get(Embryo_Program *ep, Embryo_Cell *str_cell)
|
||||
{
|
||||
|
|
@ -587,6 +791,13 @@ embryo_data_string_length_get(Embryo_Program *ep, Embryo_Cell *str_cell)
|
|||
return len;
|
||||
}
|
||||
|
||||
/**
|
||||
* Copies the string starting at the given cell to the given buffer.
|
||||
* @param ep The program the cell is part of.
|
||||
* @param str_cell Pointer to the first cell of the string.
|
||||
* @param dst The given buffer.
|
||||
* @ingroup Embryo_Data_String_Group
|
||||
*/
|
||||
void
|
||||
embryo_data_string_get(Embryo_Program *ep, Embryo_Cell *str_cell, char *dst)
|
||||
{
|
||||
|
|
@ -624,6 +835,14 @@ embryo_data_string_get(Embryo_Program *ep, Embryo_Cell *str_cell, char *dst)
|
|||
dst[i] = 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Copies string in the given buffer into the virtual machine memory
|
||||
* starting at the given cell.
|
||||
* @param ep The program the cell is part of.
|
||||
* @param src The given buffer.
|
||||
* @param str_cell Pointer to the first cell to copy the string to.
|
||||
* @ingroup Embryo_Data_String_Group
|
||||
*/
|
||||
void
|
||||
embryo_data_string_set(Embryo_Program *ep, char *src, Embryo_Cell *str_cell)
|
||||
{
|
||||
|
|
@ -665,6 +884,14 @@ embryo_data_string_set(Embryo_Program *ep, char *src, Embryo_Cell *str_cell)
|
|||
str_cell[i] = 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Retreives a pointer to the address in the virtual machine given by the
|
||||
* given cell.
|
||||
* @param ep The program whose virtual machine address is being queried.
|
||||
* @param addr The given cell.
|
||||
* @return A pointer to the cell at the given address.
|
||||
* @ingroup Embryo_Data_String_Group
|
||||
*/
|
||||
Embryo_Cell *
|
||||
embryo_data_address_get(Embryo_Program *ep, Embryo_Cell addr)
|
||||
{
|
||||
|
|
@ -678,6 +905,23 @@ embryo_data_address_get(Embryo_Program *ep, Embryo_Cell addr)
|
|||
return (Embryo_Cell *)(data + (int)addr);
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Heap_Group Heap Functions
|
||||
*
|
||||
* The heap is an area of memory that can be allocated for program
|
||||
* use at runtime. The heap functions here change the amount of heap
|
||||
* memory available.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Increases the size of the heap of the given virtual machine by the given
|
||||
* number of Embryo_Cells.
|
||||
* @param ep The program with the given virtual machine.
|
||||
* @param cells The given number of Embryo_Cells.
|
||||
* @return The address of the new memory region on success.
|
||||
* @c EMBRYO_CELL_NONE otherwise.
|
||||
* @ingroup Embryo_Heap_Group
|
||||
*/
|
||||
Embryo_Cell
|
||||
embryo_data_heap_push(Embryo_Program *ep, int cells)
|
||||
{
|
||||
|
|
@ -695,6 +939,13 @@ embryo_data_heap_push(Embryo_Program *ep, int cells)
|
|||
return addr;
|
||||
}
|
||||
|
||||
/**
|
||||
* Decreases the size of the heap of the given virtual machine down to the
|
||||
* given size.
|
||||
* @param ep The program with the given virtual machine.
|
||||
* @param down_to The given size.
|
||||
* @ingroup Embryo_Heap_Group
|
||||
*/
|
||||
void
|
||||
embryo_data_heap_pop(Embryo_Program *ep, Embryo_Cell down_to)
|
||||
{
|
||||
|
|
@ -703,12 +954,41 @@ embryo_data_heap_pop(Embryo_Program *ep, Embryo_Cell down_to)
|
|||
if (ep->hea > down_to) ep->hea = down_to;
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Run_Group Program Run Functions
|
||||
*
|
||||
* Functions that are involved in actually running functions in an
|
||||
* Embryo program.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Returns the number of virtual machines are running for the given program.
|
||||
* @param ep The given program.
|
||||
* @return The number of virtual machines running.
|
||||
* @ingroup Embryo_Run_Group
|
||||
*/
|
||||
int
|
||||
embryo_program_recursion_get(Embryo_Program *ep)
|
||||
{
|
||||
return ep->run_count;
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs the given function of the given Embryo program in the current
|
||||
* virtual machine. The parameter @p fn can be found using
|
||||
* @ref embryo_program_function_find.
|
||||
*
|
||||
* @note For Embryo to be able to run a function, it must have been
|
||||
* declared @c public in the Small source code.
|
||||
*
|
||||
* @param ep The given program.
|
||||
* @param fn The given function. Normally "main", in which case the
|
||||
* constant @c EMBRYO_FUNCTION_MAIN can be used.
|
||||
* @return @c EMBRYO_PROGRAM_OK on success. @c EMBRYO_PROGRAM_SLEEP if the
|
||||
* program is halted by the Small @c sleep call.
|
||||
* @c EMBRYO_PROGRAM_FAIL if there is an error.
|
||||
* @ingroup Embryo_Run_Group
|
||||
*/
|
||||
int
|
||||
embryo_program_run(Embryo_Program *ep, Embryo_Function fn)
|
||||
{
|
||||
|
|
@ -1626,6 +1906,14 @@ embryo_program_run(Embryo_Program *ep, Embryo_Function fn)
|
|||
return EMBRYO_PROGRAM_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* Retreives the return value of the last called function of the given
|
||||
* program.
|
||||
* @param ep The given program.
|
||||
* @return An Embryo_Cell representing the return value of the function
|
||||
* that was last called.
|
||||
* @ingroup Embryo_Run_Group
|
||||
*/
|
||||
Embryo_Cell
|
||||
embryo_program_return_value_get(Embryo_Program *ep)
|
||||
{
|
||||
|
|
@ -1633,6 +1921,20 @@ embryo_program_return_value_get(Embryo_Program *ep)
|
|||
return ep->retval;
|
||||
}
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Parameter_Group Function Parameter Functions
|
||||
*
|
||||
* Functions that set parameters for the next function that is called.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Pushes an Embryo_Cell onto the function stack to use as a parameter for
|
||||
* the next function that is called in the given program.
|
||||
* @param ep The given program.
|
||||
* @param cell The Embryo_Cell to push onto the stack.
|
||||
* @return @c 1 if successful. @c 0 otherwise.
|
||||
* @ingroup Embryo_Parameter_Group
|
||||
*/
|
||||
int
|
||||
embryo_parameter_cell_push(Embryo_Program *ep, Embryo_Cell cell)
|
||||
{
|
||||
|
|
@ -1655,6 +1957,14 @@ embryo_parameter_cell_push(Embryo_Program *ep, Embryo_Cell cell)
|
|||
return 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pushes a string onto the function stack to use as a parameter for the
|
||||
* next function that is called in the given program.
|
||||
* @param ep The given program.
|
||||
* @param str The string to push onto the stack.
|
||||
* @return @c 1 if successful. @c 0 otherwise.
|
||||
* @ingroup Embryo_Parameter_Group
|
||||
*/
|
||||
int
|
||||
embryo_parameter_string_push(Embryo_Program *ep, char *str)
|
||||
{
|
||||
|
|
@ -1686,6 +1996,15 @@ embryo_parameter_string_push(Embryo_Program *ep, char *str)
|
|||
return 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pushes an array of Embryo_Cells onto the function stack to be used as
|
||||
* parameters for the next function that is called in the given program.
|
||||
* @param ep The given program.
|
||||
* @param cells The array of Embryo_Cells.
|
||||
* @param num The number of cells in @p cells.
|
||||
* @return @c 1 if successful. @c 0 otherwise.
|
||||
* @ingroup Embryo_Parameter_Group
|
||||
*/
|
||||
int
|
||||
embryo_parameter_cell_array_push(Embryo_Program *ep, Embryo_Cell *cells, int num)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -4,7 +4,19 @@
|
|||
static int _embryo_init_count = 0;
|
||||
|
||||
/*** EXPORTED CALLS ***/
|
||||
|
||||
|
||||
/**
|
||||
* @defgroup Embryo_Library_Group Library Maintenance Functions
|
||||
*
|
||||
* Functions that start up and shutdown the Embryo library.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Initialises the Embryo library.
|
||||
* @return The number of times the library has been initialised without being
|
||||
* shut down.
|
||||
* @ingroup Embryo_Library_Group
|
||||
*/
|
||||
int
|
||||
embryo_init(void)
|
||||
{
|
||||
|
|
@ -16,6 +28,12 @@ embryo_init(void)
|
|||
return _embryo_init_count;
|
||||
}
|
||||
|
||||
/**
|
||||
* Shuts down the Embryo library.
|
||||
* @return The number of times the library has been initialised without being
|
||||
* shutdown.
|
||||
* @ingroup Embryo_Library_Group
|
||||
*/
|
||||
int
|
||||
embryo_shutdown(void)
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in New Issue