Skip to content

Encap and TLV

Jump to bottom Edit New page
Simon Duquennoy edited this page Dec 11, 2018 · 13 revisions

The Sparrow Encap protocol and TLV format are the basis for the application layer protocol used for Sparrow devices. The protocol is used to access all the functional objects (called instances) in Sparrow devices (including all Yanzi's IoT devices and the example devices in this repository). Read more about the object model on the Sparrow Object Model page.

Encapsulation Protocol

The Encap Protocol is intended to be used over UDP and encapsulates payload with or without encryption state.

The header format of the Encap protocol is:

 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |Version| Res.  | Payload Type  | Error & Status|FP Mode| IVM   |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         Fingerprint                           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         InitVector                            |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         SequenceNumber                        |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         Payload                               |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

  • Version: This is a version field indicating encapsulation format version. All versions where bit 3 is ’0’ means that the length of the encapsulation header is the same. Current version is 1 (0001b).

  • Reserved: This must be zeros in transmit and must be ignored when received. A receiver may not assume these bits are set to zero.

  • Payload Type: This is a description of the encapsulated data format. - Relevant types are:

    • 0x01 - TLV format
    • 0x08 - Serial Link Data
    • 0x09 - Debug Information
    • 0x0A - Serial data with 32-bit sequence number. The sequence number is located directly before payload after encryption sequence number, if present.

  • Error & Status: The field contain error or status. Currently status can queue control message [?KFF]. Error is reported when the encapsulation protocol was not able parse correctly. The list below shows the defined errors and status. Note that a request can never include error. Error can only be returned as a reply to a request.

    • 0x00 - No Error
    • 0x01 - Version Error
    • 0x02 - Payload Error
    • 0x03 - Fingerprint length error
    • 0x04 - Fingerprint not recognised

  • Finger Print Mode: ...

  • Init Vector Mode: ...

  • Finger Print: ...

  • Payload Unencrypted payload must be n * 4 bytes. Encrypted payload must be n * 16 bytes. Padding must be made with zeros.

TLV Format

TLVs (Type-length-value) are used to read or write variables in the data model. They are sent in lists terminated by the Zero TLV (TLV with length zero). Each of the TLVs are on either the basic TLV format or the vector TLV format - both described below.

[ TLV1, TLV2 ..., TLV-n, Zero TLV]

The basic TLV payload format is shown below:

 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |Version|         Length        |            Variable           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | Instance      |  OP Code      | ElementSize   |     Error     |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                          [ D A T A ]                          |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

If the data is on a vector format the TLV format is slightly different and include some more parameters:

 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |Version|         Length        |            Variable           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | Instance      |  OP Code      | ElementSize   |     Error     |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         Element Offset                        |  
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                         Element Count                         |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                          [ D A T A ]                          |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Here the element offset is the starting element of the vector and the element count is the number of affected elements for this TLV and operation (Read/write).

The different fields in the header are described below:

  • Version - the version of the header. Current version is 0.

  • Length - the length in 32-bit words including the TLV header. For example, a Length of 3 means that the TLV is in total 12 bytes long. A Length of 0 is not a valid length and is reserved for Zero-TLV (termination of TLVs in the packet) and MUST not be used to indicate length.

  • Variable - the variable (16-bit) that is to be read or written using this TLV (in the specified instance). There are 256 variables that are common to all instances (variable number 0-255) - they are the same for all instances so the first instance specific variable is 256 (0x100).

  • Instance - Each Sparrow device can have many different functional objects and this field correspond to an index to an instance of such an object. For example a typical Sparrow device will have instance 0 for management and two instances (1 and 2) for firmware images.

  • Op Code: Determines the type of access, if it is a read or a write for example. The table below shows the most common operations. Bit 0 indicates if it is a request or a response. A ’0’ means request and a ’1’ means response. Bit 7 in the opcode determines if access is a vector access.

    • 0x00 (0x80) Get request
    • 0x01 (0x81) Get response
    • 0x02 (0x82) Set request
    • 0x03 (0x83) Set response
    • 0x06 (0x86) Event request
    • 0x07 (0x87) Event response

  • ElementSize: Specifies the size of each element being written to or read from a device. The value is expressed in number of 32-bit words as 2**Element Size. For example, if a 32-bit data value is to be read, the element size is be set to 0. If a 256-bit data value is to be read, the element size is be set to 3. Note: When implementing a device, all register sizes from 1 to 32 bits must all be represented as a 32-bit register. For example, an indication if a link is up or down is a 1-bit register. The bit will be located in bit 0 of a 32-bit data word.

  • Error: Indicates if the TLV caused an error or not. Errors can occur for different reasons. In case of correct TLV header information but for example unknown variable, a TLV error should be generated and parsing SHOULD continue. This can be done for all errors except length errors. When an error occurrs, the rest of the TLV MUST be unmodified. Only the error field should be added. If an incoming TLV has an error set, the TLV must be discarded.

  • Element Offset: Is the address offset expressed in number of element sizes. The address offset is used in vector accesses to for example a RAM area like a FLASH. The variable number might point to address 0 in the FLASH, but the software wants to read data from byte address 0x100. In this case the offset will be set to 0x40 which is the number of 32-bit words offset to byte address 0x100. Example 2: For an element size of 8 bytes, an offset of 2 points to byte address offset 16

  • Element Count: Is the number of elements handled in the vector access. The number of element is always the same in requests and responses no matter in what direction data elements are actually present. The data being part of the TLV is depending on the OpCode according to list above.

Add a custom footer
Add a custom sidebar
Clone this wiki locally