forked from analogdevicesinc/linux
-
Notifications
You must be signed in to change notification settings - Fork 3
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
V4L/DVB (3809b): Added missing docs at kernel tree
Date: From: Mauro Carvalho Chehab <[email protected]> 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 <[email protected]>
- Loading branch information
Showing
8 changed files
with
1,740 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,319 @@ | ||
| Decoder firmware API description | ||
| ================================ | ||
|
|
||
| Note: this API is part of the decoder firmware, so it's cx23415 only. | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_PING_FW | ||
| Enum 0/0x00 | ||
| Description | ||
| This API call does nothing. It may be used to check if the firmware | ||
| is responding. | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_START_PLAYBACK | ||
| Enum 1/0x01 | ||
| Description | ||
| Begin or resume playback. | ||
| Param[0] | ||
| 0 based frame number in GOP to begin playback from. | ||
| Param[1] | ||
| Specifies the number of muted audio frames to play before normal | ||
| audio resumes. | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_STOP_PLAYBACK | ||
| Enum 2/0x02 | ||
| Description | ||
| Ends playback and clears all decoder buffers. If PTS is not zero, | ||
| playback stops at specified PTS. | ||
| Param[0] | ||
| Display 0=last frame, 1=black | ||
| Param[1] | ||
| PTS low | ||
| Param[2] | ||
| PTS high | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_PLAYBACK_SPEED | ||
| Enum 3/0x03 | ||
| Description | ||
| Playback stream at speed other than normal. There are two modes of | ||
| operation: | ||
| Smooth: host transfers entire stream and firmware drops unused | ||
| frames. | ||
| Coarse: host drops frames based on indexing as required to achieve | ||
| desired speed. | ||
| Param[0] | ||
| Bitmap: | ||
| 0:7 0 normal | ||
| 1 fast only "1.5 times" | ||
| n nX fast, 1/nX slow | ||
| 30 Framedrop: | ||
| '0' during 1.5 times play, every other B frame is dropped | ||
| '1' during 1.5 times play, stream is unchanged (bitrate | ||
| must not exceed 8mbps) | ||
| 31 Speed: | ||
| '0' slow | ||
| '1' fast | ||
| Param[1] | ||
| Direction: 0=forward, 1=reverse | ||
| Param[2] | ||
| Picture mask: | ||
| 1=I frames | ||
| 3=I, P frames | ||
| 7=I, P, B frames | ||
| Param[3] | ||
| B frames per GOP (for reverse play only) | ||
| Param[4] | ||
| Mute audio: 0=disable, 1=enable | ||
| Param[5] | ||
| Display 0=frame, 1=field | ||
| Param[6] | ||
| Specifies the number of muted audio frames to play before normal audio | ||
| resumes. | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_STEP_VIDEO | ||
| Enum 5/0x05 | ||
| Description | ||
| Each call to this API steps the playback to the next unit defined below | ||
| in the current playback direction. | ||
| Param[0] | ||
| 0=frame, 1=top field, 2=bottom field | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_DMA_BLOCK_SIZE | ||
| Enum 8/0x08 | ||
| Description | ||
| Set DMA transfer block size. Counterpart to API 0xC9 | ||
| Param[0] | ||
| DMA transfer block size in bytes. A different size may be specified | ||
| when issuing the DMA transfer command. | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_GET_XFER_INFO | ||
| Enum 9/0x09 | ||
| Description | ||
| This API call may be used to detect an end of stream condtion. | ||
| Result[0] | ||
| Stream type | ||
| Result[1] | ||
| Address offset | ||
| Result[2] | ||
| Maximum bytes to transfer | ||
| Result[3] | ||
| Buffer fullness | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_GET_DMA_STATUS | ||
| Enum 10/0x0A | ||
| Description | ||
| Status of the last DMA transfer | ||
| Result[0] | ||
| Bit 1 set means transfer complete | ||
| Bit 2 set means DMA error | ||
| Bit 3 set means linked list error | ||
| Result[1] | ||
| DMA type: 0=MPEG, 1=OSD, 2=YUV | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SCHED_DMA_FROM_HOST | ||
| Enum 11/0x0B | ||
| Description | ||
| Setup DMA from host operation. Counterpart to API 0xCC | ||
| Param[0] | ||
| Memory address of link list | ||
| Param[1] | ||
| Total # of bytes to transfer | ||
| Param[2] | ||
| DMA type (0=MPEG, 1=OSD, 2=YUV) | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_PAUSE_PLAYBACK | ||
| Enum 13/0x0D | ||
| Description | ||
| Freeze playback immediately. In this mode, when internal buffers are | ||
| full, no more data will be accepted and data request IRQs will be | ||
| masked. | ||
| Param[0] | ||
| Display: 0=last frame, 1=black | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_HALT_FW | ||
| Enum 14/0x0E | ||
| Description | ||
| The firmware is halted and no further API calls are serviced until | ||
| the firmware is uploaded again. | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_STANDARD | ||
| Enum 16/0x10 | ||
| Description | ||
| Selects display standard | ||
| Param[0] | ||
| 0=NTSC, 1=PAL | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_GET_VERSION | ||
| Enum 17/0x11 | ||
| Description | ||
| Returns decoder firmware version information | ||
| Result[0] | ||
| Version bitmask: | ||
| Bits 0:15 build | ||
| Bits 16:23 minor | ||
| Bits 24:31 major | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_STREAM_INPUT | ||
| Enum 20/0x14 | ||
| Description | ||
| Select decoder stream input port | ||
| Param[0] | ||
| 0=memory (default), 1=streaming | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_GET_TIMING_INFO | ||
| Enum 21/0x15 | ||
| Description | ||
| Returns timing information from start of playback | ||
| Result[0] | ||
| Frame count by decode order | ||
| Result[1] | ||
| Video PTS bits 0:31 by display order | ||
| Result[2] | ||
| Video PTS bit 32 by display order | ||
| Result[3] | ||
| SCR bits 0:31 by display order | ||
| Result[4] | ||
| SCR bit 32 by display order | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_AUDIO_MODE | ||
| Enum 22/0x16 | ||
| Description | ||
| Select audio mode | ||
| Param[0] | ||
| Dual mono mode action | ||
| Param[1] | ||
| Stereo mode action: | ||
| 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_EVENT_NOTIFICATION | ||
| Enum 23/0x17 | ||
| Description | ||
| Setup firmware to notify the host about a particular event. | ||
| Counterpart to API 0xD5 | ||
| Param[0] | ||
| Event: 0=Audio mode change between stereo and dual channel | ||
| Param[1] | ||
| Notification 0=disabled, 1=enabled | ||
| Param[2] | ||
| Interrupt bit | ||
| Param[3] | ||
| Mailbox slot, -1 if no mailbox required. | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_DISPLAY_BUFFERS | ||
| Enum 24/0x18 | ||
| Description | ||
| Number of display buffers. To decode all frames in reverse playback you | ||
| must use nine buffers. | ||
| Param[0] | ||
| 0=six buffers, 1=nine buffers | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_EXTRACT_VBI | ||
| Enum 25/0x19 | ||
| Description | ||
| Extracts VBI data | ||
| Param[0] | ||
| 0=extract from extension & user data, 1=extract from private packets | ||
| Result[0] | ||
| VBI table location | ||
| Result[1] | ||
| VBI table size | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_DECODER_SOURCE | ||
| Enum 26/0x1A | ||
| Description | ||
| Selects decoder source. Ensure that the parameters passed to this | ||
| API match the encoder settings. | ||
| Param[0] | ||
| Mode: 0=MPEG from host, 1=YUV from encoder, 2=YUV from host | ||
| Param[1] | ||
| YUV picture width | ||
| Param[2] | ||
| YUV picture height | ||
| Param[3] | ||
| Bitmap: see Param[0] of API 0xBD | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_AUDIO_OUTPUT | ||
| Enum 27/0x1B | ||
| Description | ||
| Select audio output format | ||
| Param[0] | ||
| Bitmask: | ||
| 0:1 Data size: | ||
| '00' 16 bit | ||
| '01' 20 bit | ||
| '10' 24 bit | ||
| 2:7 Unused | ||
| 8:9 Mode: | ||
| '00' 2 channels | ||
| '01' 4 channels | ||
| '10' 6 channels | ||
| '11' 6 channels with one line data mode | ||
| (for left justified MSB first mode, 20 bit only) | ||
| 10:11 Unused | ||
| 12:13 Channel format: | ||
| '00' right justified MSB first mode | ||
| '01' left justified MSB first mode | ||
| '10' I2S mode | ||
| 14:15 Unused | ||
| 16:21 Right justify bit count | ||
| 22:31 Unused | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_AV_DELAY | ||
| Enum 28/0x1C | ||
| Description | ||
| Set audio/video delay in 90Khz ticks | ||
| Param[0] | ||
| 0=A/V in sync, negative=audio lags, positive=video lags | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
|
|
||
| Name CX2341X_DEC_SET_PREBUFFERING | ||
| Enum 30/0x1E | ||
| Description | ||
| Decoder prebuffering, when enabled up to 128KB are buffered for | ||
| streams <8mpbs or 640KB for streams >8mbps | ||
| Param[0] | ||
| 0=off, 1=on |
Oops, something went wrong.