diff options
Diffstat (limited to 'Documentation/video4linux/cx2341x/fw-calling.txt')
| -rw-r--r-- | Documentation/video4linux/cx2341x/fw-calling.txt | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/Documentation/video4linux/cx2341x/fw-calling.txt b/Documentation/video4linux/cx2341x/fw-calling.txt new file mode 100644 index 000000000000..8d21181de537 --- /dev/null +++ b/Documentation/video4linux/cx2341x/fw-calling.txt @@ -0,0 +1,69 @@ +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. + |