Fix typos in Documentation/: 'H'-'M'
[linux-2.6.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_3_2_PULLDOWN
217 Enum    177/0xB1
218 Description
219         3:2 pulldown properties
220 Param[0]
221         0=enabled
222         1=disabled
223
224 -------------------------------------------------------------------------------
225
226 Name    CX2341X_ENC_SET_VBI_LINE
227 Enum    183/0xB7
228 Description
229         Selects VBI line number.
230 Param[0]
231         Bits 0:4        line number
232         Bit  31         0=top_field, 1=bottom_field
233         Bits 0:31       all set specifies "all lines"
234 Param[1]
235         VBI line information features: 0=disabled, 1=enabled
236 Param[2]
237         Slicing: 0=None, 1=Closed Caption
238         Almost certainly not implemented. Set to 0.
239 Param[3]
240         Luminance samples in this line.
241         Almost certainly not implemented. Set to 0.
242 Param[4]
243         Chrominance samples in this line
244         Almost certainly not implemented. Set to 0.
245
246 -------------------------------------------------------------------------------
247
248 Name    CX2341X_ENC_SET_STREAM_TYPE
249 Enum    185/0xB9
250 Description
251         Assign stream type
252         Note: Transport stream is not working in recent firmwares.
253         And in older firmwares the timestamps in the TS seem to be
254         unreliable.
255 Param[0]
256          0=Program stream
257          1=Transport stream
258          2=MPEG1 stream
259          3=PES A/V stream
260          5=PES Video stream
261          7=PES Audio stream
262         10=DVD stream
263         11=VCD stream
264         12=SVCD stream
265         13=DVD_S1 stream
266         14=DVD_S2 stream
267
268 -------------------------------------------------------------------------------
269
270 Name    CX2341X_ENC_SET_OUTPUT_PORT
271 Enum    187/0xBB
272 Description
273         Assign stream output port. Normally 0 when the data is copied through
274         the PCI bus (DMA), and 1 when the data is streamed to another chip
275         (pvrusb and cx88-blackbird).
276 Param[0]
277         0=Memory (default)
278         1=Streaming
279         2=Serial
280 Param[1]
281         Unknown, but leaving this to 0 seems to work best. Indications are that
282         this might have to do with USB support, although passing anything but 0
283         onl breaks things.
284
285 -------------------------------------------------------------------------------
286
287 Name    CX2341X_ENC_SET_AUDIO_PROPERTIES
288 Enum    189/0xBD
289 Description
290         Set audio stream properties, may be called while encoding is in progress.
291         Note: all bitfields are consistent with ISO11172 documentation except
292         bits 2:3 which ISO docs define as:
293                 '11' Layer I
294                 '10' Layer II
295                 '01' Layer III
296                 '00' Undefined
297         This discrepancy may indicate a possible error in the documentation.
298         Testing indicated that only Layer II is actually working, and that
299         the minimum bitrate should be 192 kbps.
300 Param[0]
301         Bitmask:
302            0:1  '00' 44.1Khz
303                 '01' 48Khz
304                 '10' 32Khz
305                 '11' reserved
306
307            2:3  '01'=Layer I
308                 '10'=Layer II
309
310            4:7  Bitrate:
311                      Index | Layer I     | Layer II
312                      ------+-------------+------------
313                     '0000' | free format | free format
314                     '0001' |  32 kbit/s  |  32 kbit/s
315                     '0010' |  64 kbit/s  |  48 kbit/s
316                     '0011' |  96 kbit/s  |  56 kbit/s
317                     '0100' | 128 kbit/s  |  64 kbit/s
318                     '0101' | 160 kbit/s  |  80 kbit/s
319                     '0110' | 192 kbit/s  |  96 kbit/s
320                     '0111' | 224 kbit/s  | 112 kbit/s
321                     '1000' | 256 kbit/s  | 128 kbit/s
322                     '1001' | 288 kbit/s  | 160 kbit/s
323                     '1010' | 320 kbit/s  | 192 kbit/s
324                     '1011' | 352 kbit/s  | 224 kbit/s
325                     '1100' | 384 kbit/s  | 256 kbit/s
326                     '1101' | 416 kbit/s  | 320 kbit/s
327                     '1110' | 448 kbit/s  | 384 kbit/s
328                 Note: For Layer II, not all combinations of total bitrate
329                 and mode are allowed. See ISO11172-3 3-Annex B, Table 3-B.2
330
331            8:9  '00'=Stereo
332                 '01'=JointStereo
333                 '10'=Dual
334                 '11'=Mono
335                 Note: testing seems to indicate that Mono and possibly
336                 JointStereo are not working (default to stereo).
337                 Dual does work, though.
338
339           10:11 Mode Extension used in joint_stereo mode.
340                 In Layer I and II they indicate which subbands are in
341                 intensity_stereo. All other subbands are coded in stereo.
342                     '00' subbands 4-31 in intensity_stereo, bound==4
343                     '01' subbands 8-31 in intensity_stereo, bound==8
344                     '10' subbands 12-31 in intensity_stereo, bound==12
345                     '11' subbands 16-31 in intensity_stereo, bound==16
346
347           12:13 Emphasis:
348                     '00' None
349                     '01' 50/15uS
350                     '10' reserved
351                     '11' CCITT J.17
352
353           14    CRC:
354                     '0' off
355                     '1' on
356
357           15    Copyright:
358                     '0' off
359                     '1' on
360
361           16    Generation:
362                     '0' copy
363                     '1' original
364
365 -------------------------------------------------------------------------------
366
367 Name    CX2341X_ENC_HALT_FW
368 Enum    195/0xC3
369 Description
370         The firmware is halted and no further API calls are serviced until the
371         firmware is uploaded again.
372
373 -------------------------------------------------------------------------------
374
375 Name    CX2341X_ENC_GET_VERSION
376 Enum    196/0xC4
377 Description
378         Returns the version of the encoder firmware.
379 Result[0]
380         Version bitmask:
381             Bits  0:15 build
382             Bits 16:23 minor
383             Bits 24:31 major
384
385 -------------------------------------------------------------------------------
386
387 Name    CX2341X_ENC_SET_GOP_CLOSURE
388 Enum    197/0xC5
389 Description
390         Assigns the GOP open/close property.
391 Param[0]
392         0=Open
393         1=Closed
394
395 -------------------------------------------------------------------------------
396
397 Name    CX2341X_ENC_GET_SEQ_END
398 Enum    198/0xC6
399 Description
400         Obtains the sequence end code of the encoder's buffer. When a capture
401         is started a number of interrupts are still generated, the last of
402         which will have Result[0] set to 1 and Result[1] will contain the size
403         of the buffer.
404 Result[0]
405         State of the transfer (1 if last buffer)
406 Result[1]
407         If Result[0] is 1, this contains the size of the last buffer, undefined
408         otherwise.
409
410 -------------------------------------------------------------------------------
411
412 Name    CX2341X_ENC_SET_PGM_INDEX_INFO
413 Enum    199/0xC7
414 Description
415         Sets the Program Index Information.
416 Param[0]
417         Picture Mask:
418             0=No index capture
419             1=I frames
420             3=I,P frames
421             7=I,P,B frames
422 Param[1]
423         Elements requested (up to 400)
424 Result[0]
425         Offset in SDF memory of the table.
426 Result[1]
427         Number of allocated elements up to a maximum of Param[1]
428
429 -------------------------------------------------------------------------------
430
431 Name    CX2341X_ENC_SET_VBI_CONFIG
432 Enum    200/0xC8
433 Description
434         Configure VBI settings
435 Param[0]
436         Bitmap:
437             0    Mode '0' Sliced, '1' Raw
438             1:3  Insertion:
439                      '000' insert in extension & user data
440                      '001' insert in private packets
441                      '010' separate stream and user data
442                      '111' separate stream and private data
443             8:15 Stream ID (normally 0xBD)
444 Param[1]
445         Frames per interrupt (max 8). Only valid in raw mode.
446 Param[2]
447         Total raw VBI frames. Only valid in raw mode.
448 Param[3]
449         Start codes
450 Param[4]
451         Stop codes
452 Param[5]
453         Lines per frame
454 Param[6]
455         Byte per line
456 Result[0]
457         Observed frames per interrupt in raw mode only. Rage 1 to Param[1]
458 Result[1]
459         Observed number of frames in raw mode. Range 1 to Param[2]
460 Result[2]
461         Memory offset to start or raw VBI data
462
463 -------------------------------------------------------------------------------
464
465 Name    CX2341X_ENC_SET_DMA_BLOCK_SIZE
466 Enum    201/0xC9
467 Description
468         Set DMA transfer block size
469 Param[0]
470         DMA transfer block size in bytes or frames. When unit is bytes,
471         supported block sizes are 2^7, 2^8 and 2^9 bytes.
472 Param[1]
473         Unit: 0=bytes, 1=frames
474
475 -------------------------------------------------------------------------------
476
477 Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
478 Enum    202/0xCA
479 Description
480         Returns information on the previous DMA transfer in conjunction with
481         bit 27 of the interrupt mask. Uses mailbox 10.
482 Result[0]
483         Type of stream
484 Result[1]
485         Address Offset
486 Result[2]
487         Maximum size of transfer
488
489 -------------------------------------------------------------------------------
490
491 Name    CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
492 Enum    203/0xCB
493 Description
494         Returns information on the previous DMA transfer in conjunction with
495         bit 27 of the interrupt mask. Uses mailbox 9.
496 Result[0]
497         Status bits:
498             Bit 0 set indicates transfer complete
499             Bit 2 set indicates transfer error
500             Bit 4 set indicates linked list error
501 Result[1]
502         DMA type
503 Result[2]
504         Presentation Time Stamp bits 0..31
505 Result[3]
506         Presentation Time Stamp bit 32
507
508 -------------------------------------------------------------------------------
509
510 Name    CX2341X_ENC_SCHED_DMA_TO_HOST
511 Enum    204/0xCC
512 Description
513         Setup DMA to host operation
514 Param[0]
515         Memory address of link list
516 Param[1]
517         Length of link list (wtf: what units ???)
518 Param[2]
519         DMA type (0=MPEG)
520
521 -------------------------------------------------------------------------------
522
523 Name    CX2341X_ENC_INITIALIZE_INPUT
524 Enum    205/0xCD
525 Description
526         Initializes the video input
527
528 -------------------------------------------------------------------------------
529
530 Name    CX2341X_ENC_SET_FRAME_DROP_RATE
531 Enum    208/0xD0
532 Description
533         For each frame captured, skip specified number of frames.
534 Param[0]
535         Number of frames to skip
536
537 -------------------------------------------------------------------------------
538
539 Name    CX2341X_ENC_PAUSE_ENCODER
540 Enum    210/0xD2
541 Description
542         During a pause condition, all frames are dropped instead of being encoded.
543 Param[0]
544         0=Pause encoding
545         1=Continue encoding
546
547 -------------------------------------------------------------------------------
548
549 Name    CX2341X_ENC_REFRESH_INPUT
550 Enum    211/0xD3
551 Description
552         Refreshes the video input
553
554 -------------------------------------------------------------------------------
555
556 Name    CX2341X_ENC_SET_COPYRIGHT
557 Enum    212/0xD4
558 Description
559         Sets stream copyright property
560 Param[0]
561         0=Stream is not copyrighted
562         1=Stream is copyrighted
563
564 -------------------------------------------------------------------------------
565
566 Name    CX2341X_ENC_SET_EVENT_NOTIFICATION
567 Enum    213/0xD5
568 Description
569         Setup firmware to notify the host about a particular event. Host must
570         unmask the interrupt bit.
571 Param[0]
572         Event (0=refresh encoder input)
573 Param[1]
574         Notification 0=disabled 1=enabled
575 Param[2]
576         Interrupt bit
577 Param[3]
578         Mailbox slot, -1 if no mailbox required.
579
580 -------------------------------------------------------------------------------
581
582 Name    CX2341X_ENC_SET_NUM_VSYNC_LINES
583 Enum    214/0xD6
584 Description
585         Depending on the analog video decoder used, this assigns the number
586         of lines for field 1 and 2.
587 Param[0]
588         Field 1 number of lines:
589             0x00EF for SAA7114
590             0x00F0 for SAA7115
591             0x0105 for Micronas
592 Param[1]
593         Field 2 number of lines:
594             0x00EF for SAA7114
595             0x00F0 for SAA7115
596             0x0106 for Micronas
597
598 -------------------------------------------------------------------------------
599
600 Name    CX2341X_ENC_SET_PLACEHOLDER
601 Enum    215/0xD7
602 Description
603         Provides a mechanism of inserting custom user data in the MPEG stream.
604 Param[0]
605         0=extension & user data
606         1=private packet with stream ID 0xBD
607 Param[1]
608         Rate at which to insert data, in units of frames (for private packet)
609         or GOPs (for ext. & user data)
610 Param[2]
611         Number of data DWORDs (below) to insert
612 Param[3]
613         Custom data 0
614 Param[4]
615         Custom data 1
616 Param[5]
617         Custom data 2
618 Param[6]
619         Custom data 3
620 Param[7]
621         Custom data 4
622 Param[8]
623         Custom data 5
624 Param[9]
625         Custom data 6
626 Param[10]
627         Custom data 7
628 Param[11]
629         Custom data 8
630
631 -------------------------------------------------------------------------------
632
633 Name    CX2341X_ENC_MUTE_VIDEO
634 Enum    217/0xD9
635 Description
636         Video muting
637 Param[0]
638         Bit usage:
639          0      '0'=video not muted
640                 '1'=video muted, creates frames with the YUV color defined below
641          1:7    Unused
642          8:15   V chrominance information
643         16:23   U chrominance information
644         24:31   Y luminance information
645
646 -------------------------------------------------------------------------------
647
648 Name    CX2341X_ENC_MUTE_AUDIO
649 Enum    218/0xDA
650 Description
651         Audio muting
652 Param[0]
653         0=audio not muted
654         1=audio muted (produces silent mpeg audio stream)
655
656 -------------------------------------------------------------------------------
657
658 Name    CX2341X_ENC_UNKNOWN
659 Enum    219/0xDB
660 Description
661         Unknown API, it's used by Hauppauge though.
662 Param[0]
663         0 This is the value Hauppauge uses, Unknown what it means.
664
665 -------------------------------------------------------------------------------
666
667 Name    CX2341X_ENC_MISC
668 Enum    220/0xDC
669 Description
670         Miscellaneous actions. Not known for 100% what it does. It's really a
671         sort of ioctl call. The first parameter is a command number, the second
672         the value.
673 Param[0]
674         Command number:
675          1=set initial SCR value when starting encoding.
676          2=set quality mode (apparently some test setting).
677          3=setup advanced VIM protection handling (supposedly only for the cx23416
678            for raw YUV).
679            Actually it looks like this should be 0 for saa7114/5 based card and 1
680            for cx25840 based cards.
681          4=generate artificial PTS timestamps
682          5=USB flush mode
683          6=something to do with the quantization matrix
684          7=set navigation pack insertion for DVD
685          8=enable scene change detection (seems to be a failure)
686          9=set history parameters of the video input module
687         10=set input field order of VIM
688         11=set quantization matrix
689         12=reset audio interface
690         13=set audio volume delay
691         14=set audio delay
692
693 Param[1]
694         Command value.