Message Layer

The message layer sits on top of the buffer management layer discussed above. The message layer provides system management and error reporting functionality. Many of the functions exposed through this layer take more time to process than is typically available during a single SPI or I2C transaction. Functions exposed through the message layer include managing neural network state, entering sleep modes, and performing system updates.

The message layer is accessed by writing complete command frames to the command buffer at index 0, and reading complete response frames from the response buffer at index 1. Multiple commands may be queued in the command buffer, but every command must fit into the command buffer in its entirety. It is not valid to write commands into the command buffer in multiple non-atomic transactions.

Partially received commands are discarded and a corresponding error is produced in the response buffer.

Failure to empty the response buffer delays execution of commands in the command buffer.

Command Queuing

Command frames are consumed from the command queue once command execution has completed. Commands can only complete if there is enough space in the response queue. Execution of a command may result in at most one response on the response queue. Responses are always in the same order as the corresponding commands in the command queue.

Note that most commands do not produce any response on success. In this way, the host can typically take a non-zero response buffer fill level as an indicator that an error has occurred.

If a notification on command completion is required, the host may still use one of the following two methods to accomplish this:

1. The ECHO command always produces a response, and may thus act as a marker. By queueing an ECHO command after the actual command, and configuring IRQs for the response buffer, the host will be notified whenever the ECHO response is produced.

2. Alternatively, the IRQ threshold of the command buffer may be configured such that an IRQ is triggered exactly once the current command has been consumed.

Asynchronous Responses

Given enough space in the response buffer, the TSP1 may place asynchronous messages in the response buffer. These messages are not produced as a response to a command, but inform about critical events such as irrecoverable errors. While asynchronous responses may inform about critical errors, they do not transition the command queue into the error state.

The transaction ID field of asynchronous responses monotonically increases from zero for every reboot of the TSP, as well as when waking up from deep sleep.

Insufficient space in the response buffer will not cause loss of asynchronous messages. As soon as enough space is available, the last pending asynchronous message of a certain type will be emitted.

Upon successful boot-up, the TSP1 places an ASYNC_READY message in the response buffer, and the buffer IRQs are configured to pull the TSP1_INTB signal low as soon as there is any data in the response buffer.

Error State

Whenever a command produces an error response, the command queue enters the error state. As long as the queue is in the error state, commands currently in the queue, as well as all newly queued commands, are immediately discarded. This behaviour enables opportunistic pipelining of commands with the assumption that commands complete without error.

To exit the error state, queue the special CLEAR_ERROR command. Once this command has been processed, subsequent commands will be accepted and processed as usual. The error state is cleared, and the command queue resumes normal operation.

Framing

Every command and response is encoded at the byte level as follows:

Bytes	Name	Description
0-1	PREAMBLE	The preamble is fixed to 0x55CC for commands, and 0xCC55 for responses. The preamble is used by the TSP1 to re-synchronise on framing errors, and similarly simplifies parsing response frames on the host side.
2-3	ID	Code identifying the command or response type.
4-5	N_BYTES	The number of payload bytes n. Valid values for this field depend on the selected command or response type.
6-7	TID	User-provided transaction ID. This field is mirrored in command responses and may be used by the host to easily correlate the command and the response.
8-7+n	PAYLOAD	Payload bytes, if any.
8 + n - 11 + n	CRC	Four-byte CRC-32 of the entire command or response frame. The CRC does not include the CRC field itself.

Command Overview

The following table provides an overview of all commands that may be sent to the TSP1:

