1 files changed, 319 insertions, 0 deletions

diff --git a/Documentation/video4linux/cx2341x/fw-decoder-api.txt b/Documentation/video4linux/cx2341x/fw-decoder-api.txt
new file mode 100644
index 000000000000..59193b6b5572
--- /dev/null
+++ b/Documentation/video4linux/cx2341x/fw-decoder-api.txt
@@ -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