iTVC15 Firmware Calling

This page describes how to make calls to the firmware api. The upload procedure will be described on the firmware-upload.html page and the API will be described on the firmware-api.html page. Information about the memory map of the card and the registers are described on the memory-map.html page.

How to call

The preferred calling convention is known as the firmware mailbox. The mailboxes are basically a fixed length array that serves as the call-stack.

The Firmware API documentation tells us to use the appropriate field in the FWID structure, yet no such field exists. A code comment tells us that the firmware mailboxes may be located by searching the encoder and decoder memory for a 16 byte signature. That signature will be located on a 256-byte boundary.

Signature
`0x78,0x56,0x34,0x12,0x12,0x78,0x56,0x34, 0x34,0x12,0x78,0x56,0x56,0x34,0x12,0x78`

The firmware implements 20 mailboxes of 20 32bit words. The first 10 are reserved for API calls. The second 10 are used by the firmware for event notification.

Index	Name
0	Flags
1	Command
2	Return value
3	Timeout
4-19	Parameter/Result

The flags are defined in the following table. The direction is from the perspective of the firmware.

Bit	Direction	Purpose
2	O	Firmware has processed the command.
1	I	Driver has finished setting the parameters.
0	I	Driver is using this mailbox.

The command is a 32bit enumerator. The API specifics may be found on the firmware-api.html page.

The return value is a 32bit enumerator. Only two values are currently defined: 0=success and -1=command undefined.

There are 16 parameters/results 32bit fields. The driver populates these fields with values for all the parameters required by the call. The driver overwrites these fields with result values returned by the call. The API specifics may be found on the firmware-api.html page.

The timeout value protects the card from a hung driver thread. If the driver doesn't handle the completed call within the timeout specified, the firmware will reset that mailbox.

To make an API call, the driver iterates over each mailbox looking for the first one available (bit 0 has been cleared). The driver sets that bit, fills in the command enumerator, the timeout value and any required parameters. The driver then sets the parameter ready bit (bit 1). The firmware scans the mailboxes for pending commands, processes them, sets the result code, populates the result value array with that call's return values and sets the call complete bit (bit 2). Once bit 2 is set, the driver should retrieve the results and clears all the flags. If the driver does not perform this task within the time set in the timeout register, the firmware will reset that mailbox.

Event notifications are sent from the firmware to the host. The host tells the firmware which events it is interested in via an API call. That call tells the firmware which notification mailbox to use. The firmware signals the host via an interrupt. Only the 16 Results fields are used, the Flags, Command, Return value and Timeout words are not used.