V4L/DVB (3809b): Added missing docs at kernel tree
Date:
From: Mauro Carvalho Chehab <mchehab@infradead.org>
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 <mchehab@infradead.org>
diff --git a/Documentation/video4linux/cx2341x/fw-encoder-api.txt b/Documentation/video4linux/cx2341x/fw-encoder-api.txt
new file mode 100644
index 0000000..64cd111
--- /dev/null
+++ b/Documentation/video4linux/cx2341x/fw-encoder-api.txt
@@ -0,0 +1,672 @@
+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.
+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
+
+-------------------------------------------------------------------------------
+
+Name CX2341X_ENC_SET_GOP_PROPERTIES
+Enum 151/0x97
+Description
+ Setup the GOP structure
+Param[0]
+ GOP size
+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
+
+-------------------------------------------------------------------------------
+
+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
+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 (not recommended you change setting from default)
+Param[0]
+ 0=Memory (default)
+ 1=Streaming
+ 2=Serial
+
+-------------------------------------------------------------------------------
+
+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.
+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
+
+ 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.