| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869 |
- This page describes how to make calls to the firmware api.
- 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.
- Firmware mailboxes can 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 32-bit 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 32-bit enumerator. The API specifics may be found in the
- fw-*-api.txt documents.
- The return value is a 32-bit enumerator. Only two values are currently defined:
- 0=success and -1=command undefined.
- There are 16 parameters/results 32-bit 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 in the fw-*-api.txt documents.
- 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 clear 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.
|
