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