447d6fb8cc
Date: From: Mauro Carvalho Chehab <mchehab@infradead.org> There are some docs at V4L/DVB tree that were never included at kernel. This patch includes those docs. Signed-off-by: Mauro Carvalho Chehab <mchehab@infradead.org>
70 lines
2.8 KiB
Plaintext
70 lines
2.8 KiB
Plaintext
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.
|
|
|