1 files changed, 694 insertions, 0 deletions

diff --git a/Documentation/video4linux/cx2341x/fw-encoder-api.txt b/Documentation/video4linux/cx2341x/fw-encoder-api.txt
new file mode 100644
index 000000000000..001c68644b08
--- /dev/null
+++ b/Documentation/video4linux/cx2341x/fw-encoder-api.txt
@@ -0,0 +1,694 @@
+Encoder firmware API description
+================================
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_PING_FW
+Enum    128/0x80
+Description
+        Does nothing. Can be used to check if the firmware is responding.
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_START_CAPTURE
+Enum    129/0x81
+Description
+        Commences the capture of video, audio and/or VBI data. All encoding
+        parameters must be initialized prior to this API call. Captures frames
+        continuously or until a predefined number of frames have been captured.
+Param[0]
+        Capture stream type:
+            0=MPEG
+            1=Raw
+            2=Raw passthrough
+            3=VBI
+
+Param[1]
+        Bitmask:
+            Bit 0 when set, captures YUV
+            Bit 1 when set, captures PCM audio
+            Bit 2 when set, captures VBI (same as param[0]=3)
+            Bit 3 when set, the capture destination is the decoder
+                (same as param[0]=2)
+            Bit 4 when set, the capture destination is the host
+        Note: this parameter is only meaningful for RAW capture type.
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_STOP_CAPTURE
+Enum    130/0x82
+Description
+        Ends a capture in progress
+Param[0]
+        0=stop at end of GOP (generates IRQ)
+        1=stop immediate (no IRQ)
+Param[1]
+        Stream type to stop, see param[0] of API 0x81
+Param[2]
+        Subtype, see param[1] of API 0x81
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_AUDIO_ID
+Enum    137/0x89
+Description
+        Assigns the transport stream ID of the encoded audio stream
+Param[0]
+        Audio Stream ID
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_VIDEO_ID
+Enum    139/0x8B
+Description
+        Set video transport stream ID
+Param[0]
+        Video stream ID
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_PCR_ID
+Enum    141/0x8D
+Description
+        Assigns the transport stream ID for PCR packets
+Param[0]
+        PCR Stream ID
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_FRAME_RATE
+Enum    143/0x8F
+Description
+        Set video frames per second. Change occurs at start of new GOP.
+Param[0]
+        0=30fps
+        1=25fps
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_FRAME_SIZE
+Enum    145/0x91
+Description
+        Select video stream encoding resolution.
+Param[0]
+        Height in lines. Default 480
+Param[1]
+        Width in pixels. Default 720
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_BIT_RATE
+Enum    149/0x95
+Description
+        Assign average video stream bitrate. Note on the last three params:
+        Param[3] and [4] seem to be always 0, param [5] doesn't seem to be used.
+Param[0]
+        0=variable bitrate, 1=constant bitrate
+Param[1]
+        bitrate in bits per second
+Param[2]
+        peak bitrate in bits per second, divided by 400
+Param[3]
+        Mux bitrate in bits per second, divided by 400. May be 0 (default).
+Param[4]
+        Rate Control VBR Padding
+Param[5]
+        VBV Buffer used by encoder
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_GOP_PROPERTIES
+Enum    151/0x97
+Description
+        Setup the GOP structure
+Param[0]
+        GOP size (maximum is 34)
+Param[1]
+        Number of B frames between the I and P frame, plus 1.
+        For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3
+        Note that GOP size must be a multiple of (B-frames + 1).
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_ASPECT_RATIO
+Enum    153/0x99
+Description
+        Sets the encoding aspect ratio. Changes in the aspect ratio take effect
+        at the start of the next GOP.
+Param[0]
+        '0000' forbidden
+        '0001' 1:1 square
+        '0010' 4:3
+        '0011' 16:9
+        '0100' 2.21:1
+        '0101' reserved
+         ....
+        '1111' reserved
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_DNR_FILTER_MODE
+Enum    155/0x9B
+Description
+        Assign Dynamic Noise Reduction operating mode
+Param[0]
+        Bit0: Spatial filter, set=auto, clear=manual
+        Bit1: Temporal filter, set=auto, clear=manual
+Param[1]
+        Median filter:
+            0=Disabled
+            1=Horizontal
+            2=Vertical
+            3=Horiz/Vert
+            4=Diagonal
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_DNR_FILTER_PROPS
+Enum    157/0x9D
+Description
+        These Dynamic Noise Reduction filter values are only meaningful when
+        the respective filter is set to "manual" (See API 0x9B)
+Param[0]
+        Spatial filter: default 0, range 0:15
+Param[1]
+        Temporal filter: default 0, range 0:31
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_CORING_LEVELS
+Enum    159/0x9F
+Description
+        Assign Dynamic Noise Reduction median filter properties.
+Param[0]
+        Threshold above which the luminance median filter is enabled.
+        Default: 0, range 0:255
+Param[1]
+        Threshold below which the luminance median filter is enabled.
+        Default: 255, range 0:255
+Param[2]
+        Threshold above which the chrominance median filter is enabled.
+        Default: 0, range 0:255
+Param[3]
+        Threshold below which the chrominance median filter is enabled.
+        Default: 255, range 0:255
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_SPATIAL_FILTER_TYPE
+Enum    161/0xA1
+Description
+        Assign spatial prefilter parameters
+Param[0]
+        Luminance filter
+            0=Off
+            1=1D Horizontal
+            2=1D Vertical
+            3=2D H/V Separable (default)
+            4=2D Symmetric non-separable
+Param[1]
+        Chrominance filter
+            0=Off
+            1=1D Horizontal (default)
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_3_2_PULLDOWN
+Enum    177/0xB1
+Description
+        3:2 pulldown properties
+Param[0]
+        0=enabled
+        1=disabled
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_VBI_LINE
+Enum    183/0xB7
+Description
+        Selects VBI line number.
+Param[0]
+        Bits 0:4        line number
+        Bit  31         0=top_field, 1=bottom_field
+        Bits 0:31       all set specifies "all lines"
+Param[1]
+        VBI line information features: 0=disabled, 1=enabled
+Param[2]
+        Slicing: 0=None, 1=Closed Caption
+        Almost certainly not implemented. Set to 0.
+Param[3]
+        Luminance samples in this line.
+        Almost certainly not implemented. Set to 0.
+Param[4]
+        Chrominance samples in this line
+        Almost certainly not implemented. Set to 0.
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_STREAM_TYPE
+Enum    185/0xB9
+Description
+        Assign stream type
+        Note: Transport stream is not working in recent firmwares.
+        And in older firmwares the timestamps in the TS seem to be
+        unreliable.
+Param[0]
+         0=Program stream
+         1=Transport stream
+         2=MPEG1 stream
+         3=PES A/V stream
+         5=PES Video stream
+         7=PES Audio stream
+        10=DVD stream
+        11=VCD stream
+        12=SVCD stream
+        13=DVD_S1 stream
+        14=DVD_S2 stream
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_OUTPUT_PORT
+Enum    187/0xBB
+Description
+        Assign stream output port. Normally 0 when the data is copied through
+        the PCI bus (DMA), and 1 when the data is streamed to another chip
+        (pvrusb and cx88-blackbird).
+Param[0]
+        0=Memory (default)
+        1=Streaming
+        2=Serial
+Param[1]
+        Unknown, but leaving this to 0 seems to work best. Indications are that
+        this might have to do with USB support, although passing anything but 0
+        onl breaks things.
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_AUDIO_PROPERTIES
+Enum    189/0xBD
+Description
+        Set audio stream properties, may be called while encoding is in progress.
+        Note: all bitfields are consistent with ISO11172 documentation except
+        bits 2:3 which ISO docs define as:
+                '11' Layer I
+                '10' Layer II
+                '01' Layer III
+                '00' Undefined
+        This discrepancy may indicate a possible error in the documentation.
+        Testing indicated that only Layer II is actually working, and that
+        the minimum bitrate should be 192 kbps.
+Param[0]
+        Bitmask:
+           0:1  '00' 44.1Khz
+                '01' 48Khz
+                '10' 32Khz
+                '11' reserved
+
+           2:3  '01'=Layer I
+                '10'=Layer II
+
+           4:7  Bitrate:
+                     Index | Layer I     | Layer II
+                     ------+-------------+------------
+                    '0000' | free format | free format
+                    '0001' |  32 kbit/s  |  32 kbit/s
+                    '0010' |  64 kbit/s  |  48 kbit/s
+                    '0011' |  96 kbit/s  |  56 kbit/s
+                    '0100' | 128 kbit/s  |  64 kbit/s
+                    '0101' | 160 kbit/s  |  80 kbit/s
+                    '0110' | 192 kbit/s  |  96 kbit/s
+                    '0111' | 224 kbit/s  | 112 kbit/s
+                    '1000' | 256 kbit/s  | 128 kbit/s
+                    '1001' | 288 kbit/s  | 160 kbit/s
+                    '1010' | 320 kbit/s  | 192 kbit/s
+                    '1011' | 352 kbit/s  | 224 kbit/s
+                    '1100' | 384 kbit/s  | 256 kbit/s
+                    '1101' | 416 kbit/s  | 320 kbit/s
+                    '1110' | 448 kbit/s  | 384 kbit/s
+                Note: For Layer II, not all combinations of total bitrate
+                and mode are allowed. See ISO11172-3 3-Annex B, Table 3-B.2
+
+           8:9  '00'=Stereo
+                '01'=JointStereo
+                '10'=Dual
+                '11'=Mono
+                Note: testing seems to indicate that Mono and possibly
+                JointStereo are not working (default to stereo).
+                Dual does work, though.
+
+          10:11 Mode Extension used in joint_stereo mode.
+                In Layer I and II they indicate which subbands are in
+                intensity_stereo. All other subbands are coded in stereo.
+                    '00' subbands 4-31 in intensity_stereo, bound==4
+                    '01' subbands 8-31 in intensity_stereo, bound==8
+                    '10' subbands 12-31 in intensity_stereo, bound==12
+                    '11' subbands 16-31 in intensity_stereo, bound==16
+
+          12:13 Emphasis:
+                    '00' None
+                    '01' 50/15uS
+                    '10' reserved
+                    '11' CCITT J.17
+
+          14    CRC:
+                    '0' off
+                    '1' on
+
+          15    Copyright:
+                    '0' off
+                    '1' on
+
+          16    Generation:
+                    '0' copy
+                    '1' original
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_HALT_FW
+Enum    195/0xC3
+Description
+        The firmware is halted and no further API calls are serviced until the
+        firmware is uploaded again.
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_GET_VERSION
+Enum    196/0xC4
+Description
+        Returns the version of the encoder firmware.
+Result[0]
+        Version bitmask:
+            Bits  0:15 build
+            Bits 16:23 minor
+            Bits 24:31 major
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_GOP_CLOSURE
+Enum    197/0xC5
+Description
+        Assigns the GOP open/close property.
+Param[0]
+        0=Open
+        1=Closed
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_GET_SEQ_END
+Enum    198/0xC6
+Description
+        Obtains the sequence end code of the encoder's buffer. When a capture
+        is started a number of interrupts are still generated, the last of
+        which will have Result[0] set to 1 and Result[1] will contain the size
+        of the buffer.
+Result[0]
+        State of the transfer (1 if last buffer)
+Result[1]
+        If Result[0] is 1, this contains the size of the last buffer, undefined
+        otherwise.
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_PGM_INDEX_INFO
+Enum    199/0xC7
+Description
+        Sets the Program Index Information.
+Param[0]
+        Picture Mask:
+            0=No index capture
+            1=I frames
+            3=I,P frames
+            7=I,P,B frames
+Param[1]
+        Elements requested (up to 400)
+Result[0]
+        Offset in SDF memory of the table.
+Result[1]
+        Number of allocated elements up to a maximum of Param[1]
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_VBI_CONFIG
+Enum    200/0xC8
+Description
+        Configure VBI settings
+Param[0]
+        Bitmap:
+            0    Mode '0' Sliced, '1' Raw
+            1:3  Insertion:
+                     '000' insert in extension & user data
+                     '001' insert in private packets
+                     '010' separate stream and user data
+                     '111' separate stream and private data
+            8:15 Stream ID (normally 0xBD)
+Param[1]
+        Frames per interrupt (max 8). Only valid in raw mode.
+Param[2]
+        Total raw VBI frames. Only valid in raw mode.
+Param[3]
+        Start codes
+Param[4]
+        Stop codes
+Param[5]
+        Lines per frame
+Param[6]
+        Byte per line
+Result[0]
+        Observed frames per interrupt in raw mode only. Rage 1 to Param[1]
+Result[1]
+        Observed number of frames in raw mode. Range 1 to Param[2]
+Result[2]
+        Memory offset to start or raw VBI data
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_DMA_BLOCK_SIZE
+Enum    201/0xC9
+Description
+        Set DMA transfer block size
+Param[0]
+        DMA transfer block size in bytes or frames. When unit is bytes,
+        supported block sizes are 2^7, 2^8 and 2^9 bytes.
+Param[1]
+        Unit: 0=bytes, 1=frames
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
+Enum    202/0xCA
+Description
+        Returns information on the previous DMA transfer in conjunction with
+        bit 27 of the interrupt mask. Uses mailbox 10.
+Result[0]
+        Type of stream
+Result[1]
+        Address Offset
+Result[2]
+        Maximum size of transfer
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
+Enum    203/0xCB
+Description
+        Returns information on the previous DMA transfer in conjunction with
+        bit 27 of the interrupt mask. Uses mailbox 9.
+Result[0]
+        Status bits:
+            Bit 0 set indicates transfer complete
+            Bit 2 set indicates transfer error
+            Bit 4 set indicates linked list error
+Result[1]
+        DMA type
+Result[2]
+        Presentation Time Stamp bits 0..31
+Result[3]
+        Presentation Time Stamp bit 32
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SCHED_DMA_TO_HOST
+Enum    204/0xCC
+Description
+        Setup DMA to host operation
+Param[0]
+        Memory address of link list
+Param[1]
+        Length of link list (wtf: what units ???)
+Param[2]
+        DMA type (0=MPEG)
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_INITIALIZE_INPUT
+Enum    205/0xCD
+Description
+        Initializes the video input
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_FRAME_DROP_RATE
+Enum    208/0xD0
+Description
+        For each frame captured, skip specified number of frames.
+Param[0]
+        Number of frames to skip
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_PAUSE_ENCODER
+Enum    210/0xD2
+Description
+        During a pause condition, all frames are dropped instead of being encoded.
+Param[0]
+        0=Pause encoding
+        1=Continue encoding
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_REFRESH_INPUT
+Enum    211/0xD3
+Description
+        Refreshes the video input
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_COPYRIGHT
+Enum    212/0xD4
+Description
+        Sets stream copyright property
+Param[0]
+        0=Stream is not copyrighted
+        1=Stream is copyrighted
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_EVENT_NOTIFICATION
+Enum    213/0xD5
+Description
+        Setup firmware to notify the host about a particular event. Host must
+        unmask the interrupt bit.
+Param[0]
+        Event (0=refresh encoder input)
+Param[1]
+        Notification 0=disabled 1=enabled
+Param[2]
+        Interrupt bit
+Param[3]
+        Mailbox slot, -1 if no mailbox required.
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_NUM_VSYNC_LINES
+Enum    214/0xD6
+Description
+        Depending on the analog video decoder used, this assigns the number
+        of lines for field 1 and 2.
+Param[0]
+        Field 1 number of lines:
+            0x00EF for SAA7114
+            0x00F0 for SAA7115
+            0x0105 for Micronas
+Param[1]
+        Field 2 number of lines:
+            0x00EF for SAA7114
+            0x00F0 for SAA7115
+            0x0106 for Micronas
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_SET_PLACEHOLDER
+Enum    215/0xD7
+Description
+        Provides a mechanism of inserting custom user data in the MPEG stream.
+Param[0]
+        0=extension & user data
+        1=private packet with stream ID 0xBD
+Param[1]
+        Rate at which to insert data, in units of frames (for private packet)
+        or GOPs (for ext. & user data)
+Param[2]
+        Number of data DWORDs (below) to insert
+Param[3]
+        Custom data 0
+Param[4]
+        Custom data 1
+Param[5]
+        Custom data 2
+Param[6]
+        Custom data 3
+Param[7]
+        Custom data 4
+Param[8]
+        Custom data 5
+Param[9]
+        Custom data 6
+Param[10]
+        Custom data 7
+Param[11]
+        Custom data 8
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_MUTE_VIDEO
+Enum    217/0xD9
+Description
+        Video muting
+Param[0]
+        Bit usage:
+         0      '0'=video not muted
+                '1'=video muted, creates frames with the YUV color defined below
+         1:7    Unused
+         8:15   V chrominance information
+        16:23   U chrominance information
+        24:31   Y luminance information
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_MUTE_AUDIO
+Enum    218/0xDA
+Description
+        Audio muting
+Param[0]
+        0=audio not muted
+        1=audio muted (produces silent mpeg audio stream)
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_UNKNOWN
+Enum    219/0xDB
+Description
+        Unknown API, it's used by Hauppauge though.
+Param[0]
+        0 This is the value Hauppauge uses, Unknown what it means.
+
+-------------------------------------------------------------------------------
+
+Name    CX2341X_ENC_MISC
+Enum    220/0xDC
+Description
+        Miscellaneous actions. Not known for 100% what it does. It's really a
+        sort of ioctl call. The first parameter is a command number, the second
+        the value.
+Param[0]
+        Command number:
+         1=set initial SCR value when starting encoding.
+         2=set quality mode (apparently some test setting).
+         3=setup advanced VIM protection handling (supposedly only for the cx23416
+           for raw YUV).
+           Actually it looks like this should be 0 for saa7114/5 based card and 1
+           for cx25840 based cards.
+         4=generate artificial PTS timestamps
+         5=USB flush mode
+         6=something to do with the quantization matrix
+         7=set navigation pack insertion for DVD
+         8=enable scene change detection (seems to be a failure)
+         9=set history parameters of the video input module
+        10=set input field order of VIM
+        11=set quantization matrix
+        12=reset audio interface
+        13=set audio volume delay
+        14=set audio delay
+
+Param[1]
+        Command value.