This header contains all needed functions to alter the virtual machine from plugins written for it.
These plugins allow users to improve the architecture of the machine by defining their own:
- instructions: allows extension of the SVM processors instruction set,
- memory types: allows extension of the SVM memory storage capacity,
- interruptions: allows dedicated interruptions of a processor,
- sequencers: allows extension of the sequencing of kernels with processes,
- schedulers: allows extension of the orchestration of processes within the virtual machine,
- functions: allows inter plugin communication by acting like private instructions,
- structures: also allows inter plugin communication by acting like private types.
Such objects are defined by a (rather long) string describing each of them and their dependencies on other plugin objects by a call to the svm_plugin_configure API special function.
Associated to each object and to give them life, some particular plugin callback functions have to be defined:
- For instructions:
SVM_TYPE typedef unsigned long int SVM_Size
This type is used to represent an object size.
Definition: svm.h:257
SVM_TYPE typedef const void * SVM_Parameter
This type is used by the SVM to pass instruction parameters to the corresponding plugin function.
Definition: svm.h:180
SVM_TYPE typedef const void * SVM_Value
This type is used to represent any value the SVM can store in one of its memories.
Definition: svm.h:530
- For types:
void type_<type name>_delete(const void *svm, void *handler);
void* type_<type name>_copy(const void *svm, const void *handler);
void* type_<type name>_constant(
const void *svm,
const SVM_String value);
SVM_String type_<type name>_print(
const void *svm,
const void *handler);
- For interruptions: No plugin callback to be defined.
- For sequencers:
void* sequencer_<sequencer name>_create(const void *svm);
void sequencer_<sequencer name>_delete(const void *svm, const void *handler);
SVM_Kernel sequencer_<sequencer name>_current(
const void *svm,
const void *handler);
SVM_String sequencer_<sequencer name>_print(
const void *svm,
const void *handler);
SVM_TYPE typedef const void * SVM_Kernel
This type is used to represent an atomic execution environment.
Definition: svm.h:284
SVM_Boolean
This type corresponds to a simple boolean.
Definition: svm.h:353
- For schedulers:
void* scheduler_<scheduler name>_create(const void *svm);
void scheduler_<scheduler name>_delete(const void *svm, const void *handler);
unsigned long int scheduler_<scheduler name>_schedule(
const void *svm,
const void *handler,
const SVM_Process process,
const SVM_Process_State state);
unsigned long int scheduler_<scheduler name>_notification(
const void *svm,
const void *handler,
const SVM_Notification_Type type,
const unsigned long int parameter);
SVM_Boolean scheduler_<scheduler name>_attach(
const void *svm,
const void *handler,
const SVM_Process process,
unsigned long int parameter);
SVM_Boolean scheduler_<scheduler name>_detach(
const void *svm,
const void *handler,
const SVM_Process process,
unsigned long int parameter);
SVM_String scheduler_<scheduler name>_print(
const void *svm,
const void *handler);
SVM_Process_State
This type represents the status of a process.
Definition: svm.h:431
SVM_TYPE typedef const void * SVM_Process
This type is used to represent an execution thread in the SVM.
Definition: svm.h:304
SVM_Notification_Type
This type represents the reason that triggered a callback call to a specific scheduler function.
Definition: svm.h:419
- For functions:
SVM_TYPE typedef const void * SVM_Variable
This type is used to represent any object managed by the SVM.
Definition: svm.h:171
- For structures:
void struct_<struct name>_delete(const void *svm, void *handler);
void* struct_<struct name>_copy(const void *svm, const void *handler);
Please refer to the svm manpage to get details about the call, parameters and expected return values of these callbacks.
To let the plugin callbacks interact with the SVM, some API functions are defined in this file.
- Note
- API functions have some default behavior:
- when an invalid condition is reached in the API function, it will interrupt the full plugin callback and also the calling program. To avoid interruptions, other API functions can be called to detect errors conditions.
- when a parameter is a pointer and is passed NULL, a FAILURE interruption will be raised with a message complaining about a void parameter,
- when a parameter is a pointer that has not been returned by a previous API function call or coming from a callback parameter, a FAILURE interruption will be raised with a message complaining about an invalid parameter,
- when a parameter is a pointer that has been returned by a previous API function call or a callback parameter but has an invalid type, a FAILURE interruption will be raised with a message complaining about a parameter not being of the wanted type,
- when a function returns a SVM_<something> pointer or a SVM_String structure, never free or delete the pointer or the buffer. The SVM will automatically manage the life time of objects created in plugin callbacks. (Explicit void* are not concerned and have to be freed manually.)
- Warning
- Freeing or deleting a pointer returned by an API function will result in an undefined behavior.
- Note
- Any API function requires a pointer as first parameter. This parameter is given as first parameter of the plugin callback.
- Warning
- Passing to an API function a first parameter not being the first one of a plugin callback will result in an undefined behavior. Any modification attempt to this pointer will also result in an undefined behavior.
- Note
- When a function requires a SVM_Kernel or a SVM_Process, by default if the provided SVM_Kernel or SVM_Process is not the current process, the given process has to be locked by the current process to achieve its action. A FAILURE interruption will be raised otherwise. A lock can be obtained by the svm_process_ownership_lock API function.
- See also
- SVM plugin configuration
-
svm_process_ownership_lock