ID	Name	Description
0x0010	ECHO	Replicates the given payload in an “echo response”.
0x0021	SECURE_UPDATE	Sends a chunk of a signed and encrypted NVM image for updating to the TSP1. Call repeatedly until all chunks have been uploaded.
0x0022	SECURE_UPDATE_CANCEL	Cancels any secure update that is currently in progress.
0x0023	SECURE_UPDATE_FINISH	Instructs the TSP1 to finalise the secure download.
0x0050	REBOOT	Halts and resets the neural processing unit, clears all buffers, and reboots the TSP1 into its initial system state. This command must be issued to complete an NVM image update.
0x0060	DEEP_SLEEP	Puts the device into a deep sleep state.
0x0080	NN_STATUS	Provides information about the specified neural network.
0x0081	NN_START	Starts the specified neural networks.
0x0082	NN_STOP	Stops operation of the specified neural network.
0x0083	NN_PAUSE	Pauses operation of the specified neural network, leaving it in a state where operations can be resumed quickly.
0x0084	NN_FINISH	Same as NN_PAUSE, but disables input peripherals and waits for neural network execution to stall due to a lack of input.
0x7FFF	CLEAR_ERROR	Clears the command queue error state.

Command ECHO

ID	0x0010
Payload length	Arbitrary (limited by the command and response buffer size)
Success responses	DATA
Error responses	ERR_LEN

The ECHO command produces a DATA response with the original payload in the data payload.

This command is intended for the following uses:

• To insert markers into the response queue.

• To stress-test communication during system bring-up.

Error responses

This command produces an ERR_LEN response if the response cannot possibly fit into the response buffer. This error state can only be reached if the response buffer is smaller than the command buffer.

Command SECURE_UPDATE

ID	0x0021
Payload length	Multiples of 144 bytes
Success responses	None
Error responses	ERR_ARG, ERR_BUSY, ERR_LEN, ERR_MEM

Uploads one or multiple NVM image chunks to the TSP. Chunks are linearly packed into the NVM image file produced by the ABR toolchain. A chunk consists of 16 header bytes and 128 payload bytes, for a total of 144 bytes.

This function is asynchronous; the SECURE_UPDATE command will be done before writes to NVM have completed. Potential errors will be reported with either the next SECURE_UPDATE command or as part of SECURE_UPDATE_DONE.

Caution

Starting a secure firmware update effectively erases the currently loaded NVM image. If the firmware update is not completed successfully, then the TSP1 will boot into ROM on the next reboot. Further firmware update attempts may be made from the ROM.

Error responses

This command may return the following error responses:

• ERR_ARG if the firmware cannot parse the information embedded in the chunk header.

• ERR_BUSY if the neural processing unit is currently active. Ensure that all neural networks have been halted before attempting to perform a firmware update.

• ERR_LEN if the payload is not a multiple of 144 bytes long.

• ERR_MEM if writing to NVM fails. This may happen because of power supply limitations or because the affected NVM cells have reached their maximum number of write cycles. Note that memory errors might originate from the previous SECURE_UPDATE command.

Command SECURE_UPDATE_CANCEL

ID	0x0022
Payload length	None
Success responses	None
Error responses	None

Cancels any in-progress firmware update. Discards any error that may have occurred during an asynchronous NVM write last scheduled using SECURE_UPDATE. Does nothing if no firmware update is currently in progress.

Caution

Cancelling an in-progress firmware update will result in the TSP1 booting into the ROM bootloader on the next reboot. Further firmware update attempts may be made there.

Command SECURE_UPDATE_FINISH

ID	0x0023
Payload	None
Success responses	None
Error responses	ERR_CRYPT, ERR_MEM

Finalises the firmware update. This includes verifying the integrity of the downloaded NVM image and ensuring that the device will boot into the new firmware on the next reboot.

Error responses

The SECURE_UPDATE_FINISH command may produce the following error responses:

• ERR_CRYPT if the downloaded NVM image fails cryptographic verification.

• ERR_MEM if writing to NVM fails (e.g., because of power supply limitations or worn out NVM cells). Detailed information on the error is included in the ERR_MEM payload.

Command REBOOT

ID	0x0050
Payload	None
Success responses	None
Error responses	None

Reboots the device.

This command resets the IRQ mask to only include the response buffer. Additionally, all neural networks will be halted and all associated peripherals will be deactivated. The device will reboot and all state information will be reset.

