Simple Virtual Machine
A simple but flexible virtual machine
Simple Virtual Machine API

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_Value instruction_<instruction name>(const void *svm, SVM_Size argc, SVM_Parameter argv[]); // mandatory
    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); // mandatory
    void* type_<type name>_copy(const void *svm, const void *handler); // optional
    void* type_<type name>_constant(const void *svm, const SVM_String value); // optional
    SVM_String type_<type name>_print(const void *svm, const void *handler); // optional
    Definition: svm.h:334
  • For interruptions: No plugin callback to be defined.
  • For sequencers:
    void* sequencer_<sequencer name>_create(const void *svm); // mandatory
    void sequencer_<sequencer name>_delete(const void *svm, const void *handler); // mandatory
    SVM_Kernel sequencer_<sequencer name>_current(const void *svm, const void *handler); // mandatory
    SVM_Boolean sequencer_<sequencer name>_attach(const void *svm, const void *handler, SVM_Kernel kernel, SVM_Size argc, SVM_Parameter argv[]); // mandatory
    SVM_Boolean sequencer_<sequencer name>_detach(const void *svm, const void *handler, SVM_Kernel kernel, SVM_Size argc, SVM_Parameter argv[]); // mandatory
    SVM_String sequencer_<sequencer name>_print(const void *svm, const void *handler); // mandatory
    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); // mandatory
    void scheduler_<scheduler name>_delete(const void *svm, const void *handler); // mandatory
    unsigned long int scheduler_<scheduler name>_schedule(const void *svm, const void *handler, const SVM_Process process, const SVM_Process_State state); // mandatory
    unsigned long int scheduler_<scheduler name>_notification(const void *svm, const void *handler, const SVM_Notification_Type type, const unsigned long int parameter); // optional
    SVM_Boolean scheduler_<scheduler name>_attach(const void *svm, const void *handler, const SVM_Process process, unsigned long int parameter); // mandatory
    SVM_Boolean scheduler_<scheduler name>_detach(const void *svm, const void *handler, const SVM_Process process, unsigned long int parameter); // mandatory
    SVM_String scheduler_<scheduler name>_print(const void *svm, const void *handler); // mandatory
    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_Variable function_<function name>(const void *svm, SVM_Size argc, SVM_Parameter argv[]); // mandatory
    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); // mandatory
    void* struct_<struct name>_copy(const void *svm, const void *handler); // optional

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