Commands

General command/answer structure

Commands and answers follow the same structure:

Property	Size	Payload
32 bits	32 bits	Size bytes

The Property 32 bits field contains a unique identifier of the property along with:

• a FAILURE flag in the most significant bit (bit 31 if properties bits are numbered 31 down to 0)

• a WRITE flag in the bit 30 used to set a property (some properties can be read or set, such as FPGA states or other communication parameters)

The answer starts with:

• the same property as the command if the command succeeded

• the same property plus the FAILURE flag set if the command failed

• zero plus the FAILURE set if the command was not processed, which may happen if the Size was too large, or if the command is not implemented by the device.

Regarding the Size of the payload:

• a typical read case is to send a property and a 0-size payload to get the value of the property

• a typical write command is answered by the property and a 0-size payload to acknowledge the command was received and executed.

• some read command can have some non-null payload. For example for registers accesses you need to provide the register address.

• some write acknowledge replies can have some non-null payload. For example a configuration can be returned in a write acknowledge.

Required properties and minimal support

Any implementation of Treuzell shall support the following properties

• SERIAL

• RELEASE_VERSION

• BUILD_DATE

• DEVICES

• DEVICE_NAME

• DEVICE_COMPATIBLE

Those properties should return value 0 if the board is not able to provide the requested information. If the number of devices is 0, name and compatible properties may be omitted.

Any implementation of Treuzell shall also answer with the UNKNOWN_CMD property (0 + FAILURE flag: 0x80000000) to any unknown request.

Basic functional state should be achieved by enabling devices in order (with the ENABLE property) and streaming from the last to the first (with the STREAM property), but the implementation of a complete init sequence on the board is not mandatory, relying on the host to provide register access sequences is possible.

List of properties

Board-level commands

FPGA_STATE

Note

This property is deprecated, and should not be used in new designs

Property number: (0x71)

command

FPGA_STATE	Size (0)
32 bits	32 bits

answer

FPGA_STATE	Size (0)	State
32 bits	32 bits	32 bits

The meaning of “state” is not specified yet. In current implementations, the FPGA is always ready when Treuzell is running, a read to this property always returns 0x10000, and HAL treats any non-zero answer as a FPGA ready.

SERIAL

Property number: (0x72)

command

SERIAL (0x72)	Size (0)
32 bits	32 bits

answer

SERIAL (0x72)	Size (4 or 8)	Board serial number
32 bits	32 bits	32 or 64 bits

RELEASE_VERSION

Property number: (0x79)

command

RELEASE_VERSION (0x79)	Size (0)
32 bits	32 bits

answer

RELEASE_VERSION (0x79)	Size (4)	Patch revision	Minor revision	Major revision	0
32 bits	32 bits	8 bits	8 bits	8 bits	8 bits

BUILD_DATE

Property number: (0x7A)

command

BUILD_DATE (0x7A)	Size (0)
32 bits	32 bits

answer

BUILD_DATE (0x7A)	Size (8)	Build Timestamp
32 bits	32 bits	64 bits

This property is the UNIX timestamp of the system software image generation.

Device commands

DEVICES

Property number: (0x10000)

command

DEVICES (0x10000)	Size (0)	Device	Error code
32 bits	32 bits	32 bits	32 bits

answer

DEVICES (0x10000)	Size (4)	Number of devices
32 bits	32 bits	32 bits

DEVICE_NAME

Property number: (0x10001)

command

DEVICE_NAME (0x10001)	Size (4)	Device
32 bits	32 bits	32 bits

answer

DEVICE_NAME (0x10001)	Size (4+strlen)	Device	device name (UTF-8, null terminated)
32 bits	32 bits	32 bits	string length, with null termination

failure

DEVICE_NAME + FAILURE (0x80010001)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

DEVICE_IF_FREQ

Property number: (0x10002)

The following commands allow the modification of the frequency of the interface used to communicate with the device, when possible.

command

DEVICE_IF_FREQ (0x10002)	Size (4)	Device
32 bits	32 bits	32 bits

answer

DEVICE_IF_FREQ (0x10002)	Size (8)	Device	Frequency (in Hz)
32 bits	32 bits	32 bits	32 bits

failure

DEVICE_IF_FREQ + FAILURE (0x80010002)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

