Tock processes are represented using the Tock Binary Format (TBF). A TBF includes a header portion, which encodes meta-data about the process, followed by a binary blob which is executed directly. All fields in the header are little-endian.
The TBF header contains a base header, followed by a sequence of type-length-value encoded elements. All fields in both the base header and TLV elements are little-endian. The base header is 16 bytes, and has 5 fields:
0 2 4 6 8
+-------------+-------------+---------------------------+
| Version | Header Size | Total Size |
+-------------+-------------+---------------------------+
| Flags | Checksum |
+---------------------------+---------------------------+
Version
a 16-bit unsigned integer specifying the TBF header version. Always2
.Header Size
a 16-bit unsigned integer specifying the length of the entire TBF header in bytes (including the base header and all TLV elements).Total Size
a 32-bit unsigned integer specifying the total size of the TBF in bytes (including the header).Flags
specifies properties of the process.- Bit 0 marks the process enabled. A
1
indicates the process is enabled. Disabled processes will not be launched at startup. - Bit 1 marks the process as sticky. A
1
indicates the process is sticky. Sticky processes require additional confirmation to be erased. For example,tockloader
requires the--force
flag erase them. This is useful for services running as processes that should always be available. - Bits 2-31 are reserved and should be set to 0.
- Bit 0 marks the process enabled. A
Checksum
the result of XORing each 4-byte word in the header, excluding the word containing the checksum field itself.
The header is followed immediately by a sequence of TLV elements. TLV elements are aligned to 4 bytes. If a TLV element size is not 4-byte aligned it will be padded with up to 3 bytes. Each element begins with a 16-bit type and 16-bit length followed by the element data:
0 2 4
+-------------+-------------+-----...---+
| Type | Length | Data |
+-------------+-------------+-----...---+
Type
is a 16-bit unsigned integer specifying the element type.Length
is a 16-bit unsigned integer specifying the size of the data field in bytes.Data
is the element specific data. The format for thedata
field is determined by itstype
.
TBF may contain arbitrary element types. A standard set of element types are standardized.
The Main
element has three 32-bit fields:
0 2 4 6 8
+-------------+-------------+---------------------------+
| Type (1) | Length (12) | init_offset |
+-------------+-------------+---------------------------+
| protected_size | min_ram_size |
+---------------------------+---------------------------+
init_offset
is the offset in bytes from the beginning of binary payload (i.e. the actual application binary) that contains the first instruction to execute (typically the_start
symbol).protected_size
the amount of flash, in bytes, after the header, to prevent the process from writing to.minimum_ram_size
the minimum amount of memory, in bytes, the process needs.
If the Main TLV header is not present, these values all default to 0
.
Writeable flash regions
indicate portions of the binary that the process
intends to mutate in flash.
0 2 4 6 8
+-------------+-------------+---------------------------+
| Type (2) | Length (8) | offset |
+-------------+-------------+-------------+-------------+
| size |
+---------------------------+
offset
the offset from the beginning of the binary of the writeable region.size
the size of the writeable region.
The Package name
specifies a unique name for the binary. Its only field is
an UTF-8 encoded package name.
0 2 4
+-------------+-------------+----------...-+
| Type (3) | Length | package_name |
+-------------+-------------+----------...-+
package_name
is an UTF-8 encoded package name
The process code itself has no particular format. It will reside in flash, but the specific address is determined by the platform. Code in the binary should be able to execute successfully at any address, e.g. using position independent code.