Rebooting the device is necessary to complete an NVM image update.

Note

Rebooting the device will reset the buffer IRQ thresholds and the IRQ mask. By default, the response buffer IRQ is enabled. The firmware will place an ASYNC_READY response frame in the response buffer after it has booted; this signals completion of this command.

Command DEEP_SLEEP

ID	0x0060
Payload	None
Success responses	None
Error responses	None

Places the device into deep sleep.

All neural networks will be halted and all associated peripherals will be deactivated. The TSP1 device will enter a low power state and will need to be awoken by pulling the TSP1_WAKE signal pin high. Waking up from deep sleep is faster than boot-up after reset or power-up.

After waking up from deep sleep, the TSP1 will place an ASYNC_READY message in the response buffer. Make sure to configure the IRQ mask and threshold such that the ASYNC_READY message is reacted to.

Caution

Do not issue this command if the TSP1_WAKE signal is not connected to the host system. A rising edge on TSP1_WAKE is required to wake the TSP1 back up.

Command NN_INFO

ID	0x0080
Payload	4 bytes
Success responses	NN_INFO
Error responses	ERR_ARG, ERR_LEN

Provides information about the specified neural network.

Information includes the total number of neural networks managed by the firmware, the number of inputs and outputs for that network, the buffer index offset for that neural network.

Payload encoding

Bytes	Name	Description
0	ID	Neural network ID that should be queried.
1-3	Reserved	Not used.

Response encoding

Bytes	Name	Description
0	VALID	0 if there is no neural network in this slot, 1 if a network is in that slot. Valid neural network indices are always contiguous and start at zero. That is, if VALID is set to 0 for neural network i, then it will also be false for all j > i.
1	IDX	The requested neural network index.
2	N_TOTAL	Total number of neural networks currently managed by the firmware.
3	N_IN	Number of input buffers.
4	N_OUT	Number of output buffers.
5	BUF_IN0	Index of the first input buffer for this neural network.
6	BUF_OUT0	Index of the first output buffer for this neural network.
7	STATE	Current neural network state. The following are valid values: STOPPED = 0: The neural network is currently stopped. RUNNING = 1: The neural network is currently running. PAUSED = 2: The neural network is currently paused. FINISHED = 3: The neural network has finished processing all input data and may resume.

Error responses

The NN_STATUS command may produce the following error responses:

• ERR_ARG if the neural network slot index is out-of-range. A network may still be invalid, even if no error response is returned. In that case the “valid” flag is set to false.

• ERR_LEN if the payload length is not four.

Command NN_START

ID	0x0081
Payload	4 bytes
Success responses	None
Error responses	ERR_ARG, ERR_LEN

Starts operation of the specified neural networks. Input data will be processed as they are received once the neural networks are in the running state.

All neural networks specified will be started and enter the “running” state. Associated I/O peripherals will be activated. Data will be processed starting with any data already in the input buffers, and as they are received from the peripherals or host. This command has no effect for any neural networks that are already running.

Payload encoding

The four payload bytes form a bit-mask that determines which neural networks (index 0 to 31) should start execution.

Bytes	Name	Description
0-4	MASK	Bit mask encoding which neural networks should be started. The i-th bit in the mask corresponds to the neural network with index i. Neural network indices are assigned during the application design process.

Error responses

The NN_START command may produce the following error responses:

• ERR_ARG if a non-existent neural network is selected in the bit-mask.

• ERR_LEN if the payload length is not four.

Command NN_STOP

ID	0x0082
Payload	4 bytes
Success responses	None
Error responses	ERR_ARG, ERR_LEN

Forces operation of the specified neural networks to stop. This will stop associated peripherals and clear all buffers associated with the neural network.

This command has no effect on any neural networks that are already stopped.

Note

Use NN_FINISH if data stored in the neural network input buffers should be consumed as much as possible before the neural network is paused. Alternatively, use NN_PAUSE if consuming data before pausing is not a concern. Both commands allow resuming the network from its current state.

