View source for RHD:Variable database

The variable database deﬁnes the functionality of RHD. Upon initialization, all plug-in
modules create their needed I/O variables, and ﬁnally 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
deﬁnes 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 ﬂexibility.

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” ﬂag (see ﬁg 1). The ﬂag 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 deﬁned 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:

<code><pre>
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
</pre></code>

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.