1 /** 2 @brief Embryo Library 3 4 These routines are used for Embryo. 5 6 @page embryo_main Embryo 7 8 @date 2004 (created) 9 @note based on Compuphase (http://www.compuphase.com) PAWN language. 10 11 @section embryo_toc Table of Contents 12 13 @li @ref embryo_main_intro 14 @li @ref embryo_main_compiling 15 @li @ref embryo_main_next_steps 16 17 @section embryo_main_intro Introduction 18 19 Embryo is a tiny library designed to interpret limited Small programs 20 compiled by the included compiler, @c embryo_cc. It is mostly a cleaned 21 up and smaller version of the original Small abstract machine. The 22 compiler is mostly untouched. 23 24 Small was renamed to Pawn. 25 For more information about the Pawn language, see 26 @htmlonly <a href=http://www.compuphase.com/pawn/pawn.htm>Pawn</a> 27 @endhtmlonly 28 @latexonly http://www.compuphase.com/pawn/pawn.htm @endlatexonly 29 For the basics about the Small language, see @ref Small_Page. 30 31 @section embryo_main_compiling How to compile 32 33 Embryo is a library your application links to. The procedure for this 34 is very simple. You simply have to compile your application with the 35 appropriate compiler flags that the @p pkg-config script outputs. For 36 example: 37 38 Compiling C or C++ files into object files: 39 40 @verbatim 41 gcc -c -o main.o main.c `pkg-config --cflags embryo` 42 @endverbatim 43 44 Linking object files into a binary executable: 45 46 @verbatim 47 gcc -o my_application main.o `pkg-config --libs embryo` 48 @endverbatim 49 50 See @ref pkgconfig 51 52 @section embryo_main_next_steps Next Steps 53 54 After you understood what Embryo is and installed it in your system you 55 should proceed understanding the programming interface. 56 57 Recommended reading: 58 59 @li @ref Embryo_Program_Creation_Group to create Embryo from memory or file. 60 @li @ref Embryo_Func_Group to expose functions to Embryo. 61 @li @ref Embryo_Program_VM_Group to push pop virtual machine. 62 @li @ref Embryo_Run_Group to run it. 63 64 65 66 @todo Clean up compiler code. 67 @todo Proper overview of the operation of the interpreter, that is how 68 the heap, stack, virtual machines, etc fit together. 69 70 @page Small_Page Brief Introduction to Small 71 72 This section describes the basics of Small, as compiled and interpreted 73 with Embryo. 74 75 This summary assumes that you are familar with C. For a full list of 76 differences between C and Small, again, see the full documentation. 77 78 @section Small_Variables_Section Variables 79 80 @subsection Small_Type_Subsection Types 81 82 There is only one type, known as the "cell", which can hold an integer. 83 84 @subsection Small_Scope_Subsection Scope 85 86 The scope and usage of a variable depends on its declaration. 87 88 @li A local variable is normally declared with the @c new keyword. E.g. 89 @code new variable @endcode 90 @li A static function variable is defined within a function with the 91 @c static keyword. 92 @li A global static variable is one that is only available within the 93 file it was declared in. Again, use the @c static keyword, but outside 94 of any function. 95 @li A stock variable is one that may not be compiled into a program if it 96 is not used. It is declared using @c stock. 97 @li A public variable is one that can be read by the host program using 98 @ref embryo_program_variable_find. It is declared using @c public 99 keyword. 100 101 Remember that the keywords above are to be used on their own. That is, 102 for example: @code public testvar @endcode not: 103 @code new public testvar @endcode 104 105 @subsection Small_Constants_Subsection Constants 106 107 You can declare constants in two ways: 108 @li Using the preprocessor macro @c \#define. 109 @li By inserting @c const between the keyword and variable name of a 110 variable declaration. For example, to declare the variable @c var1 111 constant, you type @code new const var1 = 2 @endcode Now @c var1 112 cannot be changed. 113 114 @subsection Small_Arrays_Subsection Arrays 115 116 To declare an array, append square brackets to the end of the variable 117 name. The following examples show how to declare arrays. Note the 118 use of the ellipsis operator, which bases the array based on the last two 119 declared values: 120 121 @code 122 new msg[] = "A message." 123 new ints[] = {1, 3, 4} 124 new ints2[20] = {1, 3} // All other elements 0. 125 new ints3[10] = {1, ... } // All elements = 1 126 new ints4[10] = {10, 20, ... } // Elements = 10 -> 100. 127 // The difference can be negative. 128 new ints5[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}} 129 @endcode 130 131 @note Array initialisers need to be constant. 132 133 @section Small_Func_Calls_Section Function Calls 134 135 A typical function declaration is as follows: 136 137 @code 138 testfunc(param) { 139 // Do something ... 140 // over a couple of lines. 141 } 142 @endcode 143 144 You can pass by reference. That is, the parameter you pass is changed 145 outside of the function. For example: 146 147 @code 148 testfunc(¶m) { 149 param = 10 150 // The passed variable will be set to 10 outside of the function. 151 } 152 @endcode 153 154 To pass an array: 155 156 @code 157 testfunc(param[]) { 158 // Do something to the array 159 } 160 @endcode 161 162 @note Arrays are passed by reference. 163 164 @section Small_Control_Subsection Control Structures. 165 166 Small has the following control structures, which similar to their C 167 counterparts: 168 @li @code if (expression) statement1 else statement2 @endcode 169 @li @code switch (expression) { 170 case 0: 171 statement1 // Can only be one statement. Look Ma, no breaks! 172 case 1..3: // For values between 1 and 3 inclusive. 173 statement2 174 default: // Optional 175 statement3 176 } 177 @endcode 178 @li @code while(expression) statement @endcode 179 @li @code do statement while (expression) @endcode 180 @li @code for (init_expression; before_iter_test_expression; after_iter_expression) statement @endcode 181 182 @section Small_Preprocessor_Section Preprocessor 183 184 The following preprocessor directives are available: 185 @li @code #assert constant_expression @endcode 186 @li @code #define pattern replacement @endcode 187 @li @code #define pattern(%1,%2,...) replacement @endcode 188 @li @code #include filename @endcode 189 @li @code #if constant_expression 190 // Various bits of code 191 #else 192 // Other bits of code 193 #endif 194 @endcode 195 @li @code #undef pattern @endcode 196 197 198 @page Available_Native_Calls_Page Available Calls 199 200 Embryo provides a minimal set of native calls that can be used within 201 any Embryo script. Those calls are detailed here. 202 203 @note Some of the "core" functions here are also described in the full 204 Small documentation given 205 206 @todo Finish this section. 207 208 @section Args_ANC_Section Argument Functions 209 210 @subsection Numargs_Desc numargs 211 212 Returns the number of arguments passed to a function. Useful 213 when dealing with variable argument lists. 214 215 @subsection Getargs_Desc getarg(arg, index=0) 216 217 Retrieves the argument number @c arg. If the argument is an array, 218 use @c index to specify the index of the array to return. 219 220 @subsection Setargs_Desc setargs(arg, index=0, value) 221 222 Sets the argument number @c arg to the given @c arg. @c index specifies 223 the index of @c arg to set if @c arg is an array. 224 225 @section String_ANC_Section String Functions 226 227 Functions that work on strings. 228 229 @subsection Atoi_Desc atoi 230 231 Translates an number in string form into an integer. 232 233 @subsection Fnmatch_Desc fnmatch 234 235 Buggered if I know what this does? 236 237 @subsection Strcmp_Desc strcmp 238 239 String comparing function. 240 241 242 @section Float_ANC_Section Float Functions 243 244 @subsection Float_Desc float 245 246 @subsection Atof_Desc atof 247 248 @subsection Float_Mul_Desc float_mul 249 250 @subsection Float_Div_Desc float_div 251 252 @subsection Float_Add_Desc float_add 253 254 @subsection Float_Sub_Desc float_sub 255 256 @subsection Fract_Desc fract 257 258 @subsection Round_Desc round 259 260 @subsection Float_Cmp_Desc float_cmp 261 262 @subsection Sqrt_Desc sqrt 263 264 @subsection Pow_Desc pow 265 266 @subsection Log_Desc log 267 268 @subsection Sin_Desc sin 269 270 @subsection Cos_Desc cos 271 272 @subsection Tan_Desc tan 273 274 @subsection Abs_Desc abs 275 276 Returns the absolute value of the given float. 277 278 @section Time_ANC_Section Time Functions 279 280 @subsection Seconds_Desc seconds() 281 282 @subsection Date_Desc date 283 284 285 @section Rand_ANC_Section Random Functions 286 287 @subsection Rand_Desc rand() 288 289 Returns a random integer. 290 291 @subsection Randf_Desc randf() 292 293 Returns a random float. 294 295 @file Embryo.h 296 @brief Embryo virtual machine library. 297 298 This file includes the routines needed for Embryo library interaction. 299 This is the @e only file you need to include. 300 301 */ 302 303 // The following definitions are in Embryo.h, but I did not want to 304 // mess up the formatting of the file 305 306 /** 307 @def EMBRYO_FUNCTION_NONE 308 An invalid/non-existent function. 309 */ 310 311 /** 312 @def EMBRYO_FUNCTION_MAIN 313 Start at program entry point. For use with @ref embryo_program_run. 314 */ 315 316 /** 317 @def EMBRYO_FUNCTION_CONT 318 Continue from last address. For use with @ref embryo_program_run. 319 */ 320 321 /** 322 @def EMBRYO_PROGRAM_OK 323 Program was run successfully. 324 */ 325 326 /** 327 @def EMBRYO_PROGRAM_SLEEP 328 The program's execution was interrupted by a Small @c sleep command. 329 */ 330 331 /** 332 @def EMBRYO_PROGRAM_FAIL 333 An error in the program caused it to fail. 334 */ 335 336 #ifndef _EMBRYO_H 337 #define _EMBRYO_H 338 339 #include <Efl_Config.h> 340 341 #ifdef EAPI 342 # undef EAPI 343 #endif 344 345 #ifdef _WIN32 346 # ifdef EFL_BUILD 347 # ifdef DLL_EXPORT 348 # define EAPI __declspec(dllexport) 349 # else 350 # define EAPI 351 # endif 352 # else 353 # define EAPI __declspec(dllimport) 354 # endif 355 #else 356 # ifdef __GNUC__ 357 # if __GNUC__ >= 4 358 # define EAPI __attribute__ ((visibility("default"))) 359 # else 360 # define EAPI 361 # endif 362 # else 363 # define EAPI 364 # endif 365 #endif 366 367 #ifdef __cplusplus 368 extern "C" { 369 #endif 370 371 #define EMBRYO_VERSION_MAJOR EFL_VERSION_MAJOR 372 #define EMBRYO_VERSION_MINOR EFL_VERSION_MINOR 373 374 /** 375 * @typedef Embryo_Version 376 * Represents the current version of Embryo 377 */ 378 typedef struct _Embryo_Version 379 { 380 int major; /** < major (binary or source incompatible changes) */ 381 int minor; /** < minor (new features, bugfixes, major improvements version) */ 382 int micro; /** < micro (bugfix, internal improvements, no new features version) */ 383 int revision; /** < git revision (0 if a proper release or the git revision number Embryo is built from) */ 384 } Embryo_Version; 385 386 EAPI extern Embryo_Version *embryo_version; 387 388 /* potential error values */ 389 typedef enum _Embryo_Error 390 { 391 EMBRYO_ERROR_NONE, 392 /* reserve the first 15 error codes for exit codes of the abstract machine */ 393 EMBRYO_ERROR_EXIT, /** Forced exit */ 394 EMBRYO_ERROR_ASSERT, /** Assertion failed */ 395 EMBRYO_ERROR_STACKERR, /** Stack/heap collision */ 396 EMBRYO_ERROR_BOUNDS, /** Index out of bounds */ 397 EMBRYO_ERROR_MEMACCESS, /** Invalid memory access */ 398 EMBRYO_ERROR_INVINSTR, /** Invalid instruction */ 399 EMBRYO_ERROR_STACKLOW, /** Stack underflow */ 400 EMBRYO_ERROR_HEAPLOW, /** Heap underflow */ 401 EMBRYO_ERROR_CALLBACK, /** No callback, or invalid callback */ 402 EMBRYO_ERROR_NATIVE, /** Native function failed */ 403 EMBRYO_ERROR_DIVIDE, /** Divide by zero */ 404 EMBRYO_ERROR_SLEEP, /** Go into sleepmode - code can be restarted */ 405 406 EMBRYO_ERROR_MEMORY = 16, /** Out of memory */ 407 EMBRYO_ERROR_FORMAT, /** Invalid file format */ 408 EMBRYO_ERROR_VERSION, /** File is for a newer version of the Embryo_Program */ 409 EMBRYO_ERROR_NOTFOUND, /** Function not found */ 410 EMBRYO_ERROR_INDEX, /** Invalid index parameter (bad entry point) */ 411 EMBRYO_ERROR_DEBUG, /** Debugger cannot run */ 412 EMBRYO_ERROR_INIT, /** Embryo_Program not initialized (or doubly initialized) */ 413 EMBRYO_ERROR_USERDATA, /** Unable to set user data field (table full) */ 414 EMBRYO_ERROR_INIT_JIT, /** Cannot initialize the JIT */ 415 EMBRYO_ERROR_PARAMS, /** Parameter error */ 416 EMBRYO_ERROR_DOMAIN, /** Domain error, expression result does not fit in range */ 417 } Embryo_Error; 418 419 /* program run return values */ 420 typedef enum _Embryo_Status 421 { 422 EMBRYO_PROGRAM_FAIL = 0, 423 EMBRYO_PROGRAM_OK = 1, 424 EMBRYO_PROGRAM_SLEEP = 2, 425 EMBRYO_PROGRAM_BUSY = 3, 426 EMBRYO_PROGRAM_TOOLONG = 4 427 } Embryo_Status; 428 429 typedef unsigned int Embryo_UCell; 430 typedef int Embryo_Cell; 431 /** An invalid cell reference */ 432 #define EMBRYO_CELL_NONE 0x7fffffff 433 434 typedef struct _Embryo_Program Embryo_Program; 435 typedef int Embryo_Function; 436 /* possible function type values that are enumerated */ 437 #define EMBRYO_FUNCTION_NONE 0x7fffffff /* An invalid/non existent function */ 438 #define EMBRYO_FUNCTION_MAIN -1 /* Start at program entry point */ 439 #define EMBRYO_FUNCTION_CONT -2 /* Continue from last address */ 440 441 typedef union 442 { 443 float f; 444 Embryo_Cell c; 445 } Embryo_Float_Cell; 446 447 #if defined _MSC_VER || defined __SUNPRO_C 448 /** Float to Embryo_Cell */ 449 # define EMBRYO_FLOAT_TO_CELL(f) (((Embryo_Float_Cell *)&(f))->c) 450 /** Embryo_Cell to float */ 451 # define EMBRYO_CELL_TO_FLOAT(c) (((Embryo_Float_Cell *)&(c))->f) 452 #else 453 /** Float to Embryo_Cell */ 454 # define EMBRYO_FLOAT_TO_CELL(f) ((Embryo_Float_Cell) f).c 455 /** Embryo_Cell to float */ 456 # define EMBRYO_CELL_TO_FLOAT(c) ((Embryo_Float_Cell) c).f 457 #endif 458 459 /** 460 * @defgroup Embryo_Library_Group Library Maintenance Functions 461 * @ingroup Embryo 462 * 463 * Functions that start up and shutdown the Embryo library. 464 */ 465 466 467 /** 468 * Initialises the Embryo library. 469 * @return The number of times the library has been initialised without being 470 * shut down. 471 * @ingroup Embryo_Library_Group 472 */ 473 EAPI int embryo_init(void); 474 475 /** 476 * Shuts down the Embryo library. 477 * @return The number of times the library has been initialised without being 478 * shutdown. 479 * @ingroup Embryo_Library_Group 480 */ 481 EAPI int embryo_shutdown(void); 482 483 /** 484 * @defgroup Embryo_Program_Creation_Group Program Creation and Destruction Functions 485 * @ingroup Embryo 486 * 487 * Functions that set up programs, and destroy them. 488 */ 489 490 /** 491 * Creates a new Embryo program, with bytecode data that can be freed. 492 * @param data Pointer to the bytecode of the program. 493 * @param size Number of bytes of bytecode. 494 * @return A new Embryo program. 495 * @ingroup Embryo_Program_Creation_Group 496 */ 497 EAPI Embryo_Program *embryo_program_new(void *data, int size); 498 499 /** 500 * Creates a new Embryo program, with bytecode data that cannot be 501 * freed. 502 * @param data Pointer to the bytecode of the program. 503 * @param size Number of bytes of bytecode. 504 * @return A new Embryo program. 505 * @ingroup Embryo_Program_Creation_Group 506 */ 507 EAPI Embryo_Program *embryo_program_const_new(void *data, int size); 508 509 /** 510 * Creates a new Embryo program based on the bytecode data stored in the 511 * given file. 512 * @param file Filename of the given file. 513 * @return A new Embryo program. 514 * @ingroup Embryo_Program_Creation_Group 515 */ 516 EAPI Embryo_Program *embryo_program_load(const char *file); 517 518 /** 519 * Frees the given Embryo program. 520 * @param ep The given program. 521 * @ingroup Embryo_Program_Creation_Group 522 */ 523 EAPI void embryo_program_free(Embryo_Program *ep); 524 525 /** 526 * @defgroup Embryo_Func_Group Function Functions 527 * @ingroup Embryo 528 * 529 * Functions that deal with Embryo program functions. 530 */ 531 532 /** 533 * Adds a native program call to the given Embryo program. 534 * @param ep The given Embryo program. 535 * @param name The name for the call used in the script. 536 * @param func The function to use when the call is made. 537 * @ingroup Embryo_Func_Group 538 */ 539 EAPI void embryo_program_native_call_add(Embryo_Program *ep, const char *name, Embryo_Cell (*func) (Embryo_Program *ep, Embryo_Cell *params)); 540 541 /** 542 * @defgroup Embryo_Program_VM_Group Virtual Machine Functions 543 * @ingroup Embryo 544 * 545 * Functions that deal with creating and destroying virtual machine sessions 546 * for a given program. 547 * 548 * A given embryo program can have multiple virtual machine sessions running. 549 * This is useful when you have a native call that in turn calls a function in 550 * the embryo program. The native call can start a new virtual machine 551 * session to run the function it needs. Once completed, the session can be 552 * popped off the program's stack, and the native call can return its value 553 * to the old session. 554 * 555 * A new virtual machine session is created by pushing a new virtual machine 556 * onto the session stack of a program using @ref embryo_program_vm_push. 557 * The current virtual machine session can be destroyed by calling 558 * @ref embryo_program_vm_pop. 559 */ 560 561 /** 562 * Resets the current virtual machine session of the given program. 563 * @param ep The given program. 564 * @ingroup Embryo_Program_VM_Group 565 */ 566 EAPI void embryo_program_vm_reset(Embryo_Program *ep); 567 568 /** 569 * Starts a new virtual machine session for the given program. 570 * 571 * See @ref Embryo_Program_VM_Group for more information about how this works. 572 * 573 * @param ep The given program. 574 * @ingroup Embryo_Program_VM_Group 575 */ 576 EAPI void embryo_program_vm_push(Embryo_Program *ep); 577 578 /** 579 * Frees the current virtual machine session associated with the given program. 580 * 581 * See @ref Embryo_Program_VM_Group for more information about how this works. 582 * Note that you will need to retrieve any return data or data on the stack 583 * before you pop. 584 * 585 * @param ep The given program. 586 * @ingroup Embryo_Program_VM_Group 587 */ 588 EAPI void embryo_program_vm_pop(Embryo_Program *ep); 589 590 /** 591 * @defgroup Embryo_Swap_Group Byte Swapping Functions 592 * @ingroup Embryo 593 * 594 * Functions that are used to ensure that integers passed to the 595 * virtual machine are in small endian format. These functions are 596 * used to ensure that the virtual machine operates correctly on big 597 * endian machines. 598 */ 599 600 /** 601 * Ensures that the given unsigned short integer is in the small 602 * endian format. 603 * @param v Pointer to the given integer. 604 * @ingroup Embryo_Swap_Group 605 */ 606 EAPI void embryo_swap_16(unsigned short *v); 607 608 /** 609 * Ensures that the given unsigned integer is in the small endian 610 * format. 611 * @param v Pointer to the given integer. 612 * @ingroup Embryo_Swap_Group 613 */ 614 EAPI void embryo_swap_32(unsigned int *v); 615 616 /** 617 * Returns the function in the given program with the given name. 618 * @param ep The given program. 619 * @param name The given function name. 620 * @return The function if successful. Otherwise, @c EMBRYO_FUNCTION_NONE. 621 * @ingroup Embryo_Func_Group 622 */ 623 EAPI Embryo_Function embryo_program_function_find(Embryo_Program *ep, const char *name); 624 625 /** 626 * @defgroup Embryo_Public_Variable_Group Public Variable Access Functions 627 * @ingroup Embryo 628 * 629 * In an Embryo program, a global variable can be declared public, as 630 * described in @ref Small_Scope_Subsection. The functions here allow 631 * the host program to access these public variables. 632 */ 633 634 /** 635 * Retrieves the location of the public variable in the given program 636 * with the given name. 637 * @param ep The given program. 638 * @param name The given name. 639 * @return The address of the variable if found. @c EMBRYO_CELL_NONE 640 * otherwise. 641 * @ingroup Embryo_Public_Variable_Group 642 */ 643 EAPI Embryo_Cell embryo_program_variable_find(Embryo_Program *ep, const char *name); 644 645 /** 646 * Retrieves the number of public variables in the given program. 647 * @param ep The given program. 648 * @return The number of public variables. 649 * @ingroup Embryo_Public_Variable_Group 650 */ 651 EAPI int embryo_program_variable_count_get(Embryo_Program *ep); 652 653 /** 654 * Retrieves the location of the public variable in the given program 655 * with the given identifier. 656 * @param ep The given program. 657 * @param num The identifier of the public variable. 658 * @return The virtual machine address of the variable if found. 659 * @c EMBRYO_CELL_NONE otherwise. 660 * @ingroup Embryo_Public_Variable_Group 661 */ 662 EAPI Embryo_Cell embryo_program_variable_get(Embryo_Program *ep, int num); 663 664 /** 665 * @defgroup Embryo_Error_Group Error Functions 666 * @ingroup Embryo 667 * 668 * Functions that set and retrieve error codes in Embryo programs. 669 */ 670 671 /** 672 * Sets the error code for the given program to the given code. 673 * @param ep The given program. 674 * @param error The given error code. 675 * @ingroup Embryo_Error_Group 676 */ 677 EAPI void embryo_program_error_set(Embryo_Program *ep, Embryo_Error error); 678 679 /** 680 * Retrieves the current error code for the given program. 681 * @param ep The given program. 682 * @return The current error code. 683 * @ingroup Embryo_Error_Group 684 */ 685 EAPI Embryo_Error embryo_program_error_get(Embryo_Program *ep); 686 687 /** 688 * @defgroup Embryo_Program_Data_Group Program Data Functions 689 * @ingroup Embryo 690 * 691 * Functions that set and retrieve data associated with the given 692 * program. 693 */ 694 695 /** 696 * Sets the data associated to the given program. 697 * @param ep The given program. 698 * @param data New bytecode data. 699 * @ingroup Embryo_Program_Data_Group 700 */ 701 EAPI void embryo_program_data_set(Embryo_Program *ep, void *data); 702 703 /** 704 * Retrieves the data associated to the given program. 705 * @param ep The given program. 706 * @ingroup Embryo_Program_Data_Group 707 */ 708 EAPI void *embryo_program_data_get(Embryo_Program *ep); 709 710 /** 711 * Retrieves a string describing the given error code. 712 * @param error The given error code. 713 * @return String describing the given error code. If the given code is not 714 * known, the string "(unknown)" is returned. 715 * @ingroup Embryo_Error_Group 716 */ 717 EAPI const char *embryo_error_string_get(Embryo_Error error); 718 719 /** 720 * @defgroup Embryo_Data_String_Group Embryo Data String Functions 721 * @ingroup Embryo 722 * 723 * Functions that operate on strings in the memory of a virtual machine. 724 */ 725 726 /** 727 * Retrieves the length of the string starting at the given cell. 728 * @param ep The program the cell is part of. 729 * @param str_cell Pointer to the first cell of the string. 730 * @return The length of the string. @c 0 is returned if there is an error. 731 * @ingroup Embryo_Data_String_Group 732 */ 733 EAPI int embryo_data_string_length_get(Embryo_Program *ep, Embryo_Cell *str_cell); 734 735 /** 736 * Copies the string starting at the given cell to the given buffer. 737 * @param ep The program the cell is part of. 738 * @param str_cell Pointer to the first cell of the string. 739 * @param dst The given buffer. 740 * @ingroup Embryo_Data_String_Group 741 */ 742 EAPI void embryo_data_string_get(Embryo_Program *ep, Embryo_Cell *str_cell, char *dst); 743 744 /** 745 * Copies string in the given buffer into the virtual machine memory 746 * starting at the given cell. 747 * @param ep The program the cell is part of. 748 * @param src The given buffer. 749 * @param str_cell Pointer to the first cell to copy the string to. 750 * @ingroup Embryo_Data_String_Group 751 */ 752 EAPI void embryo_data_string_set(Embryo_Program *ep, const char *src, Embryo_Cell *str_cell); 753 754 /** 755 * Retreives a pointer to the address in the virtual machine given by the 756 * given cell. 757 * @param ep The program whose virtual machine address is being queried. 758 * @param addr The given cell. 759 * @return A pointer to the cell at the given address. 760 * @ingroup Embryo_Data_String_Group 761 */ 762 EAPI Embryo_Cell *embryo_data_address_get(Embryo_Program *ep, Embryo_Cell addr); 763 764 /** 765 * @defgroup Embryo_Heap_Group Heap Functions 766 * @ingroup Embryo 767 * 768 * The heap is an area of memory that can be allocated for program 769 * use at runtime. The heap functions here change the amount of heap 770 * memory available. 771 */ 772 773 /** 774 * Increases the size of the heap of the given virtual machine by the given 775 * number of Embryo_Cells. 776 * @param ep The program with the given virtual machine. 777 * @param cells The given number of Embryo_Cells. 778 * @return The address of the new memory region on success. 779 * @c EMBRYO_CELL_NONE otherwise. 780 * @ingroup Embryo_Heap_Group 781 */ 782 EAPI Embryo_Cell embryo_data_heap_push(Embryo_Program *ep, int cells); 783 784 /** 785 * Decreases the size of the heap of the given virtual machine down to the 786 * given size. 787 * @param ep The program with the given virtual machine. 788 * @param down_to The given size. 789 * @ingroup Embryo_Heap_Group 790 */ 791 EAPI void embryo_data_heap_pop(Embryo_Program *ep, Embryo_Cell down_to); 792 793 /** 794 * @defgroup Embryo_Run_Group Program Run Functions 795 * @ingroup Embryo 796 * 797 * Functions that are involved in actually running functions in an 798 * Embryo program. 799 */ 800 801 /** 802 * Returns the number of virtual machines are running for the given program. 803 * @param ep The given program. 804 * @return The number of virtual machines running. 805 * @ingroup Embryo_Run_Group 806 */ 807 EAPI int embryo_program_recursion_get(Embryo_Program *ep); 808 809 /** 810 * Runs the given function of the given Embryo program in the current 811 * virtual machine. The parameter @p fn can be found using 812 * @ref embryo_program_function_find. 813 * 814 * @note For Embryo to be able to run a function, it must have been 815 * declared @c public in the Small source code. 816 * 817 * @param ep The given program. 818 * @param func The given function. Normally "main", in which case the 819 * constant @c EMBRYO_FUNCTION_MAIN can be used. 820 * @return @c EMBRYO_PROGRAM_OK on success. @c EMBRYO_PROGRAM_SLEEP if the 821 * program is halted by the Small @c sleep call. 822 * @c EMBRYO_PROGRAM_FAIL if there is an error. 823 * @c EMBRYO_PROGRAM_TOOLONG if the program executes for longer than 824 * it is allowed to in abstract machine instruction count. 825 * @ingroup Embryo_Run_Group 826 */ 827 EAPI Embryo_Status embryo_program_run(Embryo_Program *ep, Embryo_Function func); 828 829 /** 830 * Retreives the return value of the last called function of the given 831 * program. 832 * @param ep The given program. 833 * @return An Embryo_Cell representing the return value of the function 834 * that was last called. 835 * @ingroup Embryo_Run_Group 836 */ 837 EAPI Embryo_Cell embryo_program_return_value_get(Embryo_Program *ep); 838 839 /** 840 * Sets the maximum number of abstract machine cycles any given program run 841 * can execute before being put to sleep and returning. 842 * 843 * @param ep The given program. 844 * @param max The number of machine cycles as a limit. 845 * 846 * This sets the maximum number of abstract machine (virtual machine) 847 * instructions that a single run of an embryo function (even if its main) 848 * can use before embryo embryo_program_run() reutrns with the value 849 * EMBRYO_PROGRAM_TOOLONG. If the function fully executes within this number 850 * of cycles, embryo_program_run() will return as normal with either 851 * EMBRYO_PROGRAM_OK, EMBRYO_PROGRAM_FAIL or EMBRYO_PROGRAM_SLEEP. If the 852 * run exceeds this instruction count, then EMBRYO_PROGRAM_TOOLONG will be 853 * returned indicating the program exceeded its run count. If the app wishes 854 * to continue running this anyway - it is free to process its own events or 855 * whatever it wants and continue the function by calling 856 * embryo_program_run(program, EMBRYO_FUNCTION_CONT); which will start the 857 * run again until the instruction count is reached. This can keep being done 858 * to allow the calling program to still be able to control things outside the 859 * embryo function being called. If the maximum run cycle count is 0 then the 860 * program is allowed to run forever only returning when it is done. 861 * 862 * It is important to note that abstract machine cycles are NOT the same as 863 * the host machine cpu cycles. They are not fixed in runtime per cycle, so 864 * this is more of a helper tool than a way to HARD-FORCE a script to only 865 * run for a specific period of time. If the cycle count is set to something 866 * low like 5000 or 1000, then every 1000 (or 5000) cycles control will be 867 * returned to the calling process where it can check a timer to see if a 868 * physical runtime limit has been elapsed and then abort running further 869 * assuming a "runaway script" or keep continuing the script run. This 870 * limits resolution to only that many cycles which do not take a determined 871 * amount of time to execute, as this varies from cpu to cpu and also depends 872 * on how loaded the system is. Making the max cycle run too low will 873 * impact performance requiring the abstract machine to do setup and teardown 874 * cycles too often comapred to cycles actually executed. 875 * 876 * Also note it does NOT include nested abstract machines. IF this abstract 877 * machine run calls embryo script that calls a native function that in turn 878 * calls more embryo script, then the 2nd (and so on) levels are not included 879 * in this run count. They can set their own max instruction count values 880 * separately. 881 * 882 * The default max cycle run value is 0 in any program until set with this 883 * function. 884 * 885 * @ingroup Embryo_Run_Group 886 */ 887 EAPI void embryo_program_max_cycle_run_set(Embryo_Program *ep, int max); 888 889 /** 890 * Retreives the maximum number of abstract machine cycles a program is allowed 891 * to run. 892 * @param ep The given program. 893 * @return The number of cycles a run cycle is allowed to run for this 894 * program. 895 * 896 * This returns the value set by embryo_program_max_cycle_run_set(). See 897 * embryo_program_max_cycle_run_set() for more information. 898 * 899 * @ingroup Embryo_Run_Group 900 */ 901 EAPI int embryo_program_max_cycle_run_get(Embryo_Program *ep); 902 903 /** 904 * @defgroup Embryo_Parameter_Group Function Parameter Functions 905 * @ingroup Embryo 906 * 907 * Functions that set parameters for the next function that is called. 908 */ 909 910 /** 911 * Pushes an Embryo_Cell onto the function stack to use as a parameter for 912 * the next function that is called in the given program. 913 * @param ep The given program. 914 * @param cell The Embryo_Cell to push onto the stack. 915 * @return @c 1 if successful. @c 0 otherwise. 916 * @ingroup Embryo_Parameter_Group 917 */ 918 EAPI int embryo_parameter_cell_push(Embryo_Program *ep, Embryo_Cell cell); 919 920 /** 921 * Pushes a string onto the function stack to use as a parameter for the 922 * next function that is called in the given program. 923 * @param ep The given program. 924 * @param str The string to push onto the stack. 925 * @return @c 1 if successful. @c 0 otherwise. 926 * @ingroup Embryo_Parameter_Group 927 */ 928 EAPI int embryo_parameter_string_push(Embryo_Program *ep, const char *str); 929 930 /** 931 * Pushes an array of Embryo_Cells onto the function stack to be used as 932 * parameters for the next function that is called in the given program. 933 * @param ep The given program. 934 * @param cells The array of Embryo_Cells. 935 * @param num The number of cells in @p cells. 936 * @return @c 1 if successful. @c 0 otherwise. 937 * @ingroup Embryo_Parameter_Group 938 */ 939 EAPI int embryo_parameter_cell_array_push(Embryo_Program *ep, Embryo_Cell *cells, int num); 940 941 #ifdef __cplusplus 942 } 943 #endif 944 945 #undef EAPI 946 #define EAPI 947 948 #endif 949