src/lib/Embryo.h

   1 #ifndef _EMBRYO_H
   2 #define _EMBRYO_H
   3
   4 #ifdef EAPI
   5 # undef EAPI
   6 #endif
   7
   8 #ifdef _WIN32
   9 # ifdef EFL_EMBRYO_BUILD
  10 #  ifdef DLL_EXPORT
  11 #   define EAPI __declspec(dllexport)
  12 #  else
  13 #   define EAPI
  14 #  endif /* ! DLL_EXPORT */
  15 # else
  16 #  define EAPI __declspec(dllimport)
  17 # endif /* ! EFL_EMBRYO_BUILD */
  18 #else
  19 # ifdef __GNUC__
  20 #  if __GNUC__ >= 4
  21 #   define EAPI __attribute__ ((visibility("default")))
  22 #  else
  23 #   define EAPI
  24 #  endif
  25 # else
  26 #  define EAPI
  27 # endif
  28 #endif /* ! _WIN32 */
  29
  30 #ifdef  __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 #define EMBRYO_VERSION_MAJOR 1
  35 #define EMBRYO_VERSION_MINOR 0
  36
  37    typedef struct _Embryo_Version
  38      {
  39         int major;
  40         int minor;
  41         int micro;
  42         int revision;
  43      } Embryo_Version;
  44
  45    EAPI extern Embryo_Version *embryo_version;
  46
  47    /* potential error values */
  48    typedef enum _Embryo_Error
  49      {
  50         EMBRYO_ERROR_NONE,
  51           /* reserve the first 15 error codes for exit codes of the abstract machine */
  52           EMBRYO_ERROR_EXIT,         /** Forced exit */
  53           EMBRYO_ERROR_ASSERT,       /** Assertion failed */
  54           EMBRYO_ERROR_STACKERR,     /** Stack/heap collision */
  55           EMBRYO_ERROR_BOUNDS,       /** Index out of bounds */
  56           EMBRYO_ERROR_MEMACCESS,    /** Invalid memory access */
  57           EMBRYO_ERROR_INVINSTR,     /** Invalid instruction */
  58           EMBRYO_ERROR_STACKLOW,     /** Stack underflow */
  59           EMBRYO_ERROR_HEAPLOW,      /** Heap underflow */
  60           EMBRYO_ERROR_CALLBACK,     /** No callback, or invalid callback */
  61           EMBRYO_ERROR_NATIVE,       /** Native function failed */
  62           EMBRYO_ERROR_DIVIDE,       /** Divide by zero */
  63           EMBRYO_ERROR_SLEEP,        /** Go into sleepmode - code can be restarted */
  64
  65           EMBRYO_ERROR_MEMORY = 16,  /** Out of memory */
  66           EMBRYO_ERROR_FORMAT,       /** Invalid file format */
  67           EMBRYO_ERROR_VERSION,      /** File is for a newer version of the Embryo_Program */
  68           EMBRYO_ERROR_NOTFOUND,     /** Function not found */
  69           EMBRYO_ERROR_INDEX,        /** Invalid index parameter (bad entry point) */
  70           EMBRYO_ERROR_DEBUG,        /** Debugger cannot run */
  71           EMBRYO_ERROR_INIT,         /** Embryo_Program not initialized (or doubly initialized) */
  72           EMBRYO_ERROR_USERDATA,     /** Unable to set user data field (table full) */
  73           EMBRYO_ERROR_INIT_JIT,     /** Cannot initialize the JIT */
  74           EMBRYO_ERROR_PARAMS,       /** Parameter error */
  75           EMBRYO_ERROR_DOMAIN,       /** Domain error, expression result does not fit in range */
  76      } Embryo_Error;
  77
  78    /* program run return values */
  79    typedef enum _Embryo_Status
  80      {
  81         EMBRYO_PROGRAM_FAIL = 0,
  82         EMBRYO_PROGRAM_OK = 1,
  83         EMBRYO_PROGRAM_SLEEP = 2,
  84         EMBRYO_PROGRAM_BUSY = 3,
  85         EMBRYO_PROGRAM_TOOLONG = 4
  86      } Embryo_Status;
  87
  88    typedef unsigned int                Embryo_UCell;
  89    typedef int                         Embryo_Cell;
  90   /** An invalid cell reference */
  91 #define EMBRYO_CELL_NONE     0x7fffffff
  92
  93    typedef struct _Embryo_Program      Embryo_Program;
  94    typedef int                         Embryo_Function;
  95    /* possible function type values that are enumerated */
  96 #define EMBRYO_FUNCTION_NONE 0x7fffffff /* An invalid/non existent function */
  97 #define EMBRYO_FUNCTION_MAIN -1         /* Start at program entry point */
  98 #define EMBRYO_FUNCTION_CONT -2         /* Continue from last address */
  99
 100    typedef union
 101      {
 102         float       f;
 103         Embryo_Cell c;
 104      } Embryo_Float_Cell;
 105
 106 #if defined _MSC_VER || defined __SUNPRO_C
 107 /** Float to Embryo_Cell */
 108 # define EMBRYO_FLOAT_TO_CELL(f) (((Embryo_Float_Cell *)&(f))->c)
 109 /** Embryo_Cell to float */
 110 # define EMBRYO_CELL_TO_FLOAT(c) (((Embryo_Float_Cell *)&(c))->f)
 111 #else
 112 /** Float to Embryo_Cell */
 113 # define EMBRYO_FLOAT_TO_CELL(f) ((Embryo_Float_Cell) f).c
 114 /** Embryo_Cell to float */
 115 # define EMBRYO_CELL_TO_FLOAT(c) ((Embryo_Float_Cell) c).f
 116 #endif
 117
 118    /**
 119     * @defgroup Embryo_Library_Group Library Maintenance Functions
 120     *
 121     * Functions that start up and shutdown the Embryo library.
 122     */
 123
 124
 125 /**
 126  * Initialises the Embryo library.
 127  * @return  The number of times the library has been initialised without being
 128  *          shut down.
 129  * @ingroup Embryo_Library_Group
 130  */
 131 EAPI int              embryo_init(void);
 132
 133 /**
 134  * Shuts down the Embryo library.
 135  * @return  The number of times the library has been initialised without being
 136  *          shutdown.
 137  * @ingroup Embryo_Library_Group
 138  */
 139 EAPI int              embryo_shutdown(void);
 140
 141    /**
 142     * @defgroup Embryo_Program_Creation_Group Program Creation and Destruction Functions
 143     *
 144     * Functions that set up programs, and destroy them.
 145     */
 146
 147 /**
 148  * Creates a new Embryo program, with bytecode data that can be freed.
 149  * @param   data Pointer to the bytecode of the program.
 150  * @param   size Number of bytes of bytecode.
 151  * @return  A new Embryo program.
 152  * @ingroup Embryo_Program_Creation_Group
 153  */
 154 EAPI Embryo_Program  *embryo_program_new(void *data, int size);
 155
 156 /**
 157  * Creates a new Embryo program, with bytecode data that cannot be
 158  * freed.
 159  * @param   data Pointer to the bytecode of the program.
 160  * @param   size Number of bytes of bytecode.
 161  * @return  A new Embryo program.
 162  * @ingroup Embryo_Program_Creation_Group
 163  */
 164 EAPI Embryo_Program  *embryo_program_const_new(void *data, int size);
 165
 166 /**
 167  * Creates a new Embryo program based on the bytecode data stored in the
 168  * given file.
 169  * @param   file Filename of the given file.
 170  * @return  A new Embryo program.
 171  * @ingroup Embryo_Program_Creation_Group
 172  */
 173 EAPI Embryo_Program  *embryo_program_load(const char *file);
 174
 175 /**
 176  * Frees the given Embryo program.
 177  * @param   ep The given program.
 178  * @ingroup Embryo_Program_Creation_Group
 179  */
 180 EAPI void             embryo_program_free(Embryo_Program *ep);
 181
 182 /**
 183  * Adds a native program call to the given Embryo program.
 184  * @param   ep   The given Embryo program.
 185  * @param   name The name for the call used in the script.
 186  * @param   func The function to use when the call is made.
 187  * @ingroup Embryo_Func_Group
 188  */
 189
 190 /**
 191  * @defgroup Embryo_Func_Group Function Functions
 192  *
 193  * Functions that deal with Embryo program functions.
 194  */
 195 EAPI void             embryo_program_native_call_add(Embryo_Program *ep, const char *name, Embryo_Cell (*func) (Embryo_Program *ep, Embryo_Cell *params));
 196
 197 /**
 198  * Resets the current virtual machine session of the given program.
 199  * @param   ep The given program.
 200  * @ingroup Embryo_Program_VM_Group
 201  */
 202
 203 /**
 204  * @defgroup Embryo_Program_VM_Group Virtual Machine Functions
 205  *
 206  * Functions that deal with creating and destroying virtual machine sessions
 207  * for a given program.
 208  *
 209  * A given embryo program can have multiple virtual machine sessions running.
 210  * This is useful when you have a native call that in turn calls a function in
 211  * the embryo program.  The native call can start a new virtual machine
 212  * session to run the function it needs.  Once completed, the session can be
 213  * popped off the program's stack, and the native call can return its value
 214  * to the old session.
 215  *
 216  * A new virtual machine session is created by pushing a new virtual machine
 217  * onto the session stack of a program using @ref embryo_program_vm_push.
 218  * The current virtual machine session can be destroyed by calling
 219  * @ref embryo_program_vm_pop.
 220  */
 221 EAPI void             embryo_program_vm_reset(Embryo_Program *ep);
 222
 223 /**
 224  * Starts a new virtual machine session for the given program.
 225  *
 226  * See @ref Embryo_Program_VM_Group for more information about how this works.
 227  *
 228  * @param   ep The given program.
 229  * @ingroup Embryo_Program_VM_Group
 230  */
 231 EAPI void             embryo_program_vm_push(Embryo_Program *ep);
 232
 233 /**
 234  * Frees the current virtual machine session associated with the given program.
 235  *
 236  * See @ref Embryo_Program_VM_Group for more information about how this works.
 237  * Note that you will need to retrieve any return data or data on the stack
 238  * before you pop.
 239  *
 240  * @param   ep The given program.
 241  * @ingroup Embryo_Program_VM_Group
 242  */
 243 EAPI void             embryo_program_vm_pop(Embryo_Program *ep);
 244
 245 /**
 246  * Ensures that the given unsigned short integer is in the small
 247  * endian format.
 248  * @param   v Pointer to the given integer.
 249  * @ingroup Embryo_Swap_Group
 250  */
 251
 252 /**
 253  * @defgroup Embryo_Swap_Group Byte Swapping Functions
 254  *
 255  * Functions that are used to ensure that integers passed to the
 256  * virtual machine are in small endian format.  These functions are
 257  * used to ensure that the virtual machine operates correctly on big
 258  * endian machines.
 259  */
 260 EAPI void             embryo_swap_16(unsigned short *v);
 261
 262 /**
 263  * Ensures that the given unsigned integer is in the small endian
 264  * format.
 265  * @param   v Pointer to the given integer.
 266  * @ingroup Embryo_Swap_Group
 267  */
 268 EAPI void             embryo_swap_32(unsigned int *v);
 269
 270 /**
 271  * Returns the function in the given program with the given name.
 272  * @param   ep The given program.
 273  * @param   name The given function name.
 274  * @return  The function if successful.  Otherwise, @c EMBRYO_FUNCTION_NONE.
 275  * @ingroup Embryo_Func_Group
 276  */
 277 EAPI Embryo_Function  embryo_program_function_find(Embryo_Program *ep, const char *name);
 278
 279 /**
 280  * Retrieves the location of the public variable in the given program
 281  * with the given name.
 282  * @param   ep   The given program.
 283  * @param   name The given name.
 284  * @return  The address of the variable if found.  @c EMBRYO_CELL_NONE
 285  *          otherwise.
 286  * @ingroup Embryo_Public_Variable_Group
 287  */
 288
 289 /**
 290  * @defgroup Embryo_Public_Variable_Group Public Variable Access Functions
 291  *
 292  * In an Embryo program, a global variable can be declared public, as
 293  * described in @ref Small_Scope_Subsection.  The functions here allow
 294  * the host program to access these public variables.
 295  */
 296 EAPI Embryo_Cell      embryo_program_variable_find(Embryo_Program *ep, const char *name);
 297
 298 /**
 299  * Retrieves the number of public variables in the given program.
 300  * @param   ep The given program.
 301  * @return  The number of public variables.
 302  * @ingroup Embryo_Public_Variable_Group
 303  */
 304 EAPI int              embryo_program_variable_count_get(Embryo_Program *ep);
 305
 306 /**
 307  * Retrieves the location of the public variable in the given program
 308  * with the given identifier.
 309  * @param   ep  The given program.
 310  * @param   num The identifier of the public variable.
 311  * @return  The virtual machine address of the variable if found.
 312  *          @c EMBRYO_CELL_NONE otherwise.
 313  * @ingroup Embryo_Public_Variable_Group
 314  */
 315 EAPI Embryo_Cell      embryo_program_variable_get(Embryo_Program *ep, int num);
 316
 317 /**
 318  * Sets the error code for the given program to the given code.
 319  * @param   ep The given program.
 320  * @param   error The given error code.
 321  * @ingroup Embryo_Error_Group
 322  */
 323
 324 /**
 325  * @defgroup Embryo_Error_Group Error Functions
 326  *
 327  * Functions that set and retrieve error codes in Embryo programs.
 328  */
 329 EAPI void             embryo_program_error_set(Embryo_Program *ep, Embryo_Error error);
 330
 331 /**
 332  * Retrieves the current error code for the given program.
 333  * @param   ep The given program.
 334  * @return  The current error code.
 335  * @ingroup Embryo_Error_Group
 336  */
 337 EAPI Embryo_Error     embryo_program_error_get(Embryo_Program *ep);
 338
 339 /**
 340  * Sets the data associated to the given program.
 341  * @param   ep   The given program.
 342  * @param   data New bytecode data.
 343  * @ingroup Embryo_Program_Data_Group
 344  */
 345
 346 /**
 347  * @defgroup Embryo_Program_Data_Group Program Data Functions
 348  *
 349  * Functions that set and retrieve data associated with the given
 350  * program.
 351  */
 352 EAPI void             embryo_program_data_set(Embryo_Program *ep, void *data);
 353
 354 /**
 355  * Retrieves the data associated to the given program.
 356  * @param   ep The given program.
 357  * @ingroup Embryo_Program_Data_Group
 358  */
 359 EAPI void            *embryo_program_data_get(Embryo_Program *ep);
 360
 361 /**
 362  * Retrieves a string describing the given error code.
 363  * @param   error The given error code.
 364  * @return  String describing the given error code.  If the given code is not
 365  *          known, the string "(unknown)" is returned.
 366  * @ingroup Embryo_Error_Group
 367  */
 368 EAPI const char      *embryo_error_string_get(Embryo_Error error);
 369
 370 /**
 371  * Retrieves the length of the string starting at the given cell.
 372  * @param   ep       The program the cell is part of.
 373  * @param   str_cell Pointer to the first cell of the string.
 374  * @return  The length of the string.  @c 0 is returned if there is an error.
 375  * @ingroup Embryo_Data_String_Group
 376  */
 377
 378 /**
 379  * @defgroup Embryo_Data_String_Group Embryo Data String Functions
 380  *
 381  * Functions that operate on strings in the memory of a virtual machine.
 382  */
 383 EAPI int              embryo_data_string_length_get(Embryo_Program *ep, Embryo_Cell *str_cell);
 384
 385 /**
 386  * Copies the string starting at the given cell to the given buffer.
 387  * @param   ep       The program the cell is part of.
 388  * @param   str_cell Pointer to the first cell of the string.
 389  * @param   dst      The given buffer.
 390  * @ingroup Embryo_Data_String_Group
 391  */
 392 EAPI void             embryo_data_string_get(Embryo_Program *ep, Embryo_Cell *str_cell, char *dst);
 393
 394 /**
 395  * Copies string in the given buffer into the virtual machine memory
 396  * starting at the given cell.
 397  * @param ep       The program the cell is part of.
 398  * @param src      The given buffer.
 399  * @param str_cell Pointer to the first cell to copy the string to.
 400  * @ingroup Embryo_Data_String_Group
 401  */
 402 EAPI void             embryo_data_string_set(Embryo_Program *ep, const char *src, Embryo_Cell *str_cell);
 403
 404 /**
 405  * Retreives a pointer to the address in the virtual machine given by the
 406  * given cell.
 407  * @param   ep   The program whose virtual machine address is being queried.
 408  * @param   addr The given cell.
 409  * @return  A pointer to the cell at the given address.
 410  * @ingroup Embryo_Data_String_Group
 411  */
 412 EAPI Embryo_Cell     *embryo_data_address_get(Embryo_Program *ep, Embryo_Cell addr);
 413
 414 /**
 415  * Increases the size of the heap of the given virtual machine by the given
 416  * number of Embryo_Cells.
 417  * @param   ep    The program with the given virtual machine.
 418  * @param   cells The given number of Embryo_Cells.
 419  * @return  The address of the new memory region on success.
 420  *          @c EMBRYO_CELL_NONE otherwise.
 421  * @ingroup Embryo_Heap_Group
 422  */
 423
 424 /**
 425  * @defgroup Embryo_Heap_Group Heap Functions
 426  *
 427  * The heap is an area of memory that can be allocated for program
 428  * use at runtime.  The heap functions here change the amount of heap
 429  * memory available.
 430  */
 431 EAPI Embryo_Cell      embryo_data_heap_push(Embryo_Program *ep, int cells);
 432
 433 /**
 434  * Decreases the size of the heap of the given virtual machine down to the
 435  * given size.
 436  * @param   ep      The program with the given virtual machine.
 437  * @param   down_to The given size.
 438  * @ingroup Embryo_Heap_Group
 439  */
 440 EAPI void             embryo_data_heap_pop(Embryo_Program *ep, Embryo_Cell down_to);
 441
 442 /**
 443  * Returns the number of virtual machines are running for the given program.
 444  * @param   ep The given program.
 445  * @return  The number of virtual machines running.
 446  * @ingroup Embryo_Run_Group
 447  */
 448
 449 /**
 450  * @defgroup Embryo_Run_Group Program Run Functions
 451  *
 452  * Functions that are involved in actually running functions in an
 453  * Embryo program.
 454  */
 455 EAPI int              embryo_program_recursion_get(Embryo_Program *ep);
 456
 457 /**
 458  * Runs the given function of the given Embryo program in the current
 459  * virtual machine.  The parameter @p fn can be found using
 460  * @ref embryo_program_function_find.
 461  *
 462  * @note For Embryo to be able to run a function, it must have been
 463  *       declared @c public in the Small source code.
 464  *
 465  * @param   ep The given program.
 466  * @param   fn The given function.  Normally "main", in which case the
 467  *             constant @c EMBRYO_FUNCTION_MAIN can be used.
 468  * @return  @c EMBRYO_PROGRAM_OK on success.  @c EMBRYO_PROGRAM_SLEEP if the
 469  *          program is halted by the Small @c sleep call.
 470  *          @c EMBRYO_PROGRAM_FAIL if there is an error.
 471  *          @c EMBRYO_PROGRAM_TOOLONG if the program executes for longer than
 472  *          it is allowed to in abstract machine instruction count.
 473  * @ingroup Embryo_Run_Group
 474  */
 475 EAPI Embryo_Status    embryo_program_run(Embryo_Program *ep, Embryo_Function func);
 476
 477 /**
 478  * Retreives the return value of the last called function of the given
 479  * program.
 480  * @param   ep The given program.
 481  * @return  An Embryo_Cell representing the return value of the function
 482  *          that was last called.
 483  * @ingroup Embryo_Run_Group
 484  */
 485 EAPI Embryo_Cell      embryo_program_return_value_get(Embryo_Program *ep);
 486
 487 /**
 488  * Sets the maximum number of abstract machine cycles any given program run
 489  * can execute before being put to sleep and returning.
 490  *
 491  * @param   ep The given program.
 492  * @param   max The number of machine cycles as a limit.
 493  *
 494  * This sets the maximum number of abstract machine (virtual machine)
 495  * instructions that a single run of an embryo function (even if its main)
 496  * can use before embryo embryo_program_run() reutrns with the value
 497  * EMBRYO_PROGRAM_TOOLONG. If the function fully executes within this number
 498  * of cycles, embryo_program_run() will return as normal with either
 499  * EMBRYO_PROGRAM_OK, EMBRYO_PROGRAM_FAIL or EMBRYO_PROGRAM_SLEEP. If the
 500  * run exceeds this instruction count, then EMBRYO_PROGRAM_TOOLONG will be
 501  * returned indicating the program exceeded its run count. If the app wishes
 502  * to continue running this anyway - it is free to process its own events or
 503  * whatever it wants and continue the function by calling
 504  * embryo_program_run(program, EMBRYO_FUNCTION_CONT); which will start the
 505  * run again until the instruction count is reached. This can keep being done
 506  * to allow the calling program to still be able to control things outside the
 507  * embryo function being called. If the maximum run cycle count is 0 then the
 508  * program is allowed to run forever only returning when it is done.
 509  *
 510  * It is important to note that abstract machine cycles are NOT the same as
 511  * the host machine cpu cycles. They are not fixed in runtime per cycle, so
 512  * this is more of a helper tool than a way to HARD-FORCE a script to only
 513  * run for a specific period of time. If the cycle count is set to something
 514  * low like 5000 or 1000, then every 1000 (or 5000) cycles control will be
 515  * returned to the calling process where it can check a timer to see if a
 516  * physical runtime limit has been elapsed and then abort running further
 517  * assuming a "runaway script" or keep continuing the script run. This
 518  * limits resolution to only that many cycles which do not take a determined
 519  * amount of time to execute, as this varies from cpu to cpu and also depends
 520  * on how loaded the system is. Making the max cycle run too low will
 521  * impact performance requiring the abstract machine to do setup and teardown
 522  * cycles too often comapred to cycles actually executed.
 523  *
 524  * Also note it does NOT include nested abstract machines. IF this abstract
 525  * machine run calls embryo script that calls a native function that in turn
 526  * calls more embryo script, then the 2nd (and so on) levels are not included
 527  * in this run count. They can set their own max instruction count values
 528  * separately.
 529  *
 530  * The default max cycle run value is 0 in any program until set with this
 531  * function.
 532  *
 533  * @ingroup Embryo_Run_Group
 534  */
 535 EAPI void             embryo_program_max_cycle_run_set(Embryo_Program *ep, int max);
 536
 537 /**
 538  * Retreives the maximum number of abstract machine cycles a program is allowed
 539  * to run.
 540  * @param   ep The given program.
 541  * @return  The number of cycles a run cycle is allowed to run for this
 542  *          program.
 543  *
 544  * This returns the value set by embryo_program_max_cycle_run_set(). See
 545  * embryo_program_max_cycle_run_set() for more information.
 546  *
 547  * @ingroup Embryo_Run_Group
 548  */
 549 EAPI int              embryo_program_max_cycle_run_get(Embryo_Program *ep);
 550
 551 /**
 552  * Pushes an Embryo_Cell onto the function stack to use as a parameter for
 553  * the next function that is called in the given program.
 554  * @param   ep   The given program.
 555  * @param   cell The Embryo_Cell to push onto the stack.
 556  * @return  @c 1 if successful.  @c 0 otherwise.
 557  * @ingroup Embryo_Parameter_Group
 558  */
 559
 560 /**
 561  * @defgroup Embryo_Parameter_Group Function Parameter Functions
 562  *
 563  * Functions that set parameters for the next function that is called.
 564  */
 565 EAPI int              embryo_parameter_cell_push(Embryo_Program *ep, Embryo_Cell cell);
 566
 567 /**
 568  * Pushes a string onto the function stack to use as a parameter for the
 569  * next function that is called in the given program.
 570  * @param   ep The given program.
 571  * @param   str The string to push onto the stack.
 572  * @return  @c 1 if successful.  @c 0 otherwise.
 573  * @ingroup Embryo_Parameter_Group
 574  */
 575 EAPI int              embryo_parameter_string_push(Embryo_Program *ep, const char *str);
 576
 577 /**
 578  * Pushes an array of Embryo_Cells onto the function stack to be used as
 579  * parameters for the next function that is called in the given program.
 580  * @param   ep    The given program.
 581  * @param   cells The array of Embryo_Cells.
 582  * @param   num   The number of cells in @p cells.
 583  * @return  @c 1 if successful.  @c 0 otherwise.
 584  * @ingroup Embryo_Parameter_Group
 585  */
 586 EAPI int              embryo_parameter_cell_array_push(Embryo_Program *ep, Embryo_Cell *cells, int num);
 587
 588 #ifdef  __cplusplus
 589 }
 590 #endif
 591
 592 #endif