aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorStefan Bucur <stefanb@zytor.com>2008-08-16 17:03:10 +0300
committerStefan Bucur <stefan@stefan-ubumac.(none)>2009-03-15 10:12:28 +0200
commitd14cf8687310bd065b024e13b7d0b6159f652cc3 (patch)
treef332b233d675bdf316f7d7bfc769089dbf3cf31a
parent30b8cbc9e629b36737a64934abb55ece3d152d6c (diff)
downloadsyslinux-elf-d14cf8687310bd065b024e13b7d0b6159f652cc3.tar.gz
syslinux-elf-d14cf8687310bd065b024e13b7d0b6159f652cc3.tar.xz
syslinux-elf-d14cf8687310bd065b024e13b7d0b6159f652cc3.zip
Added source comments to the execution API header.
-rw-r--r--com32/include/sys/exec.h64
1 files changed, 64 insertions, 0 deletions
diff --git a/com32/include/sys/exec.h b/com32/include/sys/exec.h
index c839df02..7b3a9a0c 100644
--- a/com32/include/sys/exec.h
+++ b/com32/include/sys/exec.h
@@ -10,33 +10,97 @@
#include <sys/module.h>
+/**
+ * EXEC_ROOT_NAME - The name of the ELF module associated with the COM32 module.
+ *
+ * This is a shallow ELF module, that contains only the symbol table for
+ * the code and data sections of the loaded COM32 root module.
+ */
#define EXEC_ROOT_NAME "_root_.dyn"
+/**
+ * EXEC_DIRECTORY - The base path for all dynamic linked modules.
+ */
#define EXEC_DIRECTORY "/dyn/"
/**
* exec_init - Initialize the dynamic execution environment.
+ *
+ * Among others, it initializes the module subsystem and loads the root
+ * module into memory. You should note the difference between the module
+ * management API, and the execution API:
+ * - the module system is a static one - it only manages the data structures
+ * and their relationship. It does not describe the way modules are executed,
+ * when and how they are loaded/unloaded, etc. It acts as a service layer for
+ * the execution API.
+ * - the execution environment is the dynamic part of the SYSLINUX dynamic
+ * module API - it implements the behavior of the modules: it
+ * triggers the execution of initialization and termination functions for
+ * libraries, executes the modules marked as executable, handles dynamic
+ * memory cleanup, etc. In other words, at this layer the code and data
+ * loaded by the lower module layer gets to be executed by the CPU,
+ * thus becoming part of the SYSLINUX environment.
*/
extern int exec_init();
/**
* load_library - Loads a dynamic library into the environment.
+ * @name: the name of the library to load, including the extension
+ * (e.g. 'sort.dyn')
+ *
+ * A dynamic library is an ELF module that may contain initialization and
+ * termination routines, but not a main routine. At the same time, any memory
+ * allocations using malloc() and its derivatives are made on behalf of the
+ * currently executing program or the COM32 root module. If the library
+ * is unloaded, no memory cleanup is performed.
*/
extern int load_library(const char *name);
/**
* unload_library - unloads a library from the environment.
+ * @name: the name of the library to unload, including the extension
+ * (e.g. 'sort.dyn')
+ *
+ * Note that no memory allocated by the library code is cleaned up, as the
+ * allocations belong to the innermost calling program in the call stack.
*/
extern int unload_library(const char *name);
/**
* spawnv - Executes a program in the current environment.
+ * @name: the name of the program to spawn, including the extension
+ * (e.g. 'hello.dyn')
+ * @argv: a NULL-terminated vector of string arguments, starting with
+ * the program name.
+ *
+ * A program is an ELF module that contains a main routine. A program is
+ * loaded into memory, executed, then unloaded, thus remaining in memory only
+ * while the main() function is executing. A program also defines a
+ * memory allocation context, and a simple garbage collection mechanism
+ * it thus provided. This is done by internally associating with the program
+ * module each pointer returned by malloc(). After the program finishes
+ * its execution, all the unallocated memory pertaining to the program
+ * is automatically cleaned up.
+ *
+ * Note that this association takes place both for the allocations happening
+ * directly in the program, or indirectly through a library function. Libraries
+ * do not create allocation contexts, thus each allocation they made belong
+ * to the innermost calling program.
*/
extern int spawnv(const char *name, const char **argv);
/**
* spawnl - Executes a program in the current environment.
+ * @name: the name of the program to spawn, including the extension
+ * (e.g. 'hello.dyn')
+ * @arg: the first argument (argv[0]) to be passed to the main function
+ * of the program
+ * @...: optional subsequent arguments that are passed o the main function
+ * of the program
+ *
+ * This is another version of the spawn routine. Please see 'spawnv' for
+ * a full presentation.
*/
extern int spawnl(const char *name, const char *arg, ...);