move the contents of fw-decoder-api.txt to cx2341x and convert it to ReST file, adding it to media/v4l-drivers Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> --- Documentation/media/v4l-drivers/cx2341x.rst | 564 +++++++++++++++++++++ Documentation/media/v4l-drivers/index.rst | 1 + .../video4linux/cx2341x/fw-decoder-api.txt | 297 ----------- 3 files changed, 565 insertions(+), 297 deletions(-) create mode 100644 Documentation/media/v4l-drivers/cx2341x.rst delete mode 100644 Documentation/video4linux/cx2341x/fw-decoder-api.txt diff --git a/Documentation/media/v4l-drivers/cx2341x.rst b/Documentation/media/v4l-drivers/cx2341x.rst new file mode 100644 index 000000000000..6f4ac07f52cd --- /dev/null +++ b/Documentation/media/v4l-drivers/cx2341x.rst @@ -0,0 +1,564 @@ +The cx2341x driver +================== + +Decoder firmware API description +-------------------------------- + +.. note:: this API is part of the decoder firmware, so it's cx23415 only. + + + +CX2341X_DEC_PING_FW +------------------- + +Enum: 0/0x00 + +Description +~~~~~~~~~~~ + +This API call does nothing. It may be used to check if the firmware +is responding. + + + +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. (This is not implemented in the firmware, leave at 0) + + + +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 + +.. note:: + + this takes effect immediately, so if you want to wait for a PTS, + then use '0', otherwise the screen goes to black at once. + You can call this later (even if there is no playback) with a 1 value + to set the screen to black. + +Param[1] +~~~~~~~~ + +PTS low + +Param[2] +~~~~~~~~ + +PTS high + + + +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] +~~~~~~~~ + +.. code-block:: none + + 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 + +.. note:: + + n is limited to 2. Anything higher does not result in + faster playback. Instead the host should start dropping frames. + +Param[1] +~~~~~~~~ + +Direction: 0=forward, 1=reverse + +.. note:: + + to make reverse playback work you have to write full GOPs in + reverse order. + +Param[2] +~~~~~~~~ + +.. code-block:: none + + Picture mask: + 1=I frames + 3=I, P frames + 7=I, P, B frames + +Param[3] +~~~~~~~~ + +B frames per GOP (for reverse play only) + +.. note:: + + for reverse playback the Picture Mask should be set to I or I, P. + Adding B frames to the mask will result in corrupt video. This field + has to be set to the correct value in order to keep the timing correct. + +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. (Not implemented in the firmware, leave at 0) + + + +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 + + + +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. + + + +CX2341X_DEC_GET_XFER_INFO +------------------------- + +Enum: 9/0x09 + +Description +~~~~~~~~~~~ + +This API call may be used to detect an end of stream condition. + +Result[0] +~~~~~~~~~ + +Stream type + +Result[1] +~~~~~~~~~ + +Address offset + +Result[2] +~~~~~~~~~ + +Maximum bytes to transfer + +Result[3] +~~~~~~~~~ + +Buffer fullness + + + +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 + + + +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) + + + +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 + + + +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. + + + +CX2341X_DEC_SET_STANDARD +------------------------ + +Enum: 16/0x10 + +Description +~~~~~~~~~~~ + +Selects display standard + +Param[0] +~~~~~~~~ + +0=NTSC, 1=PAL + + + +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 + + + +CX2341X_DEC_SET_STREAM_INPUT +---------------------------- + +Enum: 20/0x14 + +Description +~~~~~~~~~~~ + +Select decoder stream input port + +Param[0] +~~~~~~~~ + +0=memory (default), 1=streaming + + + +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 + + + +CX2341X_DEC_SET_AUDIO_MODE +-------------------------- + +Enum: 22/0x16 + +Description +~~~~~~~~~~~ + +Select audio mode + +Param[0] +~~~~~~~~ + +Dual mono mode action + 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged + +Param[1] +~~~~~~~~ + +Stereo mode action: + 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged + + + +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 mono, (joint) stereo and dual channel. + - 3=Decoder started + - 4=Unknown: goes off 10-15 times per second while decoding. + - 5=Some sync event: goes off once per frame. + +Param[1] +~~~~~~~~ + +Notification 0=disabled, 1=enabled + +Param[2] +~~~~~~~~ + +Interrupt bit + +Param[3] +~~~~~~~~ + +Mailbox slot, -1 if no mailbox required. + + + +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 + + + +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 + + + +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 + + + +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 diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 53bc53c948ab..34990b536d39 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -27,6 +27,7 @@ License". cafe_ccic cpia2 cx18 + cx2341x cx88 davinci-vpbe fimc diff --git a/Documentation/video4linux/cx2341x/fw-decoder-api.txt b/Documentation/video4linux/cx2341x/fw-decoder-api.txt deleted file mode 100644 index 8c317b7a4fc9..000000000000 --- a/Documentation/video4linux/cx2341x/fw-decoder-api.txt +++ /dev/null @@ -1,297 +0,0 @@ -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. (This is not implemented in the firmware, leave at 0) - -------------------------------------------------------------------------------- - -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 - Note: this takes effect immediately, so if you want to wait for a PTS, - then use '0', otherwise the screen goes to black at once. - You can call this later (even if there is no playback) with a 1 value - to set the screen to 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 - Note: n is limited to 2. Anything higher does not result in - faster playback. Instead the host should start dropping frames. -Param[1] - Direction: 0=forward, 1=reverse - Note: to make reverse playback work you have to write full GOPs in - reverse order. -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) - Note: for reverse playback the Picture Mask should be set to I or I, P. - Adding B frames to the mask will result in corrupt video. This field - has to be set to the correct value in order to keep the timing correct. -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. (Not implemented in the firmware, leave at 0) - -------------------------------------------------------------------------------- - -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 condition. -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 - 0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged -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 mono, (joint) stereo and dual channel. - Event: 3=Decoder started - Event: 4=Unknown: goes off 10-15 times per second while decoding. - Event: 5=Some sync event: goes off once per frame. -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_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 -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