Payload encoding

The four payload bytes form a bit-mask that determines which neural networks (index 0 to 31) should be stopped.

Bytes	Name	Description
0-4	MASK	Bit mask encoding which neural networks should be stopped. The i-th bit in the mask corresponds to the neural network with index i. Neural network indices are assigned during the application design process.

Error responses

The NN_STOP command may produce the following error responses:

• ERR_ARG if a non-existent neural network is selected in the bit-mask.

• ERR_LEN if the payload length is not four.

Command NN_PAUSE

ID	0x0083
Payload	4 bytes
Success responses	None
Error responses	ERR_ARG, ERR_LEN

Pauses operation of the selected neural networks. Associated peripherals will be stopped. Data will remain in the input and output buffers as well as in the pre-, post- and neural network processing pipeline. Transfers and processing will resume when the neural networks are restarted through the NN_START command.

Caution

When using I/O peripherals, data in the input buffers will become disjoint. Use NN_FINISH instead of NN_PAUSE to consume as much data as possible from the input buffers and to stop peripherals.

Payload encoding

The four payload bytes form a bit-mask that determines which neural networks (index 0 to 31) should be paused.

Bytes	Name	Description
0-4	MASK	Bit mask encoding which neural networks should be paused. The i-th bit in the mask corresponds to the neural network with index i. Neural network indices are assigned during the application design process.

Error responses

The NN_PAUSE command may produce the following error responses:

• ERR_ARG if a non-existent neural network is selected in the bit-mask.

• ERR_LEN if the payload length is not four.

Command NN_FINISH

ID	0x0084
Payload	4 bytes
Success responses	None
Error responses	ERR_ARG, ERR_LEN

Pauses operation of the selected neural networks, but first consumes as much data as possible from the input buffers. Associated peripherals will be stopped. Transfers and processing will resume when the neural networks are restarted through the NN_START command.

Note

Depending on the network configuration, it may not be possible to consume all input data. For example, data may be consumed in blocks that are larger than the remaining data in the input buffer, or data from one input runs dry before the network state is advanced enough for data from another input to be consumed.

Payload encoding

The four payload bytes form a bit-mask that determines which neural networks (index 0 to 31) should be paused.

Bytes	Name	Description
0-4	MASK	Bit mask encoding which neural networks should be paused. The i-th bit in the mask corresponds to the neural network with index i. Neural network indices are assigned during the application design process.

Error responses

The NN_FINISH command may produce the following error responses:

• ERR_ARG if a non-existent neural network is selected in the bit-mask.

• ERR_LEN if the payload length is not four.

Command CLEAR_ERROR

ID	0x7FFF
Payload	None
Success responses	None
Error responses	None

Special command that resets the command queue error state. This is the only command that is handled once the command queue enters the error state. All other commands are immediately discarded.

Response Overview

The following table lists response types that may be placed in the response queue.

ID	Name	Description
0x8000	DATA	Generic response containing requested data.
0x8001	NN_INFO	Response containing information about the queried neural network.
0x9000	ERR_ARG	Error response indicating an issue with the arguments provided in the command payload.
0x9001	ERR_BUSY	Error response indicating that this command cannot be issued right now due to the application being active.
0x9002	ERR_LEN	Error response indicating an invalid payload length for the given command.
0x9003	ERR_MEM	Error response indicating a volatile or non-volatile memory access error.
0x9004	ERR_CRYPT	Error response indicating a cryptographic verification error.
0x9006	ERR_CHECKSUM	Error response indicating that the checksum has been mismatched.
0x9007	ERR_FRAMING	Error response indicating that the command queue was not able to extract a command frame.
0xA001	ASYNC_READY	Asynchronous message indicating that the TSP1 has successfully booted or exited sleep mode.
0xA002	ASYNC_ERR_ECC	Asynchronous message indicating a non-recoverable ECC error during execution.
0xA003	ASYNC_ERR_NPU	Asynchronous message indicating a critical error from the neural network processor.