The block definition file defines the bit level structure of all your data products like telemetry data. A block definition is similar to a structure declaration in the 'C' programming language. A block definition consists of a unique block name and a listing of all the data items that comprise this block.
This section will give a detailed description of data block definitions and the format of data block definition files (*.blk).
If you don't specify any block definition files to load in the gseos.ini configuration file a default file will be loaded. The file has to be located in the GSEOS working dircetory (e.g. in the same directory as the GSEOS.EXE file). The name of the block definition file consists of the poject name specified in the gseos.ini file and the extension '.blk'. You can override this by specifying your block definition files in the config section of the gseos.ini file. In general you want to include the system block definitions that can be found in system\system.blk.
Comments can be inserted anywhere in the file. A comment starts with the '#' character (the old notation is the '*' character) and ends at the end of the line.
A block definition starts with a unique block name. The maximum length of the block name is 32 characters. After the block name an optional block type modifier can follow. The two types allowed are MOT (the default) for Motorola (big) endianity or INTEL for Intel (little) endian. Motorola endianity means that the most significant bit resides on the highest address while the Intel endianity is defined with the least significant bit on the highest address. All items defined in this block are handled with the block default that is specified here. You can override individual items if the endianity changes on item boundaries. The maximum size of a block must not exceed 500kB.
Item definition
The item definitions are enclosed in curley brackets '{' '}'. One block may contain any number of item definitions.
Push address
The optional push address operator '(' pushes the address of the item onto a stack. It can be retrieved through the pop operator ')'. This can be used to access a single address with multiple items, i. e. have multiple names for the same address space. The push and pop operators can be nested to any level.
Item name
An item definition starts with a block unique item name. The maximum length of the item name is 32 characters. The item name can be omitted. If no item name is specified this item can not be accessed but it inserts a gap of its according size in the block definition. This way you can gap areas of no interest without using an absolute addressing mode.
Array specifier
An optional array specifier indicates an array. The dimension of the array, declared in square brackets, is determined by the dimension field. Array elements do not have to be contiguous but may be subdivided by a bit gap of a constant length. The bit gap length must be less then 65500 bits. If a data item is defined as an array and no bit gap is defined, the array elements are contiguous (packed). If the array specifier is omitted the item is assumed to be a scalar.
Start byte
The offset of the beginning of the block for this data item. The first byte in a block has offset 0. If the start byte is omitted the current byte position, contiguous to the previous defined item, is used as start byte position. Using start bytes defines an absolute addressing scheme which gives you less flexibility in changing your block definitions. Defining a start byte allows you to insert an item into the middle of a block definition without changing all the start addresses of the items defined after the inserted one. However, if you specify the start byte the current position is set to this address. It is not necessary to order the item definitions in the order of the start byte. You can use this feature to overlap multiple items. I.e. you can specify the same start byte for multiple items.
Start bit
The first bit covered by the data item. For type INTEL the first bit in a byte is defined to bit 7, the most significant bit. The last bit in a byte is bit 0, the least significant bit. For type MOT the first bit is bit 0, and the last bit is bit 7. If the start bit is omitted the item is packed behind the previous item.
Bit length
The length of the data item in bits. This can be a number from 1 to 32. If the data item was defined as an array, this is the length of one single array element. The bit length must be specified!
Item type modifier
By default the item type is the block type (MOT or INTEL). This default can be overriden for an item by MOT or INTEL.
Pop startaddress
The optional pop address operator ')' pops an address from the stack. This address has to be pushed onto the stack with the push operator '(' before. It restores the start byte address of the matching pop operation.
Comments
To be more flexible you should omit the start byte and start bit specifiers. The disadvantage of this approach is that you cannot directly tell at what absolute address an item is positioned. GSEOS allows you to print out a detailed map of your block definitions which contains the absolute byte and bit positions of every data item. You have to create a file of type 'Block Listing' from the File|New menu.
Example
The following block definition shows a simple block with all items on byte boundaries. This block is a GSEOS system block:
# -----------------------------------------------------------------------
# Status block for dynamic storage allocation
# -----------------------------------------------------------------------
DSACtrl INTEL
{
dwTotal ,,, 32;
dwTotalFree ,,, 32;
wFreeCnt ,,, 16;
wIterations ,,, 16;
dwAllocCalls ,,, 32;
dwFreeCalls ,,, 32;
dwFailCnt ,,, 32;
}
The block listing of the above block shows the absolute offsets of all data items and the endianity of each individual item.
Item Name Offset Size Gap Endian
[Byte/Bit] [Bit] [Bit]
---------------------------------------------------------
dwTotal 0/0 32 - Intel
dwTotalFree 4/0 32 - Intel
wFreeCnt 8/0 16 - Intel
wIterations 10/0 16 - Intel
dwAllocCalls 12/0 32 - Intel
dwFreeCalls 16/0 32 - Intel
dwFailCnt 20/0 32 - Intel
The next example demonstrates the push address and pop address operators. The start address of the item Block is pushed. In this case the start address is 0 (since Block is the first item in the SimTmMode block definition). Before defining the item State the address is popped. This means that the offset of State is 0 and therefore overlaps Block[0]. If we had not used the push and pop operators the byte offset (start byte) of State would have been 128. You can verify the positioning of the items in the block listing below.
# -----------------------------------------------------------------------
# telemetry mode change control
# -----------------------------------------------------------------------
SimTmMode {(Block [128] 0 ,,, 8;)
State ,,, 8;
}
=========================================================
Block Name: SimTmMode
Size: 128 Byte
Number of items: 2
Item Name Offset Size Gap Endian
[Byte/Bit] [Bit] [Bit]
---------------------------------------------------------
Block[128] 0/0 8 0 Motorola
State 0/0 8 - Motorola
The next example shows a block definition with items which are not aligned on byte boundaries. It also uses absolute addressing by specifying the start position of every item.
# -----------------------------------------------------------------------
# S/C telemetry inter-experiment data packet
# -----------------------------------------------------------------------
SimIePkt {
Ident , 0, 7, 16;
Segmentation , 2, 7, 2;
Tag , 2, 5, 14;
Length , 4, 7, 16;
OBT [6] 0, 6, 7, 8;
Data [2] 0, 12, 7, 16;
Validity [2] 15, 12, 7, 1;
Master , 12, 6, 4;
Event , 14, 6, 4;
Type [2] 15, 12, 2, 1;
x , 12, 1, 10;
y , 14, 1, 10;
}
Oftentimes it is necessary to define arrays of structures as opposed to single items. E.g. assume we have an Event block that defines 10 events with each event consisting of two items: Time-of-Flight (ToF) and Mass. Lets further assume that ToF and Mass have a resolution of 14-bit and are packed like this:
In this scenario we can define two array times which overlap in the address space. Here is the block definition:
Event
{
ToF [10] 28, , , 14;
Mass [10] 28, 1, 1, 14;
}
The first element of ToF starts at byte offset 0 bit offset 7 (remember big endian is MSB on high address). You don't have to specify any of this. But we have to indicate a spacing of 28 bits between the individual elements. 14 bit for the ToF item and a gap of 14 bit where the Mass item will reside.
The Mass item as the same layout as ToF with the exception that it is shifted by 14 bit. We specify the start position as byte 1, bit 1. This is 8 bit for the first byte plus 7-1 = 6 bit in the second bit. Resulting in 14 bit offset from the start of the ToF item.