Structures

Structures are available in MotoHawk, and are definable via use of the MotoHawk Structure Declaration block (Data Storage library), among others. Structures are useful in that they can:

Aid in organizing data
Group relevant data together for viewing/calibration access in instrumentation tools
Be particularly advantageous in situations where portability and scalability of data are useful

What is a Structure?

A structure is a compilation of data that has been organized into fields and instances. That is, a structure would be defined as to the number of data fields, and each individual data field defined as to data type and dimension. An instance of that structure would contain all the fields as defined per the structure. The data type and dimension for each of the fields may differ from one another in a structure, but the respective data type and dimension of a given field would remain the same from instance to instance; the values contained in the respective fields, however, can and will likely vary from one instance to the next.

Structure Example

In the example structure "MYSTRUCT" depicted in the table below, there are 4 defined data fields in the structure (FieldA, etc.), and 5 defined instances of this structure (Instance1, etc.). As shown, the data in the fields can have different data types and dimensions from one to the next, although, for a given field, these properties must be consistent among all instances of that field.

MYSTRUCT	FieldA (uint8)	FieldB (single)	FieldC (uint8 with enum.)	FieldD (int16 vector of length 3)
Instance1	10	3.14159265	State 1	[-5 10 1000]
Instance2	18	1.61803399	State 1	[-500 98 120]
Instance3	250	2.71828183	State 3	[-25000 -5 -2]
Instance4	74	1.41421356	State 2	[32 -81 33334]
Instance5	0	0	Error	[0 0 1]

Declaring a Structure

In MotoHawk, use a MotoHawk Structure Declaration block (Data Storage library) to declare a structure. In declaring a structure, its name is declared, data fields are defined (including data type and dimension), initial values of the field are set, and, if desired, any enumeration definitions are defined. Note that no assumptions are made on the number or name of instances of the structure; instead, these are set by individual data definitions.

For example, to declare the MYSTRUCT structure example shown above, one would use the Structure Declaration block and set the parameters as follows:

Defining Structure Instances

In MotoHawk, define individual structure instances using MotoHawk Data Definition blocks (Data Storage library). To do this, set the block Data Type to struct. When defining a structure instance, specify the corresponding Structure Declaration Name ("MYSTRUCT" in the example) and a container name (see Grouping Instances of Structures below). Additionally, the field values for that particular instance may be given unique initial values.

For example, to define the Instance1 instance with an initial value as in the table above, one would set the parameters as follows:

Grouping Instances of Structures

In MotoHawk, structure instances can be arranged in separate groups; these groups are called containers. Structure containers are defined with a MotoHawk Data Definition block (Data Storage library). To do this, set the block Data Type to struct container. The concept of a container allows groups of structure instances to have different storage types (volatile, nonvolatile, etc.) and/or different access from MotoTune.

For example, to define the MyStructContainer structure container, one would set the parameters as follows:

Note that visibility from instrumentation tools is currently limited to structures whose field data types all have the same number of bytes. Thus, the structure in the example above would not be available for calibration or display access in MotoTune. If, for instance, all the fields did have the same data type, the structure would be accessible via MotoTune. In this case, the initial value parameter of the struct container defines the order that the structures appear in MotoTune. Thus, the struct container parameters may look as follows:

Reading and Writing Examples

Consider this example: For each instance in the MYSTRUCT structure, the FieldA value is going to be read. If the value is greater than 50, the second entry of the FieldD vector will be set to 1; otherwise, it will be set to 0. There are two basic ways of approaching this task; examples of each are shown below:

Reading and Writing to Structures by Name
In the first approach, one would use MotoHawk Data Read and Data Write blocks with Lookup By Name In Structure selected for Data Source. The structure, instance, and field are explicitly specified in the block’s parameters. Note that the same blocks would have to be copied for each of the instances (very tedious if, instead of 5 instances, there were 50).
Reading and Writing to Structures by Reference
An alternative (and more efficient) approach uses references. Note that, unlike entries of a vector or matrix, each structure instance does not have an index explicitly associated with it; instead, structure instances must be pointed to using a reference data type. Using the reference pointer in conjunction with a FOR loop, the necessary task can be applied to each structure instance with fewer MotoHawk blocks.

First, the reference must be created as with a MotoHawk Data Definition block (Data Type set to struct reference). In effect, this will give the reference (pointer) to each structure instance a value. Consequently then, for each iteration in the FOR loop, a reference value will be read using a MotoHawk Data Read block (Data Type set to struct reference). This is the data reference-pointer value that will be used in the subsequent MotoHawk Data Read and Data Write blocks (Data Source set to Lookup By Name in Structure via Reference) to complete the desired task. Note that, no matter how many structure instances are added to or subtracted from the model, the desired operation will be taken for each instance of the structure.