| Mauro Carvalho Chehab | 447d6fb | 2006-05-22 10:31:37 -0300 | [diff] [blame] | 1 | This page describes how to make calls to the firmware api. |
| 2 | |
| 3 | How to call |
| 4 | =========== |
| 5 | |
| 6 | The preferred calling convention is known as the firmware mailbox. The |
| 7 | mailboxes are basically a fixed length array that serves as the call-stack. |
| 8 | |
| 9 | Firmware mailboxes can be located by searching the encoder and decoder memory |
| 10 | for a 16 byte signature. That signature will be located on a 256-byte boundary. |
| 11 | |
| 12 | Signature: |
| 13 | 0x78, 0x56, 0x34, 0x12, 0x12, 0x78, 0x56, 0x34, |
| 14 | 0x34, 0x12, 0x78, 0x56, 0x56, 0x34, 0x12, 0x78 |
| 15 | |
| 16 | The firmware implements 20 mailboxes of 20 32-bit words. The first 10 are |
| 17 | reserved for API calls. The second 10 are used by the firmware for event |
| 18 | notification. |
| 19 | |
| 20 | Index Name |
| 21 | ----- ---- |
| 22 | 0 Flags |
| 23 | 1 Command |
| 24 | 2 Return value |
| 25 | 3 Timeout |
| 26 | 4-19 Parameter/Result |
| 27 | |
| 28 | |
| 29 | The flags are defined in the following table. The direction is from the |
| 30 | perspective of the firmware. |
| 31 | |
| 32 | Bit Direction Purpose |
| 33 | --- --------- ------- |
| 34 | 2 O Firmware has processed the command. |
| 35 | 1 I Driver has finished setting the parameters. |
| 36 | 0 I Driver is using this mailbox. |
| 37 | |
| 38 | |
| 39 | The command is a 32-bit enumerator. The API specifics may be found in the |
| 40 | fw-*-api.txt documents. |
| 41 | |
| 42 | The return value is a 32-bit enumerator. Only two values are currently defined: |
| 43 | 0=success and -1=command undefined. |
| 44 | |
| 45 | There are 16 parameters/results 32-bit fields. The driver populates these fields |
| 46 | with values for all the parameters required by the call. The driver overwrites |
| 47 | these fields with result values returned by the call. The API specifics may be |
| 48 | found in the fw-*-api.txt documents. |
| 49 | |
| 50 | The timeout value protects the card from a hung driver thread. If the driver |
| 51 | doesn't handle the completed call within the timeout specified, the firmware |
| 52 | will reset that mailbox. |
| 53 | |
| 54 | To make an API call, the driver iterates over each mailbox looking for the |
| 55 | first one available (bit 0 has been cleared). The driver sets that bit, fills |
| 56 | in the command enumerator, the timeout value and any required parameters. The |
| 57 | driver then sets the parameter ready bit (bit 1). The firmware scans the |
| 58 | mailboxes for pending commands, processes them, sets the result code, populates |
| 59 | the result value array with that call's return values and sets the call |
| 60 | complete bit (bit 2). Once bit 2 is set, the driver should retrieve the results |
| 61 | and clear all the flags. If the driver does not perform this task within the |
| 62 | time set in the timeout register, the firmware will reset that mailbox. |
| 63 | |
| 64 | Event notifications are sent from the firmware to the host. The host tells the |
| 65 | firmware which events it is interested in via an API call. That call tells the |
| 66 | firmware which notification mailbox to use. The firmware signals the host via |
| 67 | an interrupt. Only the 16 Results fields are used, the Flags, Command, Return |
| 68 | value and Timeout words are not used. |
| 69 | |