SOIS GSFC Status Report Spring 2015 Pasadena Glenn Rakow Kevin Rice.

SOIS GSFC Status Report

Spring 2015 PasadenaGlenn Rakow

Kevin Rice

SOIS GSFC Status Report

• Worked up 1553 example• Used SciSys EDS Tooling• List of Grievances Found So Far• Started SEDS Tutorial

1553 – Trianna (aka “GoreSat”, DSCOVR)

• Satellite actually launched and renamed DSCOVR after years in limbo:– 11 February 2015

• We have old documentation describing a set of 1553 messages– We scanned, converted to Word, hand extracted into Excell

• We attempted to encode some of them in SOIS EDS• We found:

– It can be done– Map to a set of interfaces with commands

• An observation: – There’s nothing specific that any reader of the documentation would understand to be

1553, unless they already knew it

• Given that there were two “misses” (see Our List of Grievances Slide)

“Typical” Trianna 1553 MSG DocProperties Extracted

Actually two commands:power off AND power on

From CPU to Power Unit

SA = 0x01

Word Length = 1 (16 bits)

Power OFF = 0x**AA

Power ON=All other values

Specifies ranges

Specifies Don’t Cares ,*s

Extracted Properties to EDSProperties Extracted EDS

Actually two commands: power off AND power on

Interfaces have commands

From CPU to Power Unit Commands can have in, out or inout

SA = 0x01 SA values can command argument

Word Length = 1 (16 bits) 16 bit data types are supported

Power OFF = 0x**AA Constants are

Power ON=All other values

Specifies ranges We lost range

Specifies Don’t Cares or *s We can’t say

Not supported:-- ranges-- don’t cares (Of these range may be important, but its not clear don’t care is important)

So we define two commands, related interfaces and data types.-- But no anonymous reader of the doc would know this has anything at all to do with 1553

Prelude to EDS XML ExampleA few observations

• In EDS we are defining software interfaces– Possibly with a certain amount of implementation detail

• We are not describing how information flows over a bus per se:– We might describe a message from a bus or one that goes onto a bus– But we don’t say anything at all about how this occurs

• We don’t say anything about the actual interface from the main CPU’s perspective– Nothing about interrupts– Nothing about how information appears in the CPU’s address space– Nothing about protocol (except there is a state machine construct)… – Etc…

• THEREFORE:– If we are describing software interfaces, we need to think about this in terms of

software APIs and how these are typically layered together, not hardware interface details

Typical API Layering

PowerUnit_On IF

Send_1553_Msg_Word IF

Power Unit1553 HW

? Driver IF

CPU

To Device

Specific

General

We AreHere

Or In A Nutshellpublic void power_unit_on() { send_1553_msg(1, 1, 0x00AA);}

