Definitions of Symbol Table Variable Types

Global Variable
Messages
Array Message
Partial Structure Message
Arm Message

The symbol table is a group of variables which may be common across different processes. These variables may consist of basic or complex data structures which perform one or both of the following roles:

1) Global variable = Similar to a global variable within a program which can be accessed by different functions, these goal of these variables are to be shared across several processes and computers. In the case of Ranger TSX, the control station on the GCS should have the same values as within its shared variables as the on-board computer in orbit.

2) Message variable = These variables are used to communicate between processes to synchronized the shared variables. In many cases the shared variable itself is directly communicated. However, there are certain circumstances which it may be desirable for these two roles to be separated.

Global Variable

These varialbes are the structures used in the program. In many cases this variable is also the message that is sent. This is the default case.

For example the following variable could be accessed as a global variable and a message variable.

short mainPowerOnFlag;

This variable could represent the status on one process. The message would look the same to transmit that status to another process. However, not all global variables are message variables. A large global structure may house many different peices of information which is shared through a series of meesage variables.

Messages

There may be times when a global variable will be communicated in separate parts. A shared only variable would exist holding all the important information. Then one of the two message variables below would transmit a portion of the structure. The structure below is given to show how the different types of variables could work.

Given a variable armInfo[ARM_ID] of data type armStruct_t. The data structure could be defined as below:

struct armStruct_t{
  short powerOn;
  struct statusFlags_t {
    short commFlag;
    short jointFlag[ARM_DOF];
    short localProcessorsFlag[4];
    } statusFlags;
  float armTemp;
} armInfo[ARM_ID];

1) armInfo could be a global variable. Not only does the local process directly use armInfo, but when a message is sent or received the entire structure is communicated and updated.

2) armInfo could also be transmitted in parts. This would first require armInfo to be a shared only variable. The local process would access this variable normally. However this entire structure would not be transmitted. Specially derived message only variables would be created to send and receive. They would take one of two forms: Arm Shared with resulting message variables or a Partial Structure Message.

Array Message

One element of an array can be sent. In the above example an array message variable can be designateding by adding the array as part of the symbol name.

armInfo[MAX_ARM];

The symbol table code would recognize that a new array message was required. These message variables allow for only the information of only one arm to be transmitted. This is helpful for limiting the number of messages that an arm module must handle. A module controlling only the left arm will ignore the messages for all but the left arm. The message structure would use the original data structure but with an added element designating the arm.

The differences are as follows:

a) The name of the message is derived as

armInfo_array

The '_array' was appended and this variable is not an array.

b) An extra element was added to the top of the message,

short armInfo_ID

This element is used to identify which array element is being referenced by the rest of the message.

No new variables are made. Only a new message is generated transmitting the array index, armInfoId, and the appropriate array element, armInfo[armInfoId].

Partial Structure Message

It may be desired to only transmit part of the original structure. For the example above perhaps only the statusFlags element needs to be transferred. A partial structure symbol could be defined as

armInfo[MAX_ARM].statusFlags of data type statusFlags_t

The symbol table code would test to make sure such and variable and element already was defined, then it would create a new message. A derived message named appends _elem, the resulting message name would be statusFlags_elem .

Since the original structure had an array, armInfo[MAX_ARM], an extra element was added to identify which element within that array is being accessed. The new element is named after the original symbol name 'armInfo' with an '_ID' appended.

Multiple array within a structure

An extra element is added for every array within the parent structure. For instance if a partial symbol was defined as:

testStruct[ARRAY1].substructure[ARRAY2].element of data type float.

The resulting message structure would look like sending the following three peices of information:

 short testStruct_ID;
 short substructure_ID;
 float element;

No arrays within a structure

If no array is listed in the parent structure, then the message only sends the original element. For example if the partial symbol was defined as the following:

testStruct.substructure.element of data type long.

The resulting message would simply be the data type with a new variable with '_elem' appended to it.

long element_elem

Repetitons on the message name

If two symbols would have the same resulting message name, the repetitious names will have a unique number incremented in its name. Therefore, for the following symbol definitions:

firstStruct[3].element
secondStruct[2].element
thirdStruct[5].element

The resulting generated message names would eleminate the repetition

element_elem
element_elem1
element_elem2

Error checking on partial messages

As mentioned before error checking is made to help the programmer catch inconsistencies. For the given example of the shared variable only armInfo[MAX_ARM] the following illustrates what kinds of errors are checked.

short armInfo.armTemp

ERROR: symbol armInfo.armTemp, element armInfo has no array size, which disagrees with the symbol table definition of armInfo with array size [MAX_ARM]

short armInfo[4].armTemp

WARNING: symbol armInfo[4].armTemp, element armInfo has an array size of [4] which disagrees with the symbol table definition of armInfo with array size [MAX_ARM]

short armInfo[MAX_ARM.armTemp

ERROR: symbol armInfo[MAX_ARM.armTemp, element armInfo did not provide a matching ']' for its array size

short armInfo[MAX_ARM]a.rmTemp

ERROR: symbol armInfo[MAX_ARM]a.rmTemp, element armInfo encountered a 'a' instead of the expected '.' after the array size was defined

float armInfo[MAX_ARM].armTemp

ERROR: symbol armInfo[MAX_ARM].armTemp, element armTemp has a defined data type of float which does not agree with the data types table definition of armTemp with data type short

short armInfo[MAX_ARM].armtemp

ERROR: symbol armInfo[MAX_ARM].armTemp, element armtemp could not be found in structure armStruct_t

Depth of data type structures

Although no top limit on the levels of embedded structures has been enforced, only 5 different indexes are considered. A guideline of keeping strucuture 5 deep, or less, has been considered for the design of this system. Therefore

structName.element.secondElement.thirdElement.fourthElement

would be valid. The use of arrays is also allowed with any of the elements so that

structName[5].element[10].secondElement[MACRO].thirdElement[20].fourthElement[2]

would also be allowed. However, matrices are not supported at this time. Therefore

structName[10][3].element

is NOT valid.

Arm Message

This is a special kind of Partial Structure Message or Array Message. The programming scripts check the subSystem or the rclMessage field to see if it begins with "CArm". If so changes to the default code generation is made. It is assumed that all arm messages have an array size for each arm. Valid variales include

desiredJoint_raw[MAX_ARM]
armPower[4]

The declared variable must be an array of proper size, in the case above MAX_ARM is a macro for 4.

Messages must be defined with the array as well.

armPower[4]
desiredJoint_raw[MAX_ARM].gains[DOF].p

are both valid if the first array designates which arm.