Check-in of baseline 2.6.34 tree
[linux-2.6.34-lpc32xx.git] / Documentation / video4linux / cx2341x / fw-encoder-api.txt
1 Encoder firmware API description
2 ================================
3
4 -------------------------------------------------------------------------------
5
6 Name    CX2341X_ENC_PING_FW
7 Enum    128/0x80
8 Description
9         Does nothing. Can be used to check if the firmware is responding.
10
11 -------------------------------------------------------------------------------
12
13 Name    CX2341X_ENC_START_CAPTURE
14 Enum    129/0x81
15 Description
16         Commences the capture of video, audio and/or VBI data. All encoding
17         parameters must be initialized prior to this API call. Captures frames
18         continuously or until a predefined number of frames have been captured.
19 Param[0]
20         Capture stream type:
21             0=MPEG
22             1=Raw
23             2=Raw passthrough
24             3=VBI
25
26 Param[1]
27         Bitmask:
28             Bit 0 when set, captures YUV
29             Bit 1 when set, captures PCM audio
30             Bit 2 when set, captures VBI (same as param[0]=3)
31             Bit 3 when set, the capture destination is the decoder
32                 (same as param[0]=2)
33             Bit 4 when set, the capture destination is the host
34         Note: this parameter is only meaningful for RAW capture type.
35
36 -------------------------------------------------------------------------------
37
38 Name    CX2341X_ENC_STOP_CAPTURE
39 Enum    130/0x82
40 Description
41         Ends a capture in progress
42 Param[0]
43         0=stop at end of GOP (generates IRQ)
44         1=stop immediate (no IRQ)
45 Param[1]
46         Stream type to stop, see param[0] of API 0x81
47 Param[2]
48         Subtype, see param[1] of API 0x81
49
50 -------------------------------------------------------------------------------
51
52 Name    CX2341X_ENC_SET_AUDIO_ID
53 Enum    137/0x89
54 Description
55         Assigns the transport stream ID of the encoded audio stream
56 Param[0]
57         Audio Stream ID
58
59 -------------------------------------------------------------------------------
60
61 Name    CX2341X_ENC_SET_VIDEO_ID
62 Enum    139/0x8B
63 Description
64         Set video transport stream ID
65 Param[0]
66         Video stream ID
67
68 -------------------------------------------------------------------------------
69
70 Name    CX2341X_ENC_SET_PCR_ID
71 Enum    141/0x8D
72 Description
73         Assigns the transport stream ID for PCR packets
74 Param[0]
75         PCR Stream ID
76
77 -------------------------------------------------------------------------------
78
79 Name    CX2341X_ENC_SET_FRAME_RATE
80 Enum    143/0x8F
81 Description
82         Set video frames per second. Change occurs at start of new GOP.
83 Param[0]
84         0=30fps
85         1=25fps
86
87 -------------------------------------------------------------------------------
88
89 Name    CX2341X_ENC_SET_FRAME_SIZE
90 Enum    145/0x91
91 Description
92         Select video stream encoding resolution.
93 Param[0]
94         Height in lines. Default 480
95 Param[1]
96         Width in pixels. Default 720
97
98 -------------------------------------------------------------------------------
99
100 Name    CX2341X_ENC_SET_BIT_RATE
101 Enum    149/0x95
102 Description
103         Assign average video stream bitrate. Note on the last three params:
104         Param[3] and [4] seem to be always 0, param [5] doesn't seem to be used.
105 Param[0]
106         0=variable bitrate, 1=constant bitrate
107 Param[1]
108         bitrate in bits per second
109 Param[2]
110         peak bitrate in bits per second, divided by 400
111 Param[3]
112         Mux bitrate in bits per second, divided by 400. May be 0 (default).
113 Param[4]
114         Rate Control VBR Padding
115 Param[5]
116         VBV Buffer used by encoder
117
118 -------------------------------------------------------------------------------
119
120 Name    CX2341X_ENC_SET_GOP_PROPERTIES
121 Enum    151/0x97
122 Description
123         Setup the GOP structure
124 Param[0]
125         GOP size (maximum is 34)
126 Param[1]
127         Number of B frames between the I and P frame, plus 1.
128         For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3
129         Note that GOP size must be a multiple of (B-frames + 1).
130
131 -------------------------------------------------------------------------------
132
133 Name    CX2341X_ENC_SET_ASPECT_RATIO
134 Enum    153/0x99
135 Description
136         Sets the encoding aspect ratio. Changes in the aspect ratio take effect
137         at the start of the next GOP.
138 Param[0]
139         '0000' forbidden
140         '0001' 1:1 square
141         '0010' 4:3
142         '0011' 16:9
143         '0100' 2.21:1
144         '0101' reserved
145          ....
146         '1111' reserved
147
148 -------------------------------------------------------------------------------
149
150 Name    CX2341X_ENC_SET_DNR_FILTER_MODE
151 Enum    155/0x9B
152 Description
153         Assign Dynamic Noise Reduction operating mode
154 Param[0]
155         Bit0: Spatial filter, set=auto, clear=manual
156         Bit1: Temporal filter, set=auto, clear=manual
157 Param[1]
158         Median filter:
159             0=Disabled
160             1=Horizontal
161             2=Vertical
162             3=Horiz/Vert
163             4=Diagonal
164
165 -------------------------------------------------------------------------------
166
167 Name    CX2341X_ENC_SET_DNR_FILTER_PROPS
168 Enum    157/0x9D
169 Description
170         These Dynamic Noise Reduction filter values are only meaningful when
171         the respective filter is set to "manual" (See API 0x9B)
172 Param[0]
173         Spatial filter: default 0, range 0:15
174 Param[1]
175         Temporal filter: default 0, range 0:31
176
177 -------------------------------------------------------------------------------
178
179 Name    CX2341X_ENC_SET_CORING_LEVELS
180 Enum    159/0x9F
181 Description
182         Assign Dynamic Noise Reduction median filter properties.
183 Param[0]
184         Threshold above which the luminance median filter is enabled.
185         Default: 0, range 0:255
186 Param[1]
187         Threshold below which the luminance median filter is enabled.
188         Default: 255, range 0:255
189 Param[2]
190         Threshold above which the chrominance median filter is enabled.
191         Default: 0, range 0:255
192 Param[3]
193         Threshold below which the chrominance median filter is enabled.
194         Default: 255, range 0:255
195
196 -------------------------------------------------------------------------------
197
198 Name    CX2341X_ENC_SET_SPATIAL_FILTER_TYPE
199 Enum    161/0xA1
200 Description
201         Assign spatial prefilter parameters
202 Param[0]
203         Luminance filter
204             0=Off
205             1=1D Horizontal
206             2=1D Vertical
207             3=2D H/V Separable (default)
208             4=2D Symmetric non-separable
209 Param[1]
210         Chrominance filter
211             0=Off
212             1=1D Horizontal (default)
213
214 -------------------------------------------------------------------------------
215
216 Name    CX2341X_ENC_SET_VBI_LINE
217 Enum    183/0xB7
218 Description
219         Selects VBI line number.
220 Param[0]
221         Bits 0:4        line number
222         Bit  31         0=top_field, 1=bottom_field
223         Bits 0:31       all set specifies "all lines"
224 Param[1]
225         VBI line information features: 0=disabled, 1=enabled
226 Param[2]
227         Slicing: 0=None, 1=Closed Caption
228         Almost certainly not implemented. Set to 0.
229 Param[3]
230         Luminance samples in this line.
231         Almost certainly not implemented. Set to 0.
232 Param[4]
233         Chrominance samples in this line
234         Almost certainly not implemented. Set to 0.
235
236 -------------------------------------------------------------------------------
237
238 Name    CX2341X_ENC_SET_STREAM_TYPE
239 Enum    185/0xB9
240 Description
241         Assign stream type
242         Note: Transport stream is not working in recent firmwares.
243         And in older firmwares the timestamps in the TS seem to be
244         unreliable.
245 Param[0]
246          0=Program stream
247          1=Transport stream
248          2=MPEG1 stream
249          3=PES A/V stream
250          5=PES Video stream
251          7=PES Audio stream
252         10=DVD stream
253         11=VCD stream
254         12=SVCD stream
255         13=DVD_S1 stream
256         14=DVD_S2 stream
257
258 -------------------------------------------------------------------------------
259
260 Name    CX2341X_ENC_SET_OUTPUT_PORT
261 Enum    187/0xBB
262 Description
263         Assign stream output port. Normally 0 when the data is copied through
264         the PCI bus (DMA), and 1 when the data is streamed to another chip
265         (pvrusb and cx88-blackbird).
266 Param[0]
267         0=Memory (default)
268         1=Streaming
269         2=Serial
270 Param[1]
271         Unknown, but leaving this to 0 seems to work best. Indications are that
272         this might have to do with USB support, although passing anything but 0
273         only breaks things.
274
275 -------------------------------------------------------------------------------
276
277 Name    CX2341X_ENC_SET_AUDIO_PROPERTIES
278 Enum    189/0xBD
279 Description
280         Set audio stream properties, may be called while encoding is in progress.
281         Note: all bitfields are consistent with ISO11172 documentation except
282         bits 2:3 which ISO docs define as:
283                 '11' Layer I
284                 '10' Layer II
285                 '01' Layer III
286                 '00' Undefined
287         This discrepancy may indicate a possible error in the documentation.
288         Testing indicated that only Layer II is actually working, and that
289         the minimum bitrate should be 192 kbps.
290 Param[0]
291         Bitmask:
292            0:1  '00' 44.1Khz
293                 '01' 48Khz
294                 '10' 32Khz
295                 '11' reserved
296
297            2:3  '01'=Layer I
298                 '10'=Layer II
299
300            4:7  Bitrate:
301                      Index | Layer I     | Layer II
302                      ------+-------------+------------
303                     '0000' | free format | free format
304                     '0001' |  32 kbit/s  |  32 kbit/s
305                     '0010' |  64 kbit/s  |  48 kbit/s
306                     '0011' |  96 kbit/s  |  56 kbit/s
307                     '0100' | 128 kbit/s  |  64 kbit/s
308                     '0101' | 160 kbit/s  |  80 kbit/s
309                     '0110' | 192 kbit/s  |  96 kbit/s
310                     '0111' | 224 kbit/s  | 112 kbit/s
311                     '1000' | 256 kbit/s  | 128 kbit/s
312                     '1001' | 288 kbit/s  | 160 kbit/s
313                     '1010' | 320 kbit/s  | 192 kbit/s
314                     '1011' | 352 kbit/s  | 224 kbit/s
315                     '1100' | 384 kbit/s  | 256 kbit/s
316                     '1101' | 416 kbit/s  | 320 kbit/s
317                     '1110' | 448 kbit/s  | 384 kbit/s
318                 Note: For Layer II, not all combinations of total bitrate
319                 and mode are allowed. See ISO11172-3 3-Annex B, Table 3-B.2
320
321            8:9  '00'=Stereo
322                 '01'=JointStereo
323                 '10'=Dual
324                 '11'=Mono
325                 Note: the cx23415 cannot decode Joint Stereo properly.
326
327           10:11 Mode Extension used in joint_stereo mode.
328                 In Layer I and II they indicate which subbands are in
329                 intensity_stereo. All other subbands are coded in stereo.
330                     '00' subbands 4-31 in intensity_stereo, bound==4
331                     '01' subbands 8-31 in intensity_stereo, bound==8
332                     '10' subbands 12-31 in intensity_stereo, bound==12
333                     '11' subbands 16-31 in intensity_stereo, bound==16
334
335           12:13 Emphasis:
336                     '00' None
337                     '01' 50/15uS
338                     '10' reserved
339                     '11' CCITT J.17
340
341           14    CRC:
342                     '0' off
343                     '1' on
344
345           15    Copyright:
346                     '0' off
347                     '1' on
348
349           16    Generation:
350                     '0' copy
351                     '1' original
352
353 -------------------------------------------------------------------------------
354
355 Name    CX2341X_ENC_HALT_FW
356 Enum    195/0xC3
357 Description
358         The firmware is halted and no further API calls are serviced until the
359         firmware is uploaded again.
360
361 -------------------------------------------------------------------------------
362
363 Name    CX2341X_ENC_GET_VERSION
364 Enum    196/0xC4
365 Description
366         Returns the version of the encoder firmware.
367 Result[0]
368         Version bitmask:
369             Bits  0:15 build
370             Bits 16:23 minor
371             Bits 24:31 major
372
373 -------------------------------------------------------------------------------
374
375 Name    CX2341X_ENC_SET_GOP_CLOSURE
376 Enum    197/0xC5
377 Description
378         Assigns the GOP open/close property.
379 Param[0]
380         0=Open
381         1=Closed
382
383 -------------------------------------------------------------------------------
384
385 Name    CX2341X_ENC_GET_SEQ_END
386 Enum    198/0xC6
387 Description
388         Obtains the sequence end code of the encoder's buffer. When a capture
389         is started a number of interrupts are still generated, the last of
390         which will have Result[0] set to 1 and Result[1] will contain the size
391         of the buffer.
392 Result[0]
393         State of the transfer (1 if last buffer)
394 Result[1]
395         If Result[0] is 1, this contains the size of the last buffer, undefined
396         otherwise.
397
398 -------------------------------------------------------------------------------
399
400 Name    CX2341X_ENC_SET_PGM_INDEX_INFO
401 Enum    199/0xC7
402 Description
403         Sets the Program Index Information.
404         The information is stored as follows:
405
406         struct info {
407                 u32 length;             // Length of this frame
408                 u32 offset_low;         // Offset in the file of the
409                 u32 offset_high;        // start of this frame
410                 u32 mask1;              // Bits 0-2 are the type mask:
411                                         // 1=I, 2=P, 4=B
412                                         // 0=End of Program Index, other fields
413                                         //   are invalid.
414                 u32 pts;                // The PTS of the frame
415                 u32 mask2;              // Bit 0 is bit 32 of the pts.
416         };
417         u32 table_ptr;
418         struct info index[400];
419
420         The table_ptr is the encoder memory address in the table were
421         *new* entries will be written. Note that this is a ringbuffer,
422         so the table_ptr will wraparound.
423 Param[0]
424         Picture Mask:
425             0=No index capture
426             1=I frames
427             3=I,P frames
428             7=I,P,B frames
429         (Seems to be ignored, it always indexes I, P and B frames)
430 Param[1]
431         Elements requested (up to 400)
432 Result[0]
433         Offset in the encoder memory of the start of the table.
434 Result[1]
435         Number of allocated elements up to a maximum of Param[1]
436
437 -------------------------------------------------------------------------------
438
439 Name    CX2341X_ENC_SET_VBI_CONFIG
440 Enum    200/0xC8
441 Description
442         Configure VBI settings
443 Param[0]
444         Bitmap:
445             0    Mode '0' Sliced, '1' Raw
446             1:3  Insertion:
447                      '000' insert in extension & user data
448                      '001' insert in private packets
449                      '010' separate stream and user data
450                      '111' separate stream and private data
451             8:15 Stream ID (normally 0xBD)
452 Param[1]
453         Frames per interrupt (max 8). Only valid in raw mode.
454 Param[2]
455         Total raw VBI frames. Only valid in raw mode.
456 Param[3]
457         Start codes
458 Param[4]
459         Stop codes
460 Param[5]
461         Lines per frame
462 Param[6]
463         Byte per line
464 Result[0]
465         Observed frames per interrupt in raw mode only. Rage 1 to Param[1]
466 Result[1]
467         Observed number of frames in raw mode. Range 1 to Param[2]
468 Result[2]
469         Memory offset to start or raw VBI data
470
471 -------------------------------------------------------------------------------
472
473 Name    CX2341X_ENC_SET_DMA_BLOCK_SIZE
474 Enum    201/0xC9
475 Description
476         Set DMA transfer block size
477 Param[0]
478         DMA transfer block size in bytes or frames. When unit is bytes,
479         supported block sizes are 2^7, 2^8 and 2^9 bytes.
480 Param[1]
481         Unit: 0=bytes, 1=frames
482
483 -------------------------------------------------------------------------------
484
485 Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
486 Enum    202/0xCA
487 Description
488         Returns information on the previous DMA transfer in conjunction with
489         bit 27 of the interrupt mask. Uses mailbox 10.
490 Result[0]
491         Type of stream
492 Result[1]
493         Address Offset
494 Result[2]
495         Maximum size of transfer
496
497 -------------------------------------------------------------------------------
498
499 Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
500 Enum    203/0xCB
501 Description
502         Returns information on the previous DMA transfer in conjunction with
503         bit 27 or 18 of the interrupt mask. Uses mailbox 9.
504 Result[0]
505         Status bits:
506                 0   read completed
507                 1   write completed
508                 2   DMA read error
509                 3   DMA write error
510                 4   Scatter-Gather array error
511 Result[1]
512         DMA type
513 Result[2]
514         Presentation Time Stamp bits 0..31
515 Result[3]
516         Presentation Time Stamp bit 32
517
518 -------------------------------------------------------------------------------
519
520 Name    CX2341X_ENC_SCHED_DMA_TO_HOST
521 Enum    204/0xCC
522 Description
523         Setup DMA to host operation
524 Param[0]
525         Memory address of link list
526 Param[1]
527         Length of link list (wtf: what units ???)
528 Param[2]
529         DMA type (0=MPEG)
530
531 -------------------------------------------------------------------------------
532
533 Name    CX2341X_ENC_INITIALIZE_INPUT
534 Enum    205/0xCD
535 Description
536         Initializes the video input
537
538 -------------------------------------------------------------------------------
539
540 Name    CX2341X_ENC_SET_FRAME_DROP_RATE
541 Enum    208/0xD0
542 Description
543         For each frame captured, skip specified number of frames.
544 Param[0]
545         Number of frames to skip
546
547 -------------------------------------------------------------------------------
548
549 Name    CX2341X_ENC_PAUSE_ENCODER
550 Enum    210/0xD2
551 Description
552         During a pause condition, all frames are dropped instead of being encoded.
553 Param[0]
554         0=Pause encoding
555         1=Continue encoding
556
557 -------------------------------------------------------------------------------
558
559 Name    CX2341X_ENC_REFRESH_INPUT
560 Enum    211/0xD3
561 Description
562         Refreshes the video input
563
564 -------------------------------------------------------------------------------
565
566 Name    CX2341X_ENC_SET_COPYRIGHT
567 Enum    212/0xD4
568 Description
569         Sets stream copyright property
570 Param[0]
571         0=Stream is not copyrighted
572         1=Stream is copyrighted
573
574 -------------------------------------------------------------------------------
575
576 Name    CX2341X_ENC_SET_EVENT_NOTIFICATION
577 Enum    213/0xD5
578 Description
579         Setup firmware to notify the host about a particular event. Host must
580         unmask the interrupt bit.
581 Param[0]
582         Event (0=refresh encoder input)
583 Param[1]
584         Notification 0=disabled 1=enabled
585 Param[2]
586         Interrupt bit
587 Param[3]
588         Mailbox slot, -1 if no mailbox required.
589
590 -------------------------------------------------------------------------------
591
592 Name    CX2341X_ENC_SET_NUM_VSYNC_LINES
593 Enum    214/0xD6
594 Description
595         Depending on the analog video decoder used, this assigns the number
596         of lines for field 1 and 2.
597 Param[0]
598         Field 1 number of lines:
599             0x00EF for SAA7114
600             0x00F0 for SAA7115
601             0x0105 for Micronas
602 Param[1]
603         Field 2 number of lines:
604             0x00EF for SAA7114
605             0x00F0 for SAA7115
606             0x0106 for Micronas
607
608 -------------------------------------------------------------------------------
609
610 Name    CX2341X_ENC_SET_PLACEHOLDER
611 Enum    215/0xD7
612 Description
613         Provides a mechanism of inserting custom user data in the MPEG stream.
614 Param[0]
615         0=extension & user data
616         1=private packet with stream ID 0xBD
617 Param[1]
618         Rate at which to insert data, in units of frames (for private packet)
619         or GOPs (for ext. & user data)
620 Param[2]
621         Number of data DWORDs (below) to insert
622 Param[3]
623         Custom data 0
624 Param[4]
625         Custom data 1
626 Param[5]
627         Custom data 2
628 Param[6]
629         Custom data 3
630 Param[7]
631         Custom data 4
632 Param[8]
633         Custom data 5
634 Param[9]
635         Custom data 6
636 Param[10]
637         Custom data 7
638 Param[11]
639         Custom data 8
640
641 -------------------------------------------------------------------------------
642
643 Name    CX2341X_ENC_MUTE_VIDEO
644 Enum    217/0xD9
645 Description
646         Video muting
647 Param[0]
648         Bit usage:
649          0      '0'=video not muted
650                 '1'=video muted, creates frames with the YUV color defined below
651          1:7    Unused
652          8:15   V chrominance information
653         16:23   U chrominance information
654         24:31   Y luminance information
655
656 -------------------------------------------------------------------------------
657
658 Name    CX2341X_ENC_MUTE_AUDIO
659 Enum    218/0xDA
660 Description
661         Audio muting
662 Param[0]
663         0=audio not muted
664         1=audio muted (produces silent mpeg audio stream)
665
666 -------------------------------------------------------------------------------
667
668 Name    CX2341X_ENC_SET_VERT_CROP_LINE
669 Enum    219/0xDB
670 Description
671         Something to do with 'Vertical Crop Line'
672 Param[0]
673         If saa7114 and raw VBI capture and 60 Hz, then set to 10001.
674         Else 0.
675
676 -------------------------------------------------------------------------------
677
678 Name    CX2341X_ENC_MISC
679 Enum    220/0xDC
680 Description
681         Miscellaneous actions. Not known for 100% what it does. It's really a
682         sort of ioctl call. The first parameter is a command number, the second
683         the value.
684 Param[0]
685         Command number:
686          1=set initial SCR value when starting encoding (works).
687          2=set quality mode (apparently some test setting).
688          3=setup advanced VIM protection handling.
689            Always 1 for the cx23416 and 0 for cx23415.
690          4=generate DVD compatible PTS timestamps
691          5=USB flush mode
692          6=something to do with the quantization matrix
693          7=set navigation pack insertion for DVD: adds 0xbf (private stream 2)
694            packets to the MPEG. The size of these packets is 2048 bytes (including
695            the header of 6 bytes: 0x000001bf + length). The payload is zeroed and
696            it is up to the application to fill them in. These packets are apparently
697            inserted every four frames.
698          8=enable scene change detection (seems to be a failure)
699          9=set history parameters of the video input module
700         10=set input field order of VIM
701         11=set quantization matrix
702         12=reset audio interface after channel change or input switch (has no argument).
703            Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to
704            do any harm calling it regardless.
705         13=set audio volume delay
706         14=set audio delay
707
708 Param[1]
709         Command value.