public void send_1553_msg_word(int rt, int sa, int data) { // byte[] msgBuf = new byte[2]; // msgBuf[0]= (0xff00 & data)>>8; // msgBuf[1]=0x00ff & data; // implementation details send_1553_msg(rt, sa, msgBuf, 2); // length redundant}

public void send_1553_msg(int rt, int sa, byte[] msgBuf, int sizeInBytes) { // to low-level device interface, not shown… // package 1553 message up in device specific manner and send it}

Two Paths or Stairway to EDS

Richard Said:Path #1 - You have a general-purpose interface (e.g. to any 1553 device) and you want to record the actual usage of that interface by a specific device. So milbus transfers block of data, a star tracker transfers a ‘power on command’. But those are really the _same interface_, just looked at generically or specifically.

Path #2 - You want to define a device-specific wrapper interface for the above (i.e. a device-specific access interface in SOIS terminology).

At this time we only tried Path #2(because Ramon did it)

Our example in XML Part 1 of 5(Just the interesting bits)

<Namespace name="Datalink1553"> <InterfaceTypeSet> <InterfaceType name="Interface1553"> <CommandSet> <Command name="send1553" mode="async"> <Argument name="RT" type="Integer" mode="in"/> <Argument name="SubRT" type="Integer" mode="in"/> <Argument name="DataWords" type="Buffer" mode="in"/> <Argument name="Length" type="Integer" mode="in"/> </Command> </CommandSet> </InterfaceType> <InterfaceType name="MyDevice"> <CommandSet> <Command name="powerOn" mode="async"> <Argument name="On" type="Boolean" mode="in" defaultValue="true"/> <Argument name="RT1" type="Integer" mode="in" defaultValue="1"/> <Argument name="SubRT2" type="Boolean" mode="in" defaultValue="2"/> </Command> </CommandSet> </InterfaceType> </InterfaceTypeSet>

Our example in XML Part 2 of 5(Just the interesting bits)

<ComponentTypeSet> <ComponentType name="MyDeviceSender"> <ProvidedInterfaceSet> <Interface name="Power" type="MyDevice"/> </ProvidedInterfaceSet> <RequiredInterfaceSet> <Interface name="Power1553" type="Interface1553"/> </RequiredInterfaceSet> <Implementation> <VariableSet> <Variable name="buffer" type="byteArray"/> <Variable name="length" type="Integer"/> </VariableSet> <ActivitySet> <Activity name="powerUp"> <Argument name="RT1" type="Integer"/> <Argument name="SubRT2" type="Integer"/> <Argument name="Onness" type="Boolean"/> <Implementation>

Our example in XML Part 3 of 5(Just the interesting bits)

<Assignment outputVariableRef="buffer[0]"> <VariableRef variableRef="Onness"/> </Assignment> <Assignment outputVariableRef="length"> <Value value="1"/> </Assignment> <Command command="Interface1553/send1553" transaction="X0"> <ArgumentValue name="RT"> <VariableRef variableRef="RT1"/> </ArgumentValue> <ArgumentValue name="SubRT"> <VariableRef variableRef="SubRT2"/> </ArgumentValue> <ArgumentValue name="DataWords"> <VariableRef variableRef="buffer"/> </ArgumentValue> <ArgumentValue name="Length"> <VariableRef variableRef="length"/> </ArgumentValue> </Command> </Implementation>

Our example in XML Part 4 of 5(Just the interesting bits)

</Activity> </ActivitySet> <StateMachineSet> <StateMachine name="passThrough" defaultEntryState="idle"> <EntryState name="idle"/> <State name="busy"/> <Transition fromState="idle" toState="busy" name="getBusy"> <OnEvent xsi:type="CommandPrimitiveSinkType" command="MyDevice/powerOn"/> <Do activity="powerUp"> <ArgumentValue name="RT1"> <VariableRef variableRef="MyDevice/powerOn/RT1"/> </ArgumentValue> <ArgumentValue name="SubRT2"> <VariableRef variableRef="MyDevice/powerOn/SubRT2"/> </ArgumentValue> <ArgumentValue name="Onness"> <VariableRef variableRef="MyDevice/powerOn/On"/> </ArgumentValue> </Do> </Transition> <Transition fromState="busy" toState="idle" name="whew">

Our example in XML Part 5 of 5(Just the interesting bits)

<OnEvent xsi:type="CommandPrimitiveSinkType" command="Interface1553/send1553" transaction="X0"/> </Transition> </StateMachine> </StateMachineSet> </Implementation> </ComponentType> </ComponentTypeSet> </Namespace></DataSheet>

GPS Example to C• Sam Prices GPS Device

– Not really a CFs app … but still useful

• Used recent version of SciSys Tool chain• GPS Example includes telemetry and command packet descriptions• GSFC reads GPS header files and builds an EDS from them

– The tool is based on the CDT plugin for Eclipse (c/c++)– It uses CDT “introspection” to get at the parsed syntax, and convert it (note: this was hard)– It uses Sam Price’s DOXYGEN based “annotation” to identify packets specifically, otherwise it just

converts data types to SEDS DataTypes, etc…

• Things to note:– Sam elected to use C unions and bitfields in a few places which is atypical of GSFC– The GPS software actually runs inside it’s own CPU, the GPS device itself and is not really a MAIN

COMPUTER application…. – Sam’s CCSDS header structs are also not 48-bits but slight abstract representations of it for reasons

that elude me – and again this is atypical of how GSFC really does things)• This is a KEY problem for GSFC how to do bitfields basically in SEDS• We have discussed before at length….

• Given the GPS.XML SEDS file:– Used the tool to generate C– Overall the C looked pretty good

Tool Output Part 1

Mostly boilerplate Recreated

Headers

Part of a recreated

enum

Tool Output Part 2Lot’s of things look good:

Generated

/**@brief PPS_STATE: Enum for PPS states*/typedef enum{ PPS_STATE_PPS_COARSE = 0, PPS_STATE_PPS_FINE = 1} PpsState_T;

Original

/*! @ingroup MESSAGES * @brief Enum for PPS states */enum PPS_STATE{ PPS_COARSE =0, PPS_FINE =1

};

Tool Output Part 3But it didn’t pick up the UNION:

Generated

/**@brief Message_Union: Union containing all the individual messages.*/typedef struct{ BoardHealthM_T board_health; TaskHealthM_T task_health; SpsM_T sps; TotM_T tot; PpsM_T pps;

Original/* @brief Union containing all the individual messages. * All of the messages need to be contained inside of this structure to ensure buffer overflows don't happen. */typedef union Message_Union{ Board_Health_M board_health; Task_Health_M task_health; SPS_M sps; TOT_M tot; PPS_M pps;

WHY?

Tool Output Part 4Because we have about 3 way to do union in SEDS and the tool didn’t see it:

One of at least 3 ways to possible say “union” in SEDS

<seds:ContainerDataType name="Message_Union" shortDescription="Union containing all the individual messages."><seds:EntryList> <seds:Entry type="Board_Health_M" name="board_health"> <seds:LocationInContainerInBits offset="0" referenceLocation="containerStart"/> </seds:Entry> <seds:Entry type="Task_Health_M" name="task_health"> <seds:LocationInContainerInBits offset="0" referenceLocation="containerStart"/> </seds:Entry><!-- ... -->

GPS Example: Observations

• More tunability would be nice– As such SciSys added a template feature and delivered a new tool to

us in February• We have not used this yet but plan to do so soon to see if this will allow to

map out typically CCSDS header as we want…

– Yet even more might be nice• Key thing for GSFC:

– A more typical CCSDS header to 3 16-bit unsigned ints• Possibly w/macros to get at the sub-fields• We’d like to generate that….

– A bitfield keyword might be nice– A union keyword might be cleaner

• Although

GPS Example Final

• It’s a great start! Kudos SciSys!• And yet we want your source code!• Is there a way to get this posted as “open

source”? – Or is this proprietary, etc…?

Conclusion: Our List of Grievances1. Dropped name and other similar attributes (version) from root element2. Range is not a set, we agreed to this in the Spring3. We missed a global schema type in one place (Container ConstrainstSet)4. We cannot say that an encoding is little or big endian BIT order5. We think bit-fields could still be useful and wish to revisit this again for the

umpteenth time6. There’s nothing specific about common HW links in schema syntax: 1553, etc…

(except a tiny bit about spacewire)1. We speculate this might be important but also speculate it could be in another related

schema

7. Next slide (yes there’s more – sorry)

Conclusion: Our List of Grievances7. We have a slight “model mismatch” in the way we treat incoming or outgoing

packets with ESA1. Generally GSFC wants their C-structs to overlay the byte array and uses other means

(say macros) to get at the underlying sub-fields. This is true completely throughout the main computer FSW…

2. ESA on the other hand assumes a transformation from a byte array to an abstract data type at outer most input/output interfaces to main computer

3. The schema syntax favors #2 (& this is true in XTCE also)

8. Inheritance rules need to be absolutely nailed down and documented1. @baseType, etc…

9. Align spline cals with XTCE 1.2’s spline10. NameType REGEX is missing “_”s …11. In the schema replace xs:integer and similar with xs:int, etc… this makes

JAXB mapping slightly better because you lose BigInteger, etc…

SOIS EDS Tutorial – A Start

Work In Progress…

What is SOIS EDS

• SOIS EDS – sometimes called SEDS• SOIS Electronic Data Sheet• An XML Schema

– Actually two: It includes the Dictionary of Terms, another Schema• Describes various aspects of device metadata so that software

can communicate with it on a main cpu• Could be used for code generation:

– “Meta-Software”• Could be used for document generation• Somewhat agnostic to SOIS FSW Architecture

– But not completely…

DataSheet

• An optional Device element• Zero or more Namespace elements• The minimal valid EDS is:

– This is not terribly useful

<seds:DataSheet xsi:schemaLocation="http://www.ccsds.org/schema/sois/seds seds.xsd" xmlns:seds="http://www.ccsds.org/schema/sois/seds" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

Constructing Datasheets

• Data sheets may be composed from one or more other data sheets– Xinclude friendly

• Common namespaces may be included in your datasheet

<Device> <DAS type="NPAL/NPAL_DAS" name="NPAL_DAS"/> <Subnetwork>…</Subnetwork> </Device> <xi:include href="seds.xml" xpointer="element(/1/1)"/> <xi:include href="ccsds.sois.subnetwork.xml" xpointer="element(/1/1)"/> <Namespace name="NPAL">

Device

• Root element in a Datasheet• A device describes (all optional)– A DAS– A DVS– A sub network– Metadata

Device’s DVS and DAS

• “The DVS and DAS elements are component instances.” – Red Book

Namespaces

• Define one or more name spaces– A list in XML file– Names

• Simple – “NPAL”• Hierarchical – “ESA/NPAL”

• Referencing named items:– Using the simple name means the item is in the

current (local) namespace only– Use the hierarchical name as an absolute reference

to any name space defined

Namespace Example

Power/Battery

NPAL

CCSDS/Commons

Comm/XBand

Ref=“BatV1”

Ref=“CCSDS/TelemetryPacket”

EDS Data Type & Source

Data Encoding Data Type

Non-local source of Message

Local Address SpaceContiguous*

Bits Are Stored

Message Appears

Describes Maps to

Variables Arguments

Instances of

Component

Command

Has

Has

*Bits are in a block:-- Subfields bits are together-- Fields/Subfields may skip addresses-- (Disparate Bit extraction not supported)

Data Types

• Scalar Types: – String– Enumeration– Boolean– Float – Integer– Binary (type-less type)

• Complex Types:– Array– Container (aggregate)

Scalar Data Type with Encoding• The scalar data types have an optional data encoding element• The encoding describes a remote type format

– IntegerDataEncoding– FloatDataEncoding– BinaryDataEncoding– StringDataEncoding

• Encodings are paired with the data type– IntegerDataType has an IntegerDataEncoding– FloatDataType has a FloatDataEncoding– StringDataType has a StringDataEncoding– BinaryDataType has a BinaryDataEncoding

• The data encoding or remote type format describe how to encode or decode a particular value to the local data type represented by one of the scalar data type

Scalar Data Type with Encoding Examples

<seds:IntegerDataType name="UnsignedIntType"> <seds:IntegerDataEncoding byteOrder="bigEndian" encoding="unsigned" sizeInBits="16"/> <seds:Range> <seds:NumberOfBitsRange numberOfBits="16" signed="false"/> </seds:Range></seds:IntegerDataType>

An integer data type called “UnsignedIntType” from an unsigned 16-bit integer

<seds:FloatDataType name="FloatType"> <seds:FloatDataEncoding byteOrder="bigEndian" encodingAndPrecision="IEEE754_2008_single"/> <seds:Range> <seds:PrecisionRange>single</seds:PrecisionRange> </seds:Range></seds:FloatDataType>

An integer data type called “UnsignedIntType” from an unsigned 16-bit integer

Scalar Data Type without Encoding

• The scalar data types without optional data encoding element– Are simply local or native data types

Scalar Data Type’s Range

• The range tells the local implementation the valid range for data encodings

• And hints at the local implementation data type– Ex 1. A data encoding value might be 16-bits, but

only the lower 8-bits are valid. – Ex 2. An integer data type has a bit range of 32

bits and is unsigned. For many compilers this is a “uint”.

Scalar Data Type’s Semantic

• Semantics describes items in Dictionary of Terms– The DoT is an included schema generated from an ontology– A default DoT is provided with the standard

• Semantics Attributes:– quantityKind, unit, chirality, coordinateType, toCoordinateType,

differenceType, differenceConvention, intepretation, purpose, referenceFrame, toFrame, relationToTimestamp, statusConvention, transformationType, tecOperatingMode, healthStatus, startTrackerOperatingMode, memberOf, subject, enumeration, prefix

• Semantic Element– Terms - referring to an item by URI defined in the ontology

Complex Data Types

• ArrayDataType– Define dimensions– Point to the “cells” data type

• Often a scalar• But could be another complex data type

• ContainerDataType– An aggregate data type (e.g. “Struct”)– Define fields which point to another data type

• Often a scalar • But could another complex data type

Data Type Inheritance

• All of the data types may sub-type another– @baseType

• General rules:– Circular inheritance chains are illegal– A data type can only extend a like type– A data type only sub-types by narrowing the parent type

• Special Cases:– ContainerDataType may also define constraints

• Conditions associated with the sub-type operation• Typically used to define things like APID in a packet data type

– ArrayDataType • I dunno how this works … Richard?

Components

• “A component is a reusable element of the description of the operation of a device. “ – Red Book

• Alternatively if you are generating code from an EDS component description:– A piece of code, a function, procedure, method,

class or collection of them

Inside Component

• Components have:– Provided Interfaces (required)– Required Interfaces (required)– Local DataTypes (note: how do you ref these?)– Local Interfaces (note: how do you ref these?)– Implementation

• Variables• ParameterMap• ParameterMapActivities• Activities• StateMachines

Inside Implementation

• Variables– an instance of type, with optional initial value an other properties

• ParameterMap– maps an instance of a parameter (from outside the component) to

a variable (inside the component)• ParameterMapActivities

– Maps parameter to an activity• Activities

– Parameter, Command, Calibration, MathOperation, Assignment, Conditional, Iteration

• StateMachines– Entry, Exit, State, Transition

Inside Implementation’s Activities

• TBD

Inside Implementation’s StateMachine

• TBD

Interfaces

• “The functions of a component are exposed through one or more interfaces provided by the component. “ -- Red Book

• Alternatively if you are generating code from an EDS component description:– The signature to the entry point(s) of a

component

Inside Interface

• Interfaces have:– BaseTypes: one or more data types that includes

all children of them in the interface– GenericTypes: types that specify a “generic” root,

concrete children are included in the interface– Parameters: instances of data types at the

interface, additional properties may be set: read only, etc…

– Command: includes arguments and properties: in, out, inout

CCSDS Header ExampleMsb Lsb

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

Version Type SecHdr

APID

Seq Flags Sequence Count/Name

Length

<ContainerDataType name=“CCSDSHeader”> <EntryList> <Entry name=“Version” type=“VersionType”/> … </EntryList></ContainerDataType><IntegerDataType name=“VersionType”> <IntegerDataEncoding encoding=“unsigned” sizeInBits=“3”/></IntegerDataType>

CCSDS Header ExampleMsb Tlm=0

Cmd=1 Lsb

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

Version Type SecHdr

APID

Seq Flags Sequence Count/Name

Length

<ContainerDataType name=“CCSDSHeader”> <EntryList> … <Entry name=“Type” type=“TypeType”/> … </EntryList></ContainerDataType><IntegerDataType name=“TypeType”> <IntegerDataEncoding encoding=“unsigned” sizeInBits=“1”/></IntegerDataType>

Could be an enum

What ESA Wants To DescribeMain Computer

Devices

Subnetwork

Provides common byte array “iterator” interface

Device AShim

Device BShim

Device … Shim

Device ZShim

Low-level “stub” drivers:- interrupts, protocols, ports, memory map, scatter /gather

EDS Describable Area:- Byte order- Calibrators- Commands/args- Interfaces/Components- Layering- State machine- Overall control flow- Data Types- MessagesLayer 1

Layer 2

Layer N

What GSFC Wants To DescribeMain Computer

Devices

Software BusProvides common CCSDS Message” “iterator” service

Device ABottom Half

Device BBottom Half

Device … Bottom-Half

Device Z Bottom-half

EDS Describable Areas:- Byte order- BIT ORDER- Calibrators- Commands/args- Interfaces/Components- Layering- State machine- Overall control flow- Data Types- Messages- Top-half Driver -- possibly mftr. supplied -- Bit/Byte Order -- Data Type/Message- Bottom-half Driver-- possibly locally supplied -- protocols -- ports -- memory map -- scatter /gather -- Interrupts

Layer 1..N

Layer CFS Interface

Device ATop-Half

Device BTop Half

Device … Top-Half

Device Z Top-half