[media] cx2341x.rst: add the contents of fw-calling.txt

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

--------------------------------

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.