write command

DEVICE_IF_FREQ + WRITE (0x40010002)	Size (8)	Device	Frequency (in Hz)
32 bits	32 bits	32 bits	32 bits

The frequency provided will be regarded as the highest allowed clock, but the clock set may be lower than the required one, as it is not always possible to synthesize any frequency.

Set 0 to reset the frequency to the system default value.

write answer

DEVICE_IF_FREQ + WRITE (0x40010002)	Size (4 or 8)	Device	Frequency set (in Hz) (optional)
32 bits	32 bits	32 bits	32 bits

If the answer includes a frequency, the enclosed frequency shall be the set frequency, and not the requested one, if the exact requested frequency could not be applied.

write failure

DEVICE_IF_FREQ + WRITE + FAILURE (0xC0010002)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

DEVICE_COMPATIBLE

Property number: (0x10003)

The board is responsible for advertising what devices are available on it. To allow to match hardware with drivers, compatibility strings are used, as in the Open Firmware device tree (also used in the Linux kernel on some architectures such as ARM).

command

DEVICE_COMPATIBLE (0x10003)	Size (4)	Device
32 bits	32 bits	32 bits

answer

DEVICE_COMPATIBLE (0x10003)	Size (4+strlen)	Device	compatible strings (UTF-8, null separated and terminated)
32 bits	32 bits	32 bits	strings length, with null terminations

A device may have several compatible strings, the answer length is used to know if more strings are to be found after the first one.

failure

DEVICE_COMPATIBLE + FAILURE (0x80010003)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

DEVICE_ENABLE

Property number: (0x10010)

Enable or disable a device. Enabling a device usually consists in running the power sequence and applying initialization sequence, hence this operation may take time, and any configuration made before a disable/enable cycle may be lost. However, a device is just expected to start in a reasonable state for streaming, not necessarily the same as in the first boot. It may, for instance, depend on the state of other devices.

Status 1 for enabled device, 0 for disabled device. Other values are reserved for future use.

command

DEVICE_ENABLE (0x10010)	Size (4)	Device
32 bits	32 bits	32 bits

answer

DEVICE_ENABLE (0x10010)	Size (8)	Device	Status
32 bits	32 bits	32 bits	32 bits

failure

DEVICE_ENABLE + FAILURE (0x80010010)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

write command

DEVICE_ENABLE + WRITE (0x40010010)	Size (8)	Device	Status
32 bits	32 bits	32 bits	32 bits

write answer

DEVICE_ENABLE + WRITE (0x40010010)	Size (4)	Device
32 bits	32 bits	32 bits

write failure

DEVICE_ENABLE + WRITE + FAILURE (0xC0010010)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

DEVICE_REG32

Property number: (0x10102)

Accesses registers on the designated device. Register addresses and content are transfer on 32 bits, regardless of the address and register size on the device. Most significant bits are dropped when needed. 64 bits accesses cannot be performed with this command.

Devices and registers are displayed as seen by the board running Treuzell. A given device may map other devices in its own regmap.

command

DEVICE_REG32 (0x10102)	Size	Device	Start Address	Number of registers
32 bits	32 bits	32 bits	32 bits	32 bits

answer

DEVICE_REG32 (0x10102)	Size	Device	Start Address	Register values
32 bits	32 bits	32 bits	32 bits	number of registers * 32 bits

failure

DEVICE_REG32 + FAILURE (0x80010102)	Size (8)	Device	Start Address	Error code
32 bits	32 bits	32 bits	32 bits	32 bits

write command

DEVICE_REG32 + WRITE (0x40010102)	Size	Device	Start Address	Register values
32 bits	32 bits	32 bits	32 bits	number of registers * 32 bits

write answer

DEVICE_REG32 + WRITE (0x40010102)	Size (8)	Device	Start Address
32 bits	32 bits	32 bits	32 bits

write failure

DEVICE_REG32 + WRITE + FAILURE (0xC0010102)	Size (12)	Device	Start Address	Error code
32 bits	32 bits	32 bits	32 bits	32 bits

DEVICE_STREAM

Property number: (0x10200)

Start or stop the streaming on a given device.

Status 1 if the device is streaming, 0 for stopped device. Other values are reserved for future use.

command

DEVICE_STREAM (0x10200)	Size (4)	Device
32 bits	32 bits	32 bits

answer

DEVICE_STREAM (0x10200)	Size (8)	Device	Status
32 bits	32 bits	32 bits	32 bits

failure

DEVICE_STREAM + FAILURE (0x80010200)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

write command

DEVICE_STREAM + WRITE (0x40010200)	Size (8)	Device	Status
32 bits	32 bits	32 bits	32 bits

write answer

DEVICE_STREAM + WRITE (0x40010200)	Size (4)	Device
32 bits	32 bits	32 bits

write failure

DEVICE_STREAM + WRITE + FAILURE (0xC0010200)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

DEVICE_OUTPUT_FORMAT

Property number: (0x10201)

Access the streaming format on a given device.

Format strings are mimicking RFC2046 Media Types, but types are not registered at IANA.

When the output format of a device is modified, it may modify the output format of downstream devices to manage a valid configuration of the pipeline, but shall not modify the configuration of upstream devices. If the host enforces the output format of a device other than the upstream one (device 0), it is responsible to set a valid pipeline config.

command

DEVICE_OUTPUT_FORMAT (0x10201)	Size (4)	Device
32 bits	32 bits	32 bits

answer

DEVICE_OUTPUT_FORMAT (0x10201)	Size	Device	Current output format (UTF-8, null terminated)
32 bits	32 bits	32 bits	string length, with null termination

failure

DEVICE_OUTPUT_FORMAT + FAILURE (0x80010201)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

write command

DEVICE_OUTPUT_FORMAT + WRITE (0x40010201)	Size	Device	Requested output format (UTF-8, null terminated)
32 bits	32 bits	32 bits	string length, with null termination

write answer

DEVICE_OUTPUT_FORMAT + WRITE (0x40010201)	Size	Device	New output format (UTF-8, null terminated)
32 bits	32 bits	32 bits	string length, with null termination

write failure

DEVICE_OUTPUT_FORMAT + WRITE + FAILURE (0xC0010201)	Size (8)	Device	Error code
32 bits	32 bits	32 bits	32 bits

Protocol exceptions

For backward compatibility reasons, there are 2 exceptions to the general command/answer structure.

Those commands are deprecated, and any new implementation shall support regular accesses to the DEVICE_REG32 property, the following properties should never be used in any design. Design recommendation is to not implement the following commands, so that it gets answered with an UNKNOWN_CMD code.

READ_DEVICE_REG32

Property number: (0x55)

READ_DEVICE_REG32 (0x55)	FPGA ADDRESS
32 bits	32 bits

A command with the property READ_DEVICE_REG32 in an 8-byte bulk USB packet shall be treated as legacy: the content of the second 32-bit register shall be treated as the FPGA register address, the number of registers to read shall be inferred as 1.

In that case, the answer shall be a 12-byte bulk packet formatted as follows:

READ_DEVICE_REG32 (0x55)	FPGA ADDRESS	VALUE
32 bits	32 bits	32 bits

A command with the property READ_DEVICE_REG32 shall be treated as the DEVICE_REG32 property if the bulk USB packet size is not exactly 8 (the answer property id should still be READ_DEVICE_REG32. The only ambiguous answer is the read of 0 registers, which is also 12 bytes long. The host shall not request such read)

In case of failure, the answer shall use the READ_DEVICE_REG32 + FAILURE flag (0x80000055) property id and follow the general command/answer structure.

WRITE_DEVICE_REG32

Property number: (0x56)

This command shall be treated as a DEVICE_REG32 + WRITE flag (0x40010102), just keeping WRITE_DEVICE_REG32 as property id for the answer, except if the size of the bulk USB packet is exactly 12. In this case, the command shall be interpreted as follows:

WRITE_DEVICE_REG32 (0x56)	FPGA ADDRESS	VALUE
32 bits	32 bits	32 bits

In this case the number of registers to write shall be inferred as 1. The answer to a successful write request shall be an 8-byte bulk packet as follows:

WRITE_DEVICE_REG32 (0x56)	FPGA ADDRESS
32 bits	32 bits

In case of failure, the answer shall use the WRITE_DEVICE_REG32 + FAILURE flag (0x80000056) property id and follow the general command/answer structure.