Commit | Line | Data |
---|---|---|
447d6fb8 MCC |
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 |