aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/video4linux/cx2341x/fw-encoder-api.txt
blob: 242104ce5b61b09a82e20c24bbf44339f722d6ac (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
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_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
	only 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: the cx23415 cannot decode Joint Stereo properly.

	  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.
	The information is stored as follows:

	struct info {
		u32 length;		// Length of this frame
		u32 offset_low;		// Offset in the file of the
		u32 offset_high;	// start of this frame
		u32 mask1;		// Bits 0-1 are the type mask:
					// 1=I, 2=P, 4=B
		u32 pts;		// The PTS of the frame
		u32 mask2;		// Bit 0 is bit 32 of the pts.
	};
	u32 table_ptr;
	struct info index[400];

	The table_ptr is the encoder memory address in the table were
	*new* entries will be written. Note that this is a ringbuffer,
	so the table_ptr will wraparound.
Param[0]
	Picture Mask:
	    0=No index capture
	    1=I frames
	    3=I,P frames
	    7=I,P,B frames
	(Seems to be ignored, it always indexes I, P and B frames)
Param[1]
	Elements requested (up to 400)
Result[0]
	Offset in the encoder memory of the start 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 or 18 of the interrupt mask. Uses mailbox 9.
Result[0]
	Status bits:
		0   read completed
		1   write completed
		2   DMA read error
		3   DMA write error
		4   Scatter-Gather array 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 (works).
	 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: adds 0xbf (private stream 2)
	   packets to the MPEG. The size of these packets is 2048 bytes (including
	   the header of 6 bytes: 0x000001bf + length). The payload is zeroed and
	   it is up to the application to fill them in. These packets are apparently
	   inserted every four frames.
	 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.