Simple Virtual Machine A simple but flexible virtual machine

Loading...
Searching...
No Matches
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_Size
  SVM_TYPE typedef unsigned long int SVM_Size
  This type is used to represent an object size.
  Definition svm.h:258
  SVM_Parameter
  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:181
  SVM_Value
  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:531
- 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
  unsigned char type_<type name>_compare(const void *svm, const void *handler_left, const void *handler_right); // 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
  SVM_String
  Definition svm.h:335
- 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_Kernel
  SVM_TYPE typedef const void * SVM_Kernel
  This type is used to represent an atomic execution environment.
  Definition svm.h:285
  SVM_Boolean
  SVM_Boolean
  This type corresponds to a simple boolean.
  Definition svm.h:354
- 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
  SVM_Process_State
  This type represents the status of a process.
  Definition svm.h:432
  SVM_Process
  SVM_TYPE typedef const void * SVM_Process
  This type is used to represent an execution thread in the SVM.
  Definition svm.h:305
  SVM_Notification_Type
  SVM_Notification_Type
  This type represents the reason that triggered a callback call to a specific scheduler function.
  Definition svm.h:420
- For functions:
  SVM_Variable function_<function name>(const void *svm, SVM_Size argc, SVM_Parameter argv[]); // mandatory
  SVM_Variable
  SVM_TYPE typedef const void * SVM_Variable
  This type is used to represent any object managed by the SVM.
  Definition svm.h:172
- 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