mirror of
https://github.com/torvalds/linux.git
synced 2024-11-05 19:41:54 +00:00
[media] cx2341x.rst: add the contents of fw-calling.txt
Convert it to ReST and add its contents at this file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
This commit is contained in:
Mauro Carvalho Chehab
parent
91e71c2ba8
commit
d9b8a3f099
@ -1,6 +1,81 @@
|
||||
The cx2341x driver
|
||||
==================
|
||||
|
||||
How to call the firmware API
|
||||
----------------------------
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
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 this
|
||||
chapter.
|
||||
|
||||
The return value is a 32-bit enumerator. Only two values are currently defined:
|
||||
|
||||
- 0=success
|
||||
- -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 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.
|
||||
|
||||
|
||||
Encoder firmware API description
|
||||
--------------------------------
|
||||
|
||||
|
||||
@ -1,69 +0,0 @@
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user