RHD:Variable database

Revision as of 09:59, 28 January 2009

The variable database defines the functionality of RHD. Upon initialization, all plug-in modules create their needed I/O variables, and finally the database is locked when going into soft/hard realtime.

Structure

The database itself, are based upon a symbol table and a data area. The symbol table defines the static information regarding the variables and bookkeeping information. The data area, contains the dynamic information, the actual data and it’s timestamp. The needed memory is dynamically allocated, when variables are created. Figure 1 below, show the internal structure of the variable database and the association between symbol table and data area.

Image to come...

Figure 1: Structural overview of an element in the variable database

Note, that a standard variable size of a 32-bit signed integer is selected. This decision is made, to keep variables ”large enough” for most future applications, and the fact that memory and bandwidth is not a dramatic issue on most modern platforms.

Some discussion has concerned to include a type to the variable database, as it might seem inefficient to represent text strings in 32-bit integers. A future enhancement of RHD might supply the possibility of using other integer sizes, but so far the design decision is to keep it simple with the highest flexibility.

Bidirectionality is obtained by using two separate symbol tables: a read and a write table. Data read from sensors are fed into the read-table, and data from the client is received in the write table.

Each variable is supplied with a ”updated” flag (see fig 1). The flag is used to implement reactions to updated variables, and to determine what data should be exchanged with the client.

There might always be a need to know the exact time a variable was updated, so all variables has a timestamp, that is set, every time a variable is updated. This makes it possible to control timing with a much higher resolution than the fundamental RHD scheduler period.

API

The API is defined in database.h. This API overview is not intended as a programming reference, but just to give a feel of, how the database is interfaced. Variable creation is done by the plug-ins using the function below: int createVariable (char dir, char len, char ∗name) Add a variable array to the variable pool The direction, dir, is either the ’r’ og ’w’ character, that determines in which symbol table the variable is created. len assigns the number of elements in the variable array, and the name parameter is a pointer to a text string, containing the desired name of the variable. CreateVariable returns the id number of the variable, that is used to address the data, when performing I/O. When initialization is completed, the database is locked in soft-realtime-mode, and no further variables can be created.

Interfacing the variables are done through the following functions: int setVariable (int id , int index, int value) Update a array in the data pool

int setArray (int id , int length, int ∗array) Update a array in the data pool

int setVariable (int id , int index, int value) Get a read variable from the data pool

int getWriteArray (int id, int index, int ∗array) Get a read variable from the data pool

int getReadVariable (int id, int index) Get a read variable from the data pool

int getReadArray (int id, int index, int ∗array) Get a read array from the data pool

int isUpdated (char dir, int id) Check if a variable is updated

Using this simple API, data can be transferred into the read database and out from the read and write database. The id parameter is the variable id, that is returned when the variable is created, and index is the array-index in the database. Check if variables are updated is performed through the isUpdated() function.

Other functions, that can be found in the RHD documentation, give the possibility of interfacing the symboltables directly, but their use is highly discouraged. The API above provide semaphore and boundary projection, and result in more safe and readable code.