From bfb1076a778e63eadd5daf0d9fa6edd0add9c322 Mon Sep 17 00:00:00 2001 From: ncn Date: Sat, 25 Sep 2004 14:37:39 +0000 Subject: [PATCH] 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 --- legacy/embryo/Doxyfile | 12 +- legacy/embryo/README | 1 + legacy/embryo/embryo.c.in | 310 +++++++++++++++++++++++++-- legacy/embryo/gendoc | 4 - legacy/embryo/src/lib/Embryo.h | 62 +++--- legacy/embryo/src/lib/embryo_amx.c | 319 ++++++++++++++++++++++++++++ legacy/embryo/src/lib/embryo_main.c | 20 +- 7 files changed, 669 insertions(+), 59 deletions(-) diff --git a/legacy/embryo/Doxyfile b/legacy/embryo/Doxyfile index ba040ec825..e9c596987d 100644 --- a/legacy/embryo/Doxyfile +++ b/legacy/embryo/Doxyfile @@ -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 = diff --git a/legacy/embryo/README b/legacy/embryo/README index 2dfb4a8910..b96a862df1 100644 --- a/legacy/embryo/README +++ b/legacy/embryo/README @@ -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? diff --git a/legacy/embryo/embryo.c.in b/legacy/embryo/embryo.c.in index 75457078cc..717cfdc950 100644 --- a/legacy/embryo/embryo.c.in +++ b/legacy/embryo/embryo.c.in @@ -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 Small Language Booklet +@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. +*/ + \ No newline at end of file diff --git a/legacy/embryo/gendoc b/legacy/embryo/gendoc index e16878501a..058b02e4cd 100755 --- a/legacy/embryo/gendoc +++ b/legacy/embryo/gendoc @@ -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 diff --git a/legacy/embryo/src/lib/Embryo.h b/legacy/embryo/src/lib/Embryo.h index df5e2bfa22..9b226caf0e 100644 --- a/legacy/embryo/src/lib/Embryo.h +++ b/legacy/embryo/src/lib/Embryo.h @@ -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; diff --git a/legacy/embryo/src/lib/embryo_amx.c b/legacy/embryo/src/lib/embryo_amx.c index baaae3df18..1b7dd108a4 100644 --- a/legacy/embryo/src/lib/embryo_amx.c +++ b/legacy/embryo/src/lib/embryo_amx.c @@ -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) { diff --git a/legacy/embryo/src/lib/embryo_main.c b/legacy/embryo/src/lib/embryo_main.c index ca4195ca75..e140699010 100644 --- a/legacy/embryo/src/lib/embryo_main.c +++ b/legacy/embryo/src/lib/embryo_main.c @@ -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) {