xref: /linux/Documentation/driver-api/media/drivers/cx2341x-devel.rst (revision 4b4193256c8d3bc3a5397b5cd9494c2ad386317d)
1.. SPDX-License-Identifier: GPL-2.0
2
3The cx2341x driver
4==================
5
6Memory at cx2341x chips
7-----------------------
8
9This section describes the cx2341x memory map and documents some of the
10register space.
11
12.. note:: the memory long words are little-endian ('intel format').
13
14.. warning::
15
16	This information was figured out from searching through the memory
17	and registers, this information may not be correct and is certainly
18	not complete, and was not derived from anything more than searching
19	through the memory space with commands like:
20
21	.. code-block:: none
22
23		ivtvctl -O min=0x02000000,max=0x020000ff
24
25	So take this as is, I'm always searching for more stuff, it's a large
26	register space :-).
27
28Memory Map
29~~~~~~~~~~
30
31The cx2341x exposes its entire 64M memory space to the PCI host via the PCI BAR0
32(Base Address Register 0). The addresses here are offsets relative to the
33address held in BAR0.
34
35.. code-block:: none
36
37	0x00000000-0x00ffffff Encoder memory space
38	0x00000000-0x0003ffff Encode.rom
39	???-???         MPEG buffer(s)
40	???-???         Raw video capture buffer(s)
41	???-???         Raw audio capture buffer(s)
42	???-???         Display buffers (6 or 9)
43
44	0x01000000-0x01ffffff Decoder memory space
45	0x01000000-0x0103ffff Decode.rom
46	???-???         MPEG buffers(s)
47	0x0114b000-0x0115afff Audio.rom (deprecated?)
48
49	0x02000000-0x0200ffff Register Space
50
51Registers
52~~~~~~~~~
53
54The registers occupy the 64k space starting at the 0x02000000 offset from BAR0.
55All of these registers are 32 bits wide.
56
57.. code-block:: none
58
59	DMA Registers 0x000-0xff:
60
61	0x00 - Control:
62		0=reset/cancel, 1=read, 2=write, 4=stop
63	0x04 - DMA status:
64		1=read busy, 2=write busy, 4=read error, 8=write error, 16=link list error
65	0x08 - pci DMA pointer for read link list
66	0x0c - pci DMA pointer for write link list
67	0x10 - read/write DMA enable:
68		1=read enable, 2=write enable
69	0x14 - always 0xffffffff, if set any lower instability occurs, 0x00 crashes
70	0x18 - ??
71	0x1c - always 0x20 or 32, smaller values slow down DMA transactions
72	0x20 - always value of 0x780a010a
73	0x24-0x3c - usually just random values???
74	0x40 - Interrupt status
75	0x44 - Write a bit here and shows up in Interrupt status 0x40
76	0x48 - Interrupt Mask
77	0x4C - always value of 0xfffdffff,
78		if changed to 0xffffffff DMA write interrupts break.
79	0x50 - always 0xffffffff
80	0x54 - always 0xffffffff (0x4c, 0x50, 0x54 seem like interrupt masks, are
81		3 processors on chip, Java ones, VPU, SPU, APU, maybe these are the
82		interrupt masks???).
83	0x60-0x7C - random values
84	0x80 - first write linked list reg, for Encoder Memory addr
85	0x84 - first write linked list reg, for pci memory addr
86	0x88 - first write linked list reg, for length of buffer in memory addr
87		(|0x80000000 or this for last link)
88	0x8c-0xdc - rest of write linked list reg, 8 sets of 3 total, DMA goes here
89		from linked list addr in reg 0x0c, firmware must push through or
90		something.
91	0xe0 - first (and only) read linked list reg, for pci memory addr
92	0xe4 - first (and only) read linked list reg, for Decoder memory addr
93	0xe8 - first (and only) read linked list reg, for length of buffer
94	0xec-0xff - Nothing seems to be in these registers, 0xec-f4 are 0x00000000.
95
96Memory locations for Encoder Buffers 0x700-0x7ff:
97
98These registers show offsets of memory locations pertaining to each
99buffer area used for encoding, have to shift them by <<1 first.
100
101- 0x07F8: Encoder SDRAM refresh
102- 0x07FC: Encoder SDRAM pre-charge
103
104Memory locations for Decoder Buffers 0x800-0x8ff:
105
106These registers show offsets of memory locations pertaining to each
107buffer area used for decoding, have to shift them by <<1 first.
108
109- 0x08F8: Decoder SDRAM refresh
110- 0x08FC: Decoder SDRAM pre-charge
111
112Other memory locations:
113
114- 0x2800: Video Display Module control
115- 0x2D00: AO (audio output?) control
116- 0x2D24: Bytes Flushed
117- 0x7000: LSB I2C write clock bit (inverted)
118- 0x7004: LSB I2C write data bit (inverted)
119- 0x7008: LSB I2C read clock bit
120- 0x700c: LSB I2C read data bit
121- 0x9008: GPIO get input state
122- 0x900c: GPIO set output state
123- 0x9020: GPIO direction (Bit7 (GPIO 0..7) - 0:input, 1:output)
124- 0x9050: SPU control
125- 0x9054: Reset HW blocks
126- 0x9058: VPU control
127- 0xA018: Bit6: interrupt pending?
128- 0xA064: APU command
129
130
131Interrupt Status Register
132~~~~~~~~~~~~~~~~~~~~~~~~~
133
134The definition of the bits in the interrupt status register 0x0040, and the
135interrupt mask 0x0048. If a bit is cleared in the mask, then we want our ISR to
136execute.
137
138- bit 31 Encoder Start Capture
139- bit 30 Encoder EOS
140- bit 29 Encoder VBI capture
141- bit 28 Encoder Video Input Module reset event
142- bit 27 Encoder DMA complete
143- bit 24 Decoder audio mode change detection event (through event notification)
144- bit 22 Decoder data request
145- bit 20 Decoder DMA complete
146- bit 19 Decoder VBI re-insertion
147- bit 18 Decoder DMA err (linked-list bad)
148
149Missing documentation
150---------------------
151
152- Encoder API post(?)
153- Decoder API post(?)
154- Decoder VTRACE event
155
156
157The cx2341x firmware upload
158---------------------------
159
160This document describes how to upload the cx2341x firmware to the card.
161
162How to find
163~~~~~~~~~~~
164
165See the web pages of the various projects that uses this chip for information
166on how to obtain the firmware.
167
168The firmware stored in a Windows driver can be detected as follows:
169
170- Each firmware image is 256k bytes.
171- The 1st 32-bit word of the Encoder image is 0x0000da7
172- The 1st 32-bit word of the Decoder image is 0x00003a7
173- The 2nd 32-bit word of both images is 0xaa55bb66
174
175How to load
176~~~~~~~~~~~
177
178- Issue the FWapi command to stop the encoder if it is running. Wait for the
179  command to complete.
180- Issue the FWapi command to stop the decoder if it is running. Wait for the
181  command to complete.
182- Issue the I2C command to the digitizer to stop emitting VSYNC events.
183- Issue the FWapi command to halt the encoder's firmware.
184- Sleep for 10ms.
185- Issue the FWapi command to halt the decoder's firmware.
186- Sleep for 10ms.
187- Write 0x00000000 to register 0x2800 to stop the Video Display Module.
188- Write 0x00000005 to register 0x2D00 to stop the AO (audio output?).
189- Write 0x00000000 to register 0xA064 to ping? the APU.
190- Write 0xFFFFFFFE to register 0x9058 to stop the VPU.
191- Write 0xFFFFFFFF to register 0x9054 to reset the HW blocks.
192- Write 0x00000001 to register 0x9050 to stop the SPU.
193- Sleep for 10ms.
194- Write 0x0000001A to register 0x07FC to init the Encoder SDRAM's pre-charge.
195- Write 0x80000640 to register 0x07F8 to init the Encoder SDRAM's refresh to 1us.
196- Write 0x0000001A to register 0x08FC to init the Decoder SDRAM's pre-charge.
197- Write 0x80000640 to register 0x08F8 to init the Decoder SDRAM's refresh to 1us.
198- Sleep for 512ms. (600ms is recommended)
199- Transfer the encoder's firmware image to offset 0 in Encoder memory space.
200- Transfer the decoder's firmware image to offset 0 in Decoder memory space.
201- Use a read-modify-write operation to Clear bit 0 of register 0x9050 to
202  re-enable the SPU.
203- Sleep for 1 second.
204- Use a read-modify-write operation to Clear bits 3 and 0 of register 0x9058
205  to re-enable the VPU.
206- Sleep for 1 second.
207- Issue status API commands to both firmware images to verify.
208
209
210How to call the firmware API
211----------------------------
212
213The preferred calling convention is known as the firmware mailbox. The
214mailboxes are basically a fixed length array that serves as the call-stack.
215
216Firmware mailboxes can be located by searching the encoder and decoder memory
217for a 16 byte signature. That signature will be located on a 256-byte boundary.
218
219Signature:
220
221.. code-block:: none
222
223	0x78, 0x56, 0x34, 0x12, 0x12, 0x78, 0x56, 0x34,
224	0x34, 0x12, 0x78, 0x56, 0x56, 0x34, 0x12, 0x78
225
226The firmware implements 20 mailboxes of 20 32-bit words. The first 10 are
227reserved for API calls. The second 10 are used by the firmware for event
228notification.
229
230  ====== =================
231  Index  Name
232  ====== =================
233  0      Flags
234  1      Command
235  2      Return value
236  3      Timeout
237  4-19   Parameter/Result
238  ====== =================
239
240
241The flags are defined in the following table. The direction is from the
242perspective of the firmware.
243
244  ==== ========== ============================================
245  Bit  Direction  Purpose
246  ==== ========== ============================================
247  2    O          Firmware has processed the command.
248  1    I          Driver has finished setting the parameters.
249  0    I          Driver is using this mailbox.
250  ==== ========== ============================================
251
252The command is a 32-bit enumerator. The API specifics may be found in this
253chapter.
254
255The return value is a 32-bit enumerator. Only two values are currently defined:
256
257- 0=success
258- -1=command undefined.
259
260There are 16 parameters/results 32-bit fields. The driver populates these fields
261with values for all the parameters required by the call. The driver overwrites
262these fields with result values returned by the call.
263
264The timeout value protects the card from a hung driver thread. If the driver
265doesn't handle the completed call within the timeout specified, the firmware
266will reset that mailbox.
267
268To make an API call, the driver iterates over each mailbox looking for the
269first one available (bit 0 has been cleared). The driver sets that bit, fills
270in the command enumerator, the timeout value and any required parameters. The
271driver then sets the parameter ready bit (bit 1). The firmware scans the
272mailboxes for pending commands, processes them, sets the result code, populates
273the result value array with that call's return values and sets the call
274complete bit (bit 2). Once bit 2 is set, the driver should retrieve the results
275and clear all the flags. If the driver does not perform this task within the
276time set in the timeout register, the firmware will reset that mailbox.
277
278Event notifications are sent from the firmware to the host. The host tells the
279firmware which events it is interested in via an API call. That call tells the
280firmware which notification mailbox to use. The firmware signals the host via
281an interrupt. Only the 16 Results fields are used, the Flags, Command, Return
282value and Timeout words are not used.
283
284
285OSD firmware API description
286----------------------------
287
288.. note:: this API is part of the decoder firmware, so it's cx23415 only.
289
290
291
292CX2341X_OSD_GET_FRAMEBUFFER
293~~~~~~~~~~~~~~~~~~~~~~~~~~~
294
295Enum: 65/0x41
296
297Description
298^^^^^^^^^^^
299
300Return base and length of contiguous OSD memory.
301
302Result[0]
303^^^^^^^^^
304
305OSD base address
306
307Result[1]
308^^^^^^^^^
309
310OSD length
311
312
313
314CX2341X_OSD_GET_PIXEL_FORMAT
315~~~~~~~~~~~~~~~~~~~~~~~~~~~~
316
317Enum: 66/0x42
318
319Description
320^^^^^^^^^^^
321
322Query OSD format
323
324Result[0]
325^^^^^^^^^
326
3270=8bit index
3281=16bit RGB 5:6:5
3292=16bit ARGB 1:5:5:5
3303=16bit ARGB 1:4:4:4
3314=32bit ARGB 8:8:8:8
332
333
334
335CX2341X_OSD_SET_PIXEL_FORMAT
336~~~~~~~~~~~~~~~~~~~~~~~~~~~~
337
338Enum: 67/0x43
339
340Description
341^^^^^^^^^^^
342
343Assign pixel format
344
345Param[0]
346^^^^^^^^
347
348- 0=8bit index
349- 1=16bit RGB 5:6:5
350- 2=16bit ARGB 1:5:5:5
351- 3=16bit ARGB 1:4:4:4
352- 4=32bit ARGB 8:8:8:8
353
354
355
356CX2341X_OSD_GET_STATE
357~~~~~~~~~~~~~~~~~~~~~
358
359Enum: 68/0x44
360
361Description
362^^^^^^^^^^^
363
364Query OSD state
365
366Result[0]
367^^^^^^^^^
368
369- Bit  0   0=off, 1=on
370- Bits 1:2 alpha control
371- Bits 3:5 pixel format
372
373
374
375CX2341X_OSD_SET_STATE
376~~~~~~~~~~~~~~~~~~~~~
377
378Enum: 69/0x45
379
380Description
381^^^^^^^^^^^
382
383OSD switch
384
385Param[0]
386^^^^^^^^
387
3880=off, 1=on
389
390
391
392CX2341X_OSD_GET_OSD_COORDS
393~~~~~~~~~~~~~~~~~~~~~~~~~~
394
395Enum: 70/0x46
396
397Description
398^^^^^^^^^^^
399
400Retrieve coordinates of OSD area blended with video
401
402Result[0]
403^^^^^^^^^
404
405OSD buffer address
406
407Result[1]
408^^^^^^^^^
409
410Stride in pixels
411
412Result[2]
413^^^^^^^^^
414
415Lines in OSD buffer
416
417Result[3]
418^^^^^^^^^
419
420Horizontal offset in buffer
421
422Result[4]
423^^^^^^^^^
424
425Vertical offset in buffer
426
427
428
429CX2341X_OSD_SET_OSD_COORDS
430~~~~~~~~~~~~~~~~~~~~~~~~~~
431
432Enum: 71/0x47
433
434Description
435^^^^^^^^^^^
436
437Assign the coordinates of the OSD area to blend with video
438
439Param[0]
440^^^^^^^^
441
442buffer address
443
444Param[1]
445^^^^^^^^
446
447buffer stride in pixels
448
449Param[2]
450^^^^^^^^
451
452lines in buffer
453
454Param[3]
455^^^^^^^^
456
457horizontal offset
458
459Param[4]
460^^^^^^^^
461
462vertical offset
463
464
465
466CX2341X_OSD_GET_SCREEN_COORDS
467~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
468
469Enum: 72/0x48
470
471Description
472^^^^^^^^^^^
473
474Retrieve OSD screen area coordinates
475
476Result[0]
477^^^^^^^^^
478
479top left horizontal offset
480
481Result[1]
482^^^^^^^^^
483
484top left vertical offset
485
486Result[2]
487^^^^^^^^^
488
489bottom right horizontal offset
490
491Result[3]
492^^^^^^^^^
493
494bottom right vertical offset
495
496
497
498CX2341X_OSD_SET_SCREEN_COORDS
499~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
500
501Enum: 73/0x49
502
503Description
504^^^^^^^^^^^
505
506Assign the coordinates of the screen area to blend with video
507
508Param[0]
509^^^^^^^^
510
511top left horizontal offset
512
513Param[1]
514^^^^^^^^
515
516top left vertical offset
517
518Param[2]
519^^^^^^^^
520
521bottom left horizontal offset
522
523Param[3]
524^^^^^^^^
525
526bottom left vertical offset
527
528
529
530CX2341X_OSD_GET_GLOBAL_ALPHA
531~~~~~~~~~~~~~~~~~~~~~~~~~~~~
532
533Enum: 74/0x4A
534
535Description
536^^^^^^^^^^^
537
538Retrieve OSD global alpha
539
540Result[0]
541^^^^^^^^^
542
543global alpha: 0=off, 1=on
544
545Result[1]
546^^^^^^^^^
547
548bits 0:7 global alpha
549
550
551
552CX2341X_OSD_SET_GLOBAL_ALPHA
553~~~~~~~~~~~~~~~~~~~~~~~~~~~~
554
555Enum: 75/0x4B
556
557Description
558^^^^^^^^^^^
559
560Update global alpha
561
562Param[0]
563^^^^^^^^
564
565global alpha: 0=off, 1=on
566
567Param[1]
568^^^^^^^^
569
570global alpha (8 bits)
571
572Param[2]
573^^^^^^^^
574
575local alpha: 0=on, 1=off
576
577
578
579CX2341X_OSD_SET_BLEND_COORDS
580~~~~~~~~~~~~~~~~~~~~~~~~~~~~
581
582Enum: 78/0x4C
583
584Description
585^^^^^^^^^^^
586
587Move start of blending area within display buffer
588
589Param[0]
590^^^^^^^^
591
592horizontal offset in buffer
593
594Param[1]
595^^^^^^^^
596
597vertical offset in buffer
598
599
600
601CX2341X_OSD_GET_FLICKER_STATE
602~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
603
604Enum: 79/0x4F
605
606Description
607^^^^^^^^^^^
608
609Retrieve flicker reduction module state
610
611Result[0]
612^^^^^^^^^
613
614flicker state: 0=off, 1=on
615
616
617
618CX2341X_OSD_SET_FLICKER_STATE
619~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
620
621Enum: 80/0x50
622
623Description
624^^^^^^^^^^^
625
626Set flicker reduction module state
627
628Param[0]
629^^^^^^^^
630
631State: 0=off, 1=on
632
633
634
635CX2341X_OSD_BLT_COPY
636~~~~~~~~~~~~~~~~~~~~
637
638Enum: 82/0x52
639
640Description
641^^^^^^^^^^^
642
643BLT copy
644
645Param[0]
646^^^^^^^^
647
648.. code-block:: none
649
650	'0000'  zero
651	'0001' ~destination AND ~source
652	'0010' ~destination AND  source
653	'0011' ~destination
654	'0100'  destination AND ~source
655	'0101'                  ~source
656	'0110'  destination XOR  source
657	'0111' ~destination OR  ~source
658	'1000' ~destination AND ~source
659	'1001'  destination XNOR source
660	'1010'                   source
661	'1011' ~destination OR   source
662	'1100'  destination
663	'1101'  destination OR  ~source
664	'1110'  destination OR   source
665	'1111'  one
666
667
668Param[1]
669^^^^^^^^
670
671Resulting alpha blending
672
673- '01' source_alpha
674- '10' destination_alpha
675- '11' source_alpha*destination_alpha+1
676  (zero if both source and destination alpha are zero)
677
678Param[2]
679^^^^^^^^
680
681.. code-block:: none
682
683	'00' output_pixel = source_pixel
684
685	'01' if source_alpha=0:
686		 output_pixel = destination_pixel
687	     if 256 > source_alpha > 1:
688		 output_pixel = ((source_alpha + 1)*source_pixel +
689				 (255 - source_alpha)*destination_pixel)/256
690
691	'10' if destination_alpha=0:
692		 output_pixel = source_pixel
693	      if 255 > destination_alpha > 0:
694		 output_pixel = ((255 - destination_alpha)*source_pixel +
695				 (destination_alpha + 1)*destination_pixel)/256
696
697	'11' if source_alpha=0:
698		 source_temp = 0
699	     if source_alpha=255:
700		 source_temp = source_pixel*256
701	     if 255 > source_alpha > 0:
702		 source_temp = source_pixel*(source_alpha + 1)
703	     if destination_alpha=0:
704		 destination_temp = 0
705	     if destination_alpha=255:
706		 destination_temp = destination_pixel*256
707	     if 255 > destination_alpha > 0:
708		 destination_temp = destination_pixel*(destination_alpha + 1)
709	     output_pixel = (source_temp + destination_temp)/256
710
711Param[3]
712^^^^^^^^
713
714width
715
716Param[4]
717^^^^^^^^
718
719height
720
721Param[5]
722^^^^^^^^
723
724destination pixel mask
725
726Param[6]
727^^^^^^^^
728
729destination rectangle start address
730
731Param[7]
732^^^^^^^^
733
734destination stride in dwords
735
736Param[8]
737^^^^^^^^
738
739source stride in dwords
740
741Param[9]
742^^^^^^^^
743
744source rectangle start address
745
746
747
748CX2341X_OSD_BLT_FILL
749~~~~~~~~~~~~~~~~~~~~
750
751Enum: 83/0x53
752
753Description
754^^^^^^^^^^^
755
756BLT fill color
757
758Param[0]
759^^^^^^^^
760
761Same as Param[0] on API 0x52
762
763Param[1]
764^^^^^^^^
765
766Same as Param[1] on API 0x52
767
768Param[2]
769^^^^^^^^
770
771Same as Param[2] on API 0x52
772
773Param[3]
774^^^^^^^^
775
776width
777
778Param[4]
779^^^^^^^^
780
781height
782
783Param[5]
784^^^^^^^^
785
786destination pixel mask
787
788Param[6]
789^^^^^^^^
790
791destination rectangle start address
792
793Param[7]
794^^^^^^^^
795
796destination stride in dwords
797
798Param[8]
799^^^^^^^^
800
801color fill value
802
803
804
805CX2341X_OSD_BLT_TEXT
806~~~~~~~~~~~~~~~~~~~~
807
808Enum: 84/0x54
809
810Description
811^^^^^^^^^^^
812
813BLT for 8 bit alpha text source
814
815Param[0]
816^^^^^^^^
817
818Same as Param[0] on API 0x52
819
820Param[1]
821^^^^^^^^
822
823Same as Param[1] on API 0x52
824
825Param[2]
826^^^^^^^^
827
828Same as Param[2] on API 0x52
829
830Param[3]
831^^^^^^^^
832
833width
834
835Param[4]
836^^^^^^^^
837
838height
839
840Param[5]
841^^^^^^^^
842
843destination pixel mask
844
845Param[6]
846^^^^^^^^
847
848destination rectangle start address
849
850Param[7]
851^^^^^^^^
852
853destination stride in dwords
854
855Param[8]
856^^^^^^^^
857
858source stride in dwords
859
860Param[9]
861^^^^^^^^
862
863source rectangle start address
864
865Param[10]
866^^^^^^^^^
867
868color fill value
869
870
871
872CX2341X_OSD_SET_FRAMEBUFFER_WINDOW
873~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
874
875Enum: 86/0x56
876
877Description
878^^^^^^^^^^^
879
880Positions the main output window on the screen. The coordinates must be
881such that the entire window fits on the screen.
882
883Param[0]
884^^^^^^^^
885
886window width
887
888Param[1]
889^^^^^^^^
890
891window height
892
893Param[2]
894^^^^^^^^
895
896top left window corner horizontal offset
897
898Param[3]
899^^^^^^^^
900
901top left window corner vertical offset
902
903
904
905CX2341X_OSD_SET_CHROMA_KEY
906~~~~~~~~~~~~~~~~~~~~~~~~~~
907
908Enum: 96/0x60
909
910Description
911^^^^^^^^^^^
912
913Chroma key switch and color
914
915Param[0]
916^^^^^^^^
917
918state: 0=off, 1=on
919
920Param[1]
921^^^^^^^^
922
923color
924
925
926
927CX2341X_OSD_GET_ALPHA_CONTENT_INDEX
928~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
929
930Enum: 97/0x61
931
932Description
933^^^^^^^^^^^
934
935Retrieve alpha content index
936
937Result[0]
938^^^^^^^^^
939
940alpha content index, Range 0:15
941
942
943
944CX2341X_OSD_SET_ALPHA_CONTENT_INDEX
945~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
946
947Enum: 98/0x62
948
949Description
950^^^^^^^^^^^
951
952Assign alpha content index
953
954Param[0]
955^^^^^^^^
956
957alpha content index, range 0:15
958
959
960Encoder firmware API description
961--------------------------------
962
963CX2341X_ENC_PING_FW
964~~~~~~~~~~~~~~~~~~~
965
966Enum: 128/0x80
967
968Description
969^^^^^^^^^^^
970
971Does nothing. Can be used to check if the firmware is responding.
972
973
974
975CX2341X_ENC_START_CAPTURE
976~~~~~~~~~~~~~~~~~~~~~~~~~
977
978Enum: 129/0x81
979
980Description
981^^^^^^^^^^^
982
983Commences the capture of video, audio and/or VBI data. All encoding
984parameters must be initialized prior to this API call. Captures frames
985continuously or until a predefined number of frames have been captured.
986
987Param[0]
988^^^^^^^^
989
990Capture stream type:
991
992	- 0=MPEG
993	- 1=Raw
994	- 2=Raw passthrough
995	- 3=VBI
996
997
998Param[1]
999^^^^^^^^
1000
1001Bitmask:
1002
1003	- Bit 0 when set, captures YUV
1004	- Bit 1 when set, captures PCM audio
1005	- Bit 2 when set, captures VBI (same as param[0]=3)
1006	- Bit 3 when set, the capture destination is the decoder
1007	  (same as param[0]=2)
1008	- Bit 4 when set, the capture destination is the host
1009
1010.. note:: this parameter is only meaningful for RAW capture type.
1011
1012
1013
1014CX2341X_ENC_STOP_CAPTURE
1015~~~~~~~~~~~~~~~~~~~~~~~~
1016
1017Enum: 130/0x82
1018
1019Description
1020^^^^^^^^^^^
1021
1022Ends a capture in progress
1023
1024Param[0]
1025^^^^^^^^
1026
1027- 0=stop at end of GOP (generates IRQ)
1028- 1=stop immediate (no IRQ)
1029
1030Param[1]
1031^^^^^^^^
1032
1033Stream type to stop, see param[0] of API 0x81
1034
1035Param[2]
1036^^^^^^^^
1037
1038Subtype, see param[1] of API 0x81
1039
1040
1041
1042CX2341X_ENC_SET_AUDIO_ID
1043~~~~~~~~~~~~~~~~~~~~~~~~
1044
1045Enum: 137/0x89
1046
1047Description
1048^^^^^^^^^^^
1049
1050Assigns the transport stream ID of the encoded audio stream
1051
1052Param[0]
1053^^^^^^^^
1054
1055Audio Stream ID
1056
1057
1058
1059CX2341X_ENC_SET_VIDEO_ID
1060~~~~~~~~~~~~~~~~~~~~~~~~
1061
1062Enum: 139/0x8B
1063
1064Description
1065^^^^^^^^^^^
1066
1067Set video transport stream ID
1068
1069Param[0]
1070^^^^^^^^
1071
1072Video stream ID
1073
1074
1075
1076CX2341X_ENC_SET_PCR_ID
1077~~~~~~~~~~~~~~~~~~~~~~
1078
1079Enum: 141/0x8D
1080
1081Description
1082^^^^^^^^^^^
1083
1084Assigns the transport stream ID for PCR packets
1085
1086Param[0]
1087^^^^^^^^
1088
1089PCR Stream ID
1090
1091
1092
1093CX2341X_ENC_SET_FRAME_RATE
1094~~~~~~~~~~~~~~~~~~~~~~~~~~
1095
1096Enum: 143/0x8F
1097
1098Description
1099^^^^^^^^^^^
1100
1101Set video frames per second. Change occurs at start of new GOP.
1102
1103Param[0]
1104^^^^^^^^
1105
1106- 0=30fps
1107- 1=25fps
1108
1109
1110
1111CX2341X_ENC_SET_FRAME_SIZE
1112~~~~~~~~~~~~~~~~~~~~~~~~~~
1113
1114Enum: 145/0x91
1115
1116Description
1117^^^^^^^^^^^
1118
1119Select video stream encoding resolution.
1120
1121Param[0]
1122^^^^^^^^
1123
1124Height in lines. Default 480
1125
1126Param[1]
1127^^^^^^^^
1128
1129Width in pixels. Default 720
1130
1131
1132
1133CX2341X_ENC_SET_BIT_RATE
1134~~~~~~~~~~~~~~~~~~~~~~~~
1135
1136Enum: 149/0x95
1137
1138Description
1139^^^^^^^^^^^
1140
1141Assign average video stream bitrate.
1142
1143Param[0]
1144^^^^^^^^
1145
11460=variable bitrate, 1=constant bitrate
1147
1148Param[1]
1149^^^^^^^^
1150
1151bitrate in bits per second
1152
1153Param[2]
1154^^^^^^^^
1155
1156peak bitrate in bits per second, divided by 400
1157
1158Param[3]
1159^^^^^^^^
1160
1161Mux bitrate in bits per second, divided by 400. May be 0 (default).
1162
1163Param[4]
1164^^^^^^^^
1165
1166Rate Control VBR Padding
1167
1168Param[5]
1169^^^^^^^^
1170
1171VBV Buffer used by encoder
1172
1173.. note::
1174
1175	#) Param\[3\] and Param\[4\] seem to be always 0
1176	#) Param\[5\] doesn't seem to be used.
1177
1178
1179
1180CX2341X_ENC_SET_GOP_PROPERTIES
1181~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1182
1183Enum: 151/0x97
1184
1185Description
1186^^^^^^^^^^^
1187
1188Setup the GOP structure
1189
1190Param[0]
1191^^^^^^^^
1192
1193GOP size (maximum is 34)
1194
1195Param[1]
1196^^^^^^^^
1197
1198Number of B frames between the I and P frame, plus 1.
1199For example: IBBPBBPBBPBB --> GOP size: 12, number of B frames: 2+1 = 3
1200
1201.. note::
1202
1203	GOP size must be a multiple of (B-frames + 1).
1204
1205
1206
1207CX2341X_ENC_SET_ASPECT_RATIO
1208~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1209
1210Enum: 153/0x99
1211
1212Description
1213^^^^^^^^^^^
1214
1215Sets the encoding aspect ratio. Changes in the aspect ratio take effect
1216at the start of the next GOP.
1217
1218Param[0]
1219^^^^^^^^
1220
1221- '0000' forbidden
1222- '0001' 1:1 square
1223- '0010' 4:3
1224- '0011' 16:9
1225- '0100' 2.21:1
1226- '0101' to '1111' reserved
1227
1228
1229
1230CX2341X_ENC_SET_DNR_FILTER_MODE
1231~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1232
1233Enum: 155/0x9B
1234
1235Description
1236^^^^^^^^^^^
1237
1238Assign Dynamic Noise Reduction operating mode
1239
1240Param[0]
1241^^^^^^^^
1242
1243Bit0: Spatial filter, set=auto, clear=manual
1244Bit1: Temporal filter, set=auto, clear=manual
1245
1246Param[1]
1247^^^^^^^^
1248
1249Median filter:
1250
1251- 0=Disabled
1252- 1=Horizontal
1253- 2=Vertical
1254- 3=Horiz/Vert
1255- 4=Diagonal
1256
1257
1258
1259CX2341X_ENC_SET_DNR_FILTER_PROPS
1260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1261
1262Enum: 157/0x9D
1263
1264Description
1265^^^^^^^^^^^
1266
1267These Dynamic Noise Reduction filter values are only meaningful when
1268the respective filter is set to "manual" (See API 0x9B)
1269
1270Param[0]
1271^^^^^^^^
1272
1273Spatial filter: default 0, range 0:15
1274
1275Param[1]
1276^^^^^^^^
1277
1278Temporal filter: default 0, range 0:31
1279
1280
1281
1282CX2341X_ENC_SET_CORING_LEVELS
1283~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1284
1285Enum: 159/0x9F
1286
1287Description
1288^^^^^^^^^^^
1289
1290Assign Dynamic Noise Reduction median filter properties.
1291
1292Param[0]
1293^^^^^^^^
1294
1295Threshold above which the luminance median filter is enabled.
1296Default: 0, range 0:255
1297
1298Param[1]
1299^^^^^^^^
1300
1301Threshold below which the luminance median filter is enabled.
1302Default: 255, range 0:255
1303
1304Param[2]
1305^^^^^^^^
1306
1307Threshold above which the chrominance median filter is enabled.
1308Default: 0, range 0:255
1309
1310Param[3]
1311^^^^^^^^
1312
1313Threshold below which the chrominance median filter is enabled.
1314Default: 255, range 0:255
1315
1316
1317
1318CX2341X_ENC_SET_SPATIAL_FILTER_TYPE
1319~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1320
1321Enum: 161/0xA1
1322
1323Description
1324^^^^^^^^^^^
1325
1326Assign spatial prefilter parameters
1327
1328Param[0]
1329^^^^^^^^
1330
1331Luminance filter
1332
1333- 0=Off
1334- 1=1D Horizontal
1335- 2=1D Vertical
1336- 3=2D H/V Separable (default)
1337- 4=2D Symmetric non-separable
1338
1339Param[1]
1340^^^^^^^^
1341
1342Chrominance filter
1343
1344- 0=Off
1345- 1=1D Horizontal (default)
1346
1347
1348
1349CX2341X_ENC_SET_VBI_LINE
1350~~~~~~~~~~~~~~~~~~~~~~~~
1351
1352Enum: 183/0xB7
1353
1354Description
1355^^^^^^^^^^^
1356
1357Selects VBI line number.
1358
1359Param[0]
1360^^^^^^^^
1361
1362- Bits 0:4 	line number
1363- Bit  31		0=top_field, 1=bottom_field
1364- Bits 0:31 	all set specifies "all lines"
1365
1366Param[1]
1367^^^^^^^^
1368
1369VBI line information features: 0=disabled, 1=enabled
1370
1371Param[2]
1372^^^^^^^^
1373
1374Slicing: 0=None, 1=Closed Caption
1375Almost certainly not implemented. Set to 0.
1376
1377Param[3]
1378^^^^^^^^
1379
1380Luminance samples in this line.
1381Almost certainly not implemented. Set to 0.
1382
1383Param[4]
1384^^^^^^^^
1385
1386Chrominance samples in this line
1387Almost certainly not implemented. Set to 0.
1388
1389
1390
1391CX2341X_ENC_SET_STREAM_TYPE
1392~~~~~~~~~~~~~~~~~~~~~~~~~~~
1393
1394Enum: 185/0xB9
1395
1396Description
1397^^^^^^^^^^^
1398
1399Assign stream type
1400
1401.. note::
1402
1403	Transport stream is not working in recent firmwares.
1404	And in older firmwares the timestamps in the TS seem to be
1405	unreliable.
1406
1407Param[0]
1408^^^^^^^^
1409
1410- 0=Program stream
1411- 1=Transport stream
1412- 2=MPEG1 stream
1413- 3=PES A/V stream
1414- 5=PES Video stream
1415- 7=PES Audio stream
1416- 10=DVD stream
1417- 11=VCD stream
1418- 12=SVCD stream
1419- 13=DVD_S1 stream
1420- 14=DVD_S2 stream
1421
1422
1423
1424CX2341X_ENC_SET_OUTPUT_PORT
1425~~~~~~~~~~~~~~~~~~~~~~~~~~~
1426
1427Enum: 187/0xBB
1428
1429Description
1430^^^^^^^^^^^
1431
1432Assign stream output port. Normally 0 when the data is copied through
1433the PCI bus (DMA), and 1 when the data is streamed to another chip
1434(pvrusb and cx88-blackbird).
1435
1436Param[0]
1437^^^^^^^^
1438
1439- 0=Memory (default)
1440- 1=Streaming
1441- 2=Serial
1442
1443Param[1]
1444^^^^^^^^
1445
1446Unknown, but leaving this to 0 seems to work best. Indications are that
1447this might have to do with USB support, although passing anything but 0
1448only breaks things.
1449
1450
1451
1452CX2341X_ENC_SET_AUDIO_PROPERTIES
1453~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1454
1455Enum: 189/0xBD
1456
1457Description
1458^^^^^^^^^^^
1459
1460Set audio stream properties, may be called while encoding is in progress.
1461
1462.. note::
1463
1464	All bitfields are consistent with ISO11172 documentation except
1465	bits 2:3 which ISO docs define as:
1466
1467	- '11' Layer I
1468	- '10' Layer II
1469	- '01' Layer III
1470	- '00' Undefined
1471
1472	This discrepancy may indicate a possible error in the documentation.
1473	Testing indicated that only Layer II is actually working, and that
1474	the minimum bitrate should be 192 kbps.
1475
1476Param[0]
1477^^^^^^^^
1478
1479Bitmask:
1480
1481.. code-block:: none
1482
1483	   0:1  '00' 44.1Khz
1484		'01' 48Khz
1485		'10' 32Khz
1486		'11' reserved
1487
1488	   2:3  '01'=Layer I
1489		'10'=Layer II
1490
1491	   4:7  Bitrate:
1492		     Index | Layer I     | Layer II
1493		     ------+-------------+------------
1494		    '0000' | free format | free format
1495		    '0001' |  32 kbit/s  |  32 kbit/s
1496		    '0010' |  64 kbit/s  |  48 kbit/s
1497		    '0011' |  96 kbit/s  |  56 kbit/s
1498		    '0100' | 128 kbit/s  |  64 kbit/s
1499		    '0101' | 160 kbit/s  |  80 kbit/s
1500		    '0110' | 192 kbit/s  |  96 kbit/s
1501		    '0111' | 224 kbit/s  | 112 kbit/s
1502		    '1000' | 256 kbit/s  | 128 kbit/s
1503		    '1001' | 288 kbit/s  | 160 kbit/s
1504		    '1010' | 320 kbit/s  | 192 kbit/s
1505		    '1011' | 352 kbit/s  | 224 kbit/s
1506		    '1100' | 384 kbit/s  | 256 kbit/s
1507		    '1101' | 416 kbit/s  | 320 kbit/s
1508		    '1110' | 448 kbit/s  | 384 kbit/s
1509
1510		.. note::
1511
1512			For Layer II, not all combinations of total bitrate
1513			and mode are allowed. See ISO11172-3 3-Annex B,
1514			Table 3-B.2
1515
1516	   8:9  '00'=Stereo
1517		'01'=JointStereo
1518		'10'=Dual
1519		'11'=Mono
1520
1521		.. note::
1522
1523			The cx23415 cannot decode Joint Stereo properly.
1524
1525	  10:11 Mode Extension used in joint_stereo mode.
1526		In Layer I and II they indicate which subbands are in
1527		intensity_stereo. All other subbands are coded in stereo.
1528		    '00' subbands 4-31 in intensity_stereo, bound==4
1529		    '01' subbands 8-31 in intensity_stereo, bound==8
1530		    '10' subbands 12-31 in intensity_stereo, bound==12
1531		    '11' subbands 16-31 in intensity_stereo, bound==16
1532
1533	  12:13 Emphasis:
1534		    '00' None
1535		    '01' 50/15uS
1536		    '10' reserved
1537		    '11' CCITT J.17
1538
1539	  14 	CRC:
1540		    '0' off
1541		    '1' on
1542
1543	  15    Copyright:
1544		    '0' off
1545		    '1' on
1546
1547	  16    Generation:
1548		    '0' copy
1549		    '1' original
1550
1551
1552
1553CX2341X_ENC_HALT_FW
1554~~~~~~~~~~~~~~~~~~~
1555
1556Enum: 195/0xC3
1557
1558Description
1559^^^^^^^^^^^
1560
1561The firmware is halted and no further API calls are serviced until the
1562firmware is uploaded again.
1563
1564
1565
1566CX2341X_ENC_GET_VERSION
1567~~~~~~~~~~~~~~~~~~~~~~~
1568
1569Enum: 196/0xC4
1570
1571Description
1572^^^^^^^^^^^
1573
1574Returns the version of the encoder firmware.
1575
1576Result[0]
1577^^^^^^^^^
1578
1579Version bitmask:
1580- Bits  0:15 build
1581- Bits 16:23 minor
1582- Bits 24:31 major
1583
1584
1585
1586CX2341X_ENC_SET_GOP_CLOSURE
1587~~~~~~~~~~~~~~~~~~~~~~~~~~~
1588
1589Enum: 197/0xC5
1590
1591Description
1592^^^^^^^^^^^
1593
1594Assigns the GOP open/close property.
1595
1596Param[0]
1597^^^^^^^^
1598
1599- 0=Open
1600- 1=Closed
1601
1602
1603
1604CX2341X_ENC_GET_SEQ_END
1605~~~~~~~~~~~~~~~~~~~~~~~
1606
1607Enum: 198/0xC6
1608
1609Description
1610^^^^^^^^^^^
1611
1612Obtains the sequence end code of the encoder's buffer. When a capture
1613is started a number of interrupts are still generated, the last of
1614which will have Result[0] set to 1 and Result[1] will contain the size
1615of the buffer.
1616
1617Result[0]
1618^^^^^^^^^
1619
1620State of the transfer (1 if last buffer)
1621
1622Result[1]
1623^^^^^^^^^
1624
1625If Result[0] is 1, this contains the size of the last buffer, undefined
1626otherwise.
1627
1628
1629
1630CX2341X_ENC_SET_PGM_INDEX_INFO
1631~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1632
1633Enum: 199/0xC7
1634
1635Description
1636^^^^^^^^^^^
1637
1638Sets the Program Index Information.
1639The information is stored as follows:
1640
1641.. code-block:: c
1642
1643	struct info {
1644		u32 length;		// Length of this frame
1645		u32 offset_low;		// Offset in the file of the
1646		u32 offset_high;	// start of this frame
1647		u32 mask1;		// Bits 0-2 are the type mask:
1648					// 1=I, 2=P, 4=B
1649					// 0=End of Program Index, other fields
1650					//   are invalid.
1651		u32 pts;		// The PTS of the frame
1652		u32 mask2;		// Bit 0 is bit 32 of the pts.
1653	};
1654	u32 table_ptr;
1655	struct info index[400];
1656
1657The table_ptr is the encoder memory address in the table were
1658*new* entries will be written.
1659
1660.. note:: This is a ringbuffer, so the table_ptr will wraparound.
1661
1662Param[0]
1663^^^^^^^^
1664
1665Picture Mask:
1666- 0=No index capture
1667- 1=I frames
1668- 3=I,P frames
1669- 7=I,P,B frames
1670
1671(Seems to be ignored, it always indexes I, P and B frames)
1672
1673Param[1]
1674^^^^^^^^
1675
1676Elements requested (up to 400)
1677
1678Result[0]
1679^^^^^^^^^
1680
1681Offset in the encoder memory of the start of the table.
1682
1683Result[1]
1684^^^^^^^^^
1685
1686Number of allocated elements up to a maximum of Param[1]
1687
1688
1689
1690CX2341X_ENC_SET_VBI_CONFIG
1691~~~~~~~~~~~~~~~~~~~~~~~~~~
1692
1693Enum: 200/0xC8
1694
1695Description
1696^^^^^^^^^^^
1697
1698Configure VBI settings
1699
1700Param[0]
1701^^^^^^^^
1702
1703Bitmap:
1704
1705.. code-block:: none
1706
1707	    0    Mode '0' Sliced, '1' Raw
1708	    1:3  Insertion:
1709		     '000' insert in extension & user data
1710		     '001' insert in private packets
1711		     '010' separate stream and user data
1712		     '111' separate stream and private data
1713	    8:15 Stream ID (normally 0xBD)
1714
1715Param[1]
1716^^^^^^^^
1717
1718Frames per interrupt (max 8). Only valid in raw mode.
1719
1720Param[2]
1721^^^^^^^^
1722
1723Total raw VBI frames. Only valid in raw mode.
1724
1725Param[3]
1726^^^^^^^^
1727
1728Start codes
1729
1730Param[4]
1731^^^^^^^^
1732
1733Stop codes
1734
1735Param[5]
1736^^^^^^^^
1737
1738Lines per frame
1739
1740Param[6]
1741^^^^^^^^
1742
1743Byte per line
1744
1745Result[0]
1746^^^^^^^^^
1747
1748Observed frames per interrupt in raw mode only. Rage 1 to Param[1]
1749
1750Result[1]
1751^^^^^^^^^
1752
1753Observed number of frames in raw mode. Range 1 to Param[2]
1754
1755Result[2]
1756^^^^^^^^^
1757
1758Memory offset to start or raw VBI data
1759
1760
1761
1762CX2341X_ENC_SET_DMA_BLOCK_SIZE
1763~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1764
1765Enum: 201/0xC9
1766
1767Description
1768^^^^^^^^^^^
1769
1770Set DMA transfer block size
1771
1772Param[0]
1773^^^^^^^^
1774
1775DMA transfer block size in bytes or frames. When unit is bytes,
1776supported block sizes are 2^7, 2^8 and 2^9 bytes.
1777
1778Param[1]
1779^^^^^^^^
1780
1781Unit: 0=bytes, 1=frames
1782
1783
1784
1785CX2341X_ENC_GET_PREV_DMA_INFO_MB_10
1786~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1787
1788Enum: 202/0xCA
1789
1790Description
1791^^^^^^^^^^^
1792
1793Returns information on the previous DMA transfer in conjunction with
1794bit 27 of the interrupt mask. Uses mailbox 10.
1795
1796Result[0]
1797^^^^^^^^^
1798
1799Type of stream
1800
1801Result[1]
1802^^^^^^^^^
1803
1804Address Offset
1805
1806Result[2]
1807^^^^^^^^^
1808
1809Maximum size of transfer
1810
1811
1812
1813CX2341X_ENC_GET_PREV_DMA_INFO_MB_9
1814~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1815
1816Enum: 203/0xCB
1817
1818Description
1819^^^^^^^^^^^
1820
1821Returns information on the previous DMA transfer in conjunction with
1822bit 27 or 18 of the interrupt mask. Uses mailbox 9.
1823
1824Result[0]
1825^^^^^^^^^
1826
1827Status bits:
1828- 0   read completed
1829- 1   write completed
1830- 2   DMA read error
1831- 3   DMA write error
1832- 4   Scatter-Gather array error
1833
1834Result[1]
1835^^^^^^^^^
1836
1837DMA type
1838
1839Result[2]
1840^^^^^^^^^
1841
1842Presentation Time Stamp bits 0..31
1843
1844Result[3]
1845^^^^^^^^^
1846
1847Presentation Time Stamp bit 32
1848
1849
1850
1851CX2341X_ENC_SCHED_DMA_TO_HOST
1852~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1853
1854Enum: 204/0xCC
1855
1856Description
1857^^^^^^^^^^^
1858
1859Setup DMA to host operation
1860
1861Param[0]
1862^^^^^^^^
1863
1864Memory address of link list
1865
1866Param[1]
1867^^^^^^^^
1868
1869Length of link list (wtf: what units ???)
1870
1871Param[2]
1872^^^^^^^^
1873
1874DMA type (0=MPEG)
1875
1876
1877
1878CX2341X_ENC_INITIALIZE_INPUT
1879~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1880
1881Enum: 205/0xCD
1882
1883Description
1884^^^^^^^^^^^
1885
1886Initializes the video input
1887
1888
1889
1890CX2341X_ENC_SET_FRAME_DROP_RATE
1891~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1892
1893Enum: 208/0xD0
1894
1895Description
1896^^^^^^^^^^^
1897
1898For each frame captured, skip specified number of frames.
1899
1900Param[0]
1901^^^^^^^^
1902
1903Number of frames to skip
1904
1905
1906
1907CX2341X_ENC_PAUSE_ENCODER
1908~~~~~~~~~~~~~~~~~~~~~~~~~
1909
1910Enum: 210/0xD2
1911
1912Description
1913^^^^^^^^^^^
1914
1915During a pause condition, all frames are dropped instead of being encoded.
1916
1917Param[0]
1918^^^^^^^^
1919
1920- 0=Pause encoding
1921- 1=Continue encoding
1922
1923
1924
1925CX2341X_ENC_REFRESH_INPUT
1926~~~~~~~~~~~~~~~~~~~~~~~~~
1927
1928Enum: 211/0xD3
1929
1930Description
1931^^^^^^^^^^^
1932
1933Refreshes the video input
1934
1935
1936
1937CX2341X_ENC_SET_COPYRIGHT
1938~~~~~~~~~~~~~~~~~~~~~~~~~
1939
1940Enum: 212/0xD4
1941
1942Description
1943^^^^^^^^^^^
1944
1945Sets stream copyright property
1946
1947Param[0]
1948^^^^^^^^
1949
1950
1951- 0=Stream is not copyrighted
1952- 1=Stream is copyrighted
1953
1954
1955
1956CX2341X_ENC_SET_EVENT_NOTIFICATION
1957~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1958
1959Enum: 213/0xD5
1960
1961Description
1962^^^^^^^^^^^
1963
1964Setup firmware to notify the host about a particular event. Host must
1965unmask the interrupt bit.
1966
1967Param[0]
1968^^^^^^^^
1969
1970Event (0=refresh encoder input)
1971
1972Param[1]
1973^^^^^^^^
1974
1975Notification 0=disabled 1=enabled
1976
1977Param[2]
1978^^^^^^^^
1979
1980Interrupt bit
1981
1982Param[3]
1983^^^^^^^^
1984
1985Mailbox slot, -1 if no mailbox required.
1986
1987
1988
1989CX2341X_ENC_SET_NUM_VSYNC_LINES
1990~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1991
1992Enum: 214/0xD6
1993
1994Description
1995^^^^^^^^^^^
1996
1997Depending on the analog video decoder used, this assigns the number
1998of lines for field 1 and 2.
1999
2000Param[0]
2001^^^^^^^^
2002
2003Field 1 number of lines:
2004- 0x00EF for SAA7114
2005- 0x00F0 for SAA7115
2006- 0x0105 for Micronas
2007
2008Param[1]
2009^^^^^^^^
2010
2011Field 2 number of lines:
2012- 0x00EF for SAA7114
2013- 0x00F0 for SAA7115
2014- 0x0106 for Micronas
2015
2016
2017
2018CX2341X_ENC_SET_PLACEHOLDER
2019~~~~~~~~~~~~~~~~~~~~~~~~~~~
2020
2021Enum: 215/0xD7
2022
2023Description
2024^^^^^^^^^^^
2025
2026Provides a mechanism of inserting custom user data in the MPEG stream.
2027
2028Param[0]
2029^^^^^^^^
2030
2031- 0=extension & user data
2032- 1=private packet with stream ID 0xBD
2033
2034Param[1]
2035^^^^^^^^
2036
2037Rate at which to insert data, in units of frames (for private packet)
2038or GOPs (for ext. & user data)
2039
2040Param[2]
2041^^^^^^^^
2042
2043Number of data DWORDs (below) to insert
2044
2045Param[3]
2046^^^^^^^^
2047
2048Custom data 0
2049
2050Param[4]
2051^^^^^^^^
2052
2053Custom data 1
2054
2055Param[5]
2056^^^^^^^^
2057
2058Custom data 2
2059
2060Param[6]
2061^^^^^^^^
2062
2063Custom data 3
2064
2065Param[7]
2066^^^^^^^^
2067
2068Custom data 4
2069
2070Param[8]
2071^^^^^^^^
2072
2073Custom data 5
2074
2075Param[9]
2076^^^^^^^^
2077
2078Custom data 6
2079
2080Param[10]
2081^^^^^^^^^
2082
2083Custom data 7
2084
2085Param[11]
2086^^^^^^^^^
2087
2088Custom data 8
2089
2090
2091
2092CX2341X_ENC_MUTE_VIDEO
2093~~~~~~~~~~~~~~~~~~~~~~
2094
2095Enum: 217/0xD9
2096
2097Description
2098^^^^^^^^^^^
2099
2100Video muting
2101
2102Param[0]
2103^^^^^^^^
2104
2105Bit usage:
2106
2107.. code-block:: none
2108
2109	 0    	'0'=video not muted
2110		'1'=video muted, creates frames with the YUV color defined below
2111	 1:7  	Unused
2112	 8:15 	V chrominance information
2113	16:23 	U chrominance information
2114	24:31 	Y luminance information
2115
2116
2117
2118CX2341X_ENC_MUTE_AUDIO
2119~~~~~~~~~~~~~~~~~~~~~~
2120
2121Enum: 218/0xDA
2122
2123Description
2124^^^^^^^^^^^
2125
2126Audio muting
2127
2128Param[0]
2129^^^^^^^^
2130
2131- 0=audio not muted
2132- 1=audio muted (produces silent mpeg audio stream)
2133
2134
2135
2136CX2341X_ENC_SET_VERT_CROP_LINE
2137~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2138
2139Enum: 219/0xDB
2140
2141Description
2142^^^^^^^^^^^
2143
2144Something to do with 'Vertical Crop Line'
2145
2146Param[0]
2147^^^^^^^^
2148
2149If saa7114 and raw VBI capture and 60 Hz, then set to 10001.
2150Else 0.
2151
2152
2153
2154CX2341X_ENC_MISC
2155~~~~~~~~~~~~~~~~
2156
2157Enum: 220/0xDC
2158
2159Description
2160^^^^^^^^^^^
2161
2162Miscellaneous actions. Not known for 100% what it does. It's really a
2163sort of ioctl call. The first parameter is a command number, the second
2164the value.
2165
2166Param[0]
2167^^^^^^^^
2168
2169Command number:
2170
2171.. code-block:: none
2172
2173	 1=set initial SCR value when starting encoding (works).
2174	 2=set quality mode (apparently some test setting).
2175	 3=setup advanced VIM protection handling.
2176	   Always 1 for the cx23416 and 0 for cx23415.
2177	 4=generate DVD compatible PTS timestamps
2178	 5=USB flush mode
2179	 6=something to do with the quantization matrix
2180	 7=set navigation pack insertion for DVD: adds 0xbf (private stream 2)
2181	   packets to the MPEG. The size of these packets is 2048 bytes (including
2182	   the header of 6 bytes: 0x000001bf + length). The payload is zeroed and
2183	   it is up to the application to fill them in. These packets are apparently
2184	   inserted every four frames.
2185	 8=enable scene change detection (seems to be a failure)
2186	 9=set history parameters of the video input module
2187	10=set input field order of VIM
2188	11=set quantization matrix
2189	12=reset audio interface after channel change or input switch (has no argument).
2190	   Needed for the cx2584x, not needed for the mspx4xx, but it doesn't seem to
2191	   do any harm calling it regardless.
2192	13=set audio volume delay
2193	14=set audio delay
2194
2195
2196Param[1]
2197^^^^^^^^
2198
2199Command value.
2200
2201Decoder firmware API description
2202--------------------------------
2203
2204.. note:: this API is part of the decoder firmware, so it's cx23415 only.
2205
2206
2207
2208CX2341X_DEC_PING_FW
2209~~~~~~~~~~~~~~~~~~~
2210
2211Enum: 0/0x00
2212
2213Description
2214^^^^^^^^^^^
2215
2216This API call does nothing. It may be used to check if the firmware
2217is responding.
2218
2219
2220
2221CX2341X_DEC_START_PLAYBACK
2222~~~~~~~~~~~~~~~~~~~~~~~~~~
2223
2224Enum: 1/0x01
2225
2226Description
2227^^^^^^^^^^^
2228
2229Begin or resume playback.
2230
2231Param[0]
2232^^^^^^^^
2233
22340 based frame number in GOP to begin playback from.
2235
2236Param[1]
2237^^^^^^^^
2238
2239Specifies the number of muted audio frames to play before normal
2240audio resumes. (This is not implemented in the firmware, leave at 0)
2241
2242
2243
2244CX2341X_DEC_STOP_PLAYBACK
2245~~~~~~~~~~~~~~~~~~~~~~~~~
2246
2247Enum: 2/0x02
2248
2249Description
2250^^^^^^^^^^^
2251
2252Ends playback and clears all decoder buffers. If PTS is not zero,
2253playback stops at specified PTS.
2254
2255Param[0]
2256^^^^^^^^
2257
2258Display 0=last frame, 1=black
2259
2260.. note::
2261
2262	this takes effect immediately, so if you want to wait for a PTS,
2263	then use '0', otherwise the screen goes to black at once.
2264	You can call this later (even if there is no playback) with a 1 value
2265	to set the screen to black.
2266
2267Param[1]
2268^^^^^^^^
2269
2270PTS low
2271
2272Param[2]
2273^^^^^^^^
2274
2275PTS high
2276
2277
2278
2279CX2341X_DEC_SET_PLAYBACK_SPEED
2280~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2281
2282Enum: 3/0x03
2283
2284Description
2285^^^^^^^^^^^
2286
2287Playback stream at speed other than normal. There are two modes of
2288operation:
2289
2290	- Smooth: host transfers entire stream and firmware drops unused
2291	  frames.
2292	- Coarse: host drops frames based on indexing as required to achieve
2293	  desired speed.
2294
2295Param[0]
2296^^^^^^^^
2297
2298.. code-block:: none
2299
2300	Bitmap:
2301	    0:7  0 normal
2302		 1 fast only "1.5 times"
2303		 n nX fast, 1/nX slow
2304	    30   Framedrop:
2305		     '0' during 1.5 times play, every other B frame is dropped
2306		     '1' during 1.5 times play, stream is unchanged (bitrate
2307			 must not exceed 8mbps)
2308	    31   Speed:
2309		     '0' slow
2310		     '1' fast
2311
2312.. note::
2313
2314	n is limited to 2. Anything higher does not result in
2315	faster playback. Instead the host should start dropping frames.
2316
2317Param[1]
2318^^^^^^^^
2319
2320Direction: 0=forward, 1=reverse
2321
2322.. note::
2323
2324	to make reverse playback work you have to write full GOPs in
2325	reverse order.
2326
2327Param[2]
2328^^^^^^^^
2329
2330.. code-block:: none
2331
2332	Picture mask:
2333	    1=I frames
2334	    3=I, P frames
2335	    7=I, P, B frames
2336
2337Param[3]
2338^^^^^^^^
2339
2340B frames per GOP (for reverse play only)
2341
2342.. note::
2343
2344	for reverse playback the Picture Mask should be set to I or I, P.
2345	Adding B frames to the mask will result in corrupt video. This field
2346	has to be set to the correct value in order to keep the timing correct.
2347
2348Param[4]
2349^^^^^^^^
2350
2351Mute audio: 0=disable, 1=enable
2352
2353Param[5]
2354^^^^^^^^
2355
2356Display 0=frame, 1=field
2357
2358Param[6]
2359^^^^^^^^
2360
2361Specifies the number of muted audio frames to play before normal audio
2362resumes. (Not implemented in the firmware, leave at 0)
2363
2364
2365
2366CX2341X_DEC_STEP_VIDEO
2367~~~~~~~~~~~~~~~~~~~~~~
2368
2369Enum: 5/0x05
2370
2371Description
2372^^^^^^^^^^^
2373
2374Each call to this API steps the playback to the next unit defined below
2375in the current playback direction.
2376
2377Param[0]
2378^^^^^^^^
2379
23800=frame, 1=top field, 2=bottom field
2381
2382
2383
2384CX2341X_DEC_SET_DMA_BLOCK_SIZE
2385~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2386
2387Enum: 8/0x08
2388
2389Description
2390^^^^^^^^^^^
2391
2392Set DMA transfer block size. Counterpart to API 0xC9
2393
2394Param[0]
2395^^^^^^^^
2396
2397DMA transfer block size in bytes. A different size may be specified
2398when issuing the DMA transfer command.
2399
2400
2401
2402CX2341X_DEC_GET_XFER_INFO
2403~~~~~~~~~~~~~~~~~~~~~~~~~
2404
2405Enum: 9/0x09
2406
2407Description
2408^^^^^^^^^^^
2409
2410This API call may be used to detect an end of stream condition.
2411
2412Result[0]
2413^^^^^^^^^
2414
2415Stream type
2416
2417Result[1]
2418^^^^^^^^^
2419
2420Address offset
2421
2422Result[2]
2423^^^^^^^^^
2424
2425Maximum bytes to transfer
2426
2427Result[3]
2428^^^^^^^^^
2429
2430Buffer fullness
2431
2432
2433
2434CX2341X_DEC_GET_DMA_STATUS
2435~~~~~~~~~~~~~~~~~~~~~~~~~~
2436
2437Enum: 10/0x0A
2438
2439Description
2440^^^^^^^^^^^
2441
2442Status of the last DMA transfer
2443
2444Result[0]
2445^^^^^^^^^
2446
2447Bit 1 set means transfer complete
2448Bit 2 set means DMA error
2449Bit 3 set means linked list error
2450
2451Result[1]
2452^^^^^^^^^
2453
2454DMA type: 0=MPEG, 1=OSD, 2=YUV
2455
2456
2457
2458CX2341X_DEC_SCHED_DMA_FROM_HOST
2459~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2460
2461Enum: 11/0x0B
2462
2463Description
2464^^^^^^^^^^^
2465
2466Setup DMA from host operation. Counterpart to API 0xCC
2467
2468Param[0]
2469^^^^^^^^
2470
2471Memory address of link list
2472
2473Param[1]
2474^^^^^^^^
2475
2476Total # of bytes to transfer
2477
2478Param[2]
2479^^^^^^^^
2480
2481DMA type (0=MPEG, 1=OSD, 2=YUV)
2482
2483
2484
2485CX2341X_DEC_PAUSE_PLAYBACK
2486~~~~~~~~~~~~~~~~~~~~~~~~~~
2487
2488Enum: 13/0x0D
2489
2490Description
2491^^^^^^^^^^^
2492
2493Freeze playback immediately. In this mode, when internal buffers are
2494full, no more data will be accepted and data request IRQs will be
2495masked.
2496
2497Param[0]
2498^^^^^^^^
2499
2500Display: 0=last frame, 1=black
2501
2502
2503
2504CX2341X_DEC_HALT_FW
2505~~~~~~~~~~~~~~~~~~~
2506
2507Enum: 14/0x0E
2508
2509Description
2510^^^^^^^^^^^
2511
2512The firmware is halted and no further API calls are serviced until
2513the firmware is uploaded again.
2514
2515
2516
2517CX2341X_DEC_SET_STANDARD
2518~~~~~~~~~~~~~~~~~~~~~~~~
2519
2520Enum: 16/0x10
2521
2522Description
2523^^^^^^^^^^^
2524
2525Selects display standard
2526
2527Param[0]
2528^^^^^^^^
2529
25300=NTSC, 1=PAL
2531
2532
2533
2534CX2341X_DEC_GET_VERSION
2535~~~~~~~~~~~~~~~~~~~~~~~
2536
2537Enum: 17/0x11
2538
2539Description
2540^^^^^^^^^^^
2541
2542Returns decoder firmware version information
2543
2544Result[0]
2545^^^^^^^^^
2546
2547Version bitmask:
2548	- Bits  0:15 build
2549	- Bits 16:23 minor
2550	- Bits 24:31 major
2551
2552
2553
2554CX2341X_DEC_SET_STREAM_INPUT
2555~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2556
2557Enum: 20/0x14
2558
2559Description
2560^^^^^^^^^^^
2561
2562Select decoder stream input port
2563
2564Param[0]
2565^^^^^^^^
2566
25670=memory (default), 1=streaming
2568
2569
2570
2571CX2341X_DEC_GET_TIMING_INFO
2572~~~~~~~~~~~~~~~~~~~~~~~~~~~
2573
2574Enum: 21/0x15
2575
2576Description
2577^^^^^^^^^^^
2578
2579Returns timing information from start of playback
2580
2581Result[0]
2582^^^^^^^^^
2583
2584Frame count by decode order
2585
2586Result[1]
2587^^^^^^^^^
2588
2589Video PTS bits 0:31 by display order
2590
2591Result[2]
2592^^^^^^^^^
2593
2594Video PTS bit 32 by display order
2595
2596Result[3]
2597^^^^^^^^^
2598
2599SCR bits 0:31 by display order
2600
2601Result[4]
2602^^^^^^^^^
2603
2604SCR bit 32 by display order
2605
2606
2607
2608CX2341X_DEC_SET_AUDIO_MODE
2609~~~~~~~~~~~~~~~~~~~~~~~~~~
2610
2611Enum: 22/0x16
2612
2613Description
2614^^^^^^^^^^^
2615
2616Select audio mode
2617
2618Param[0]
2619^^^^^^^^
2620
2621Dual mono mode action
2622	0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
2623
2624Param[1]
2625^^^^^^^^
2626
2627Stereo mode action:
2628	0=Stereo, 1=Left, 2=Right, 3=Mono, 4=Swap, -1=Unchanged
2629
2630
2631
2632CX2341X_DEC_SET_EVENT_NOTIFICATION
2633~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2634
2635Enum: 23/0x17
2636
2637Description
2638^^^^^^^^^^^
2639
2640Setup firmware to notify the host about a particular event.
2641Counterpart to API 0xD5
2642
2643Param[0]
2644^^^^^^^^
2645
2646Event:
2647	- 0=Audio mode change between mono, (joint) stereo and dual channel.
2648	- 3=Decoder started
2649	- 4=Unknown: goes off 10-15 times per second while decoding.
2650	- 5=Some sync event: goes off once per frame.
2651
2652Param[1]
2653^^^^^^^^
2654
2655Notification 0=disabled, 1=enabled
2656
2657Param[2]
2658^^^^^^^^
2659
2660Interrupt bit
2661
2662Param[3]
2663^^^^^^^^
2664
2665Mailbox slot, -1 if no mailbox required.
2666
2667
2668
2669CX2341X_DEC_SET_DISPLAY_BUFFERS
2670~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2671
2672Enum: 24/0x18
2673
2674Description
2675^^^^^^^^^^^
2676
2677Number of display buffers. To decode all frames in reverse playback you
2678must use nine buffers.
2679
2680Param[0]
2681^^^^^^^^
2682
26830=six buffers, 1=nine buffers
2684
2685
2686
2687CX2341X_DEC_EXTRACT_VBI
2688~~~~~~~~~~~~~~~~~~~~~~~
2689
2690Enum: 25/0x19
2691
2692Description
2693^^^^^^^^^^^
2694
2695Extracts VBI data
2696
2697Param[0]
2698^^^^^^^^
2699
27000=extract from extension & user data, 1=extract from private packets
2701
2702Result[0]
2703^^^^^^^^^
2704
2705VBI table location
2706
2707Result[1]
2708^^^^^^^^^
2709
2710VBI table size
2711
2712
2713
2714CX2341X_DEC_SET_DECODER_SOURCE
2715~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2716
2717Enum: 26/0x1A
2718
2719Description
2720^^^^^^^^^^^
2721
2722Selects decoder source. Ensure that the parameters passed to this
2723API match the encoder settings.
2724
2725Param[0]
2726^^^^^^^^
2727
2728Mode: 0=MPEG from host, 1=YUV from encoder, 2=YUV from host
2729
2730Param[1]
2731^^^^^^^^
2732
2733YUV picture width
2734
2735Param[2]
2736^^^^^^^^
2737
2738YUV picture height
2739
2740Param[3]
2741^^^^^^^^
2742
2743Bitmap: see Param[0] of API 0xBD
2744
2745
2746
2747CX2341X_DEC_SET_PREBUFFERING
2748~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2749
2750Enum: 30/0x1E
2751
2752Description
2753^^^^^^^^^^^
2754
2755Decoder prebuffering, when enabled up to 128KB are buffered for
2756streams <8mpbs or 640KB for streams >8mbps
2757
2758Param[0]
2759^^^^^^^^
2760
27610=off, 1=on
2762
2763PVR350 Video decoder registers 0x02002800 -> 0x02002B00
2764-------------------------------------------------------
2765
2766Author: Ian Armstrong <ian@iarmst.demon.co.uk>
2767
2768Version: v0.4
2769
2770Date: 12 March 2007
2771
2772
2773This list has been worked out through trial and error. There will be mistakes
2774and omissions. Some registers have no obvious effect so it's hard to say what
2775they do, while others interact with each other, or require a certain load
2776sequence. Horizontal filter setup is one example, with six registers working
2777in unison and requiring a certain load sequence to correctly configure. The
2778indexed colour palette is much easier to set at just two registers, but again
2779it requires a certain load sequence.
2780
2781Some registers are fussy about what they are set to. Load in a bad value & the
2782decoder will fail. A firmware reload will often recover, but sometimes a reset
2783is required. For registers containing size information, setting them to 0 is
2784generally a bad idea. For other control registers i.e. 2878, you'll only find
2785out what values are bad when it hangs.
2786
2787.. code-block:: none
2788
2789	--------------------------------------------------------------------------------
2790	2800
2791	bit 0
2792		Decoder enable
2793		0 = disable
2794		1 = enable
2795	--------------------------------------------------------------------------------
2796	2804
2797	bits 0:31
2798		Decoder horizontal Y alias register 1
2799	---------------
2800	2808
2801	bits 0:31
2802		Decoder horizontal Y alias register 2
2803	---------------
2804	280C
2805	bits 0:31
2806		Decoder horizontal Y alias register 3
2807	---------------
2808	2810
2809	bits 0:31
2810		Decoder horizontal Y alias register 4
2811	---------------
2812	2814
2813	bits 0:31
2814		Decoder horizontal Y alias register 5
2815	---------------
2816	2818
2817	bits 0:31
2818		Decoder horizontal Y alias trigger
2819
2820	These six registers control the horizontal aliasing filter for the Y plane.
2821	The first five registers must all be loaded before accessing the trigger
2822	(2818), as this register actually clocks the data through for the first
2823	five.
2824
2825	To correctly program set the filter, this whole procedure must be done 16
2826	times. The actual register contents are copied from a lookup-table in the
2827	firmware which contains 4 different filter settings.
2828
2829	--------------------------------------------------------------------------------
2830	281C
2831	bits 0:31
2832		Decoder horizontal UV alias register 1
2833	---------------
2834	2820
2835	bits 0:31
2836		Decoder horizontal UV alias register 2
2837	---------------
2838	2824
2839	bits 0:31
2840		Decoder horizontal UV alias register 3
2841	---------------
2842	2828
2843	bits 0:31
2844		Decoder horizontal UV alias register 4
2845	---------------
2846	282C
2847	bits 0:31
2848		Decoder horizontal UV alias register 5
2849	---------------
2850	2830
2851	bits 0:31
2852		Decoder horizontal UV alias trigger
2853
2854	These six registers control the horizontal aliasing for the UV plane.
2855	Operation is the same as the Y filter, with 2830 being the trigger
2856	register.
2857
2858	--------------------------------------------------------------------------------
2859	2834
2860	bits 0:15
2861		Decoder Y source width in pixels
2862
2863	bits 16:31
2864		Decoder Y destination width in pixels
2865	---------------
2866	2838
2867	bits 0:15
2868		Decoder UV source width in pixels
2869
2870	bits 16:31
2871		Decoder UV destination width in pixels
2872
2873	NOTE: For both registers, the resulting image must be fully visible on
2874	screen. If the image exceeds the right edge both the source and destination
2875	size must be adjusted to reflect the visible portion. For the source width,
2876	you must take into account the scaling when calculating the new value.
2877	--------------------------------------------------------------------------------
2878
2879	283C
2880	bits 0:31
2881		Decoder Y horizontal scaling
2882			Normally = Reg 2854 >> 2
2883	---------------
2884	2840
2885	bits 0:31
2886		Decoder ?? unknown - horizontal scaling
2887		Usually 0x00080514
2888	---------------
2889	2844
2890	bits 0:31
2891		Decoder UV horizontal scaling
2892		Normally = Reg 2854 >> 2
2893	---------------
2894	2848
2895	bits 0:31
2896		Decoder ?? unknown - horizontal scaling
2897		Usually 0x00100514
2898	---------------
2899	284C
2900	bits 0:31
2901		Decoder ?? unknown - Y plane
2902		Usually 0x00200020
2903	---------------
2904	2850
2905	bits 0:31
2906		Decoder ?? unknown - UV plane
2907		Usually 0x00200020
2908	---------------
2909	2854
2910	bits 0:31
2911		Decoder 'master' value for horizontal scaling
2912	---------------
2913	2858
2914	bits 0:31
2915		Decoder ?? unknown
2916		Usually 0
2917	---------------
2918	285C
2919	bits 0:31
2920		Decoder ?? unknown
2921		Normally = Reg 2854 >> 1
2922	---------------
2923	2860
2924	bits 0:31
2925		Decoder ?? unknown
2926		Usually 0
2927	---------------
2928	2864
2929	bits 0:31
2930		Decoder ?? unknown
2931		Normally = Reg 2854 >> 1
2932	---------------
2933	2868
2934	bits 0:31
2935		Decoder ?? unknown
2936		Usually 0
2937
2938	Most of these registers either control horizontal scaling, or appear linked
2939	to it in some way. Register 2854 contains the 'master' value & the other
2940	registers can be calculated from that one. You must also remember to
2941	correctly set the divider in Reg 2874.
2942
2943	To enlarge:
2944		Reg 2854 = (source_width * 0x00200000) / destination_width
2945		Reg 2874 = No divide
2946
2947	To reduce from full size down to half size:
2948		Reg 2854 = (source_width/2 * 0x00200000) / destination width
2949		Reg 2874 = Divide by 2
2950
2951	To reduce from half size down to quarter size:
2952		Reg 2854 = (source_width/4 * 0x00200000) / destination width
2953		Reg 2874 = Divide by 4
2954
2955	The result is always rounded up.
2956
2957	--------------------------------------------------------------------------------
2958	286C
2959	bits 0:15
2960		Decoder horizontal Y buffer offset
2961
2962	bits 15:31
2963		Decoder horizontal UV buffer offset
2964
2965	Offset into the video image buffer. If the offset is gradually incremented,
2966	the on screen image will move left & wrap around higher up on the right.
2967
2968	--------------------------------------------------------------------------------
2969	2870
2970	bits 0:15
2971		Decoder horizontal Y output offset
2972
2973	bits 16:31
2974		Decoder horizontal UV output offset
2975
2976	Offsets the actual video output. Controls output alignment of the Y & UV
2977	planes. The higher the value, the greater the shift to the left. Use
2978	reg 2890 to move the image right.
2979
2980	--------------------------------------------------------------------------------
2981	2874
2982	bits 0:1
2983		Decoder horizontal Y output size divider
2984		00 = No divide
2985		01 = Divide by 2
2986		10 = Divide by 3
2987
2988	bits 4:5
2989		Decoder horizontal UV output size divider
2990		00 = No divide
2991		01 = Divide by 2
2992		10 = Divide by 3
2993
2994	bit 8
2995		Decoder ?? unknown
2996		0 = Normal
2997		1 = Affects video output levels
2998
2999	bit 16
3000		Decoder ?? unknown
3001		0 = Normal
3002		1 = Disable horizontal filter
3003
3004	--------------------------------------------------------------------------------
3005	2878
3006	bit 0
3007		?? unknown
3008
3009	bit 1
3010		osd on/off
3011		0 = osd off
3012		1 = osd on
3013
3014	bit 2
3015		Decoder + osd video timing
3016		0 = NTSC
3017		1 = PAL
3018
3019	bits 3:4
3020		?? unknown
3021
3022	bit 5
3023		Decoder + osd
3024		Swaps upper & lower fields
3025
3026	--------------------------------------------------------------------------------
3027	287C
3028	bits 0:10
3029		Decoder & osd ?? unknown
3030		Moves entire screen horizontally. Starts at 0x005 with the screen
3031		shifted heavily to the right. Incrementing in steps of 0x004 will
3032		gradually shift the screen to the left.
3033
3034	bits 11:31
3035		?? unknown
3036
3037	Normally contents are 0x00101111 (NTSC) or 0x1010111d (PAL)
3038
3039	--------------------------------------------------------------------------------
3040	2880  --------    ?? unknown
3041	2884  --------    ?? unknown
3042	--------------------------------------------------------------------------------
3043	2888
3044	bit 0
3045		Decoder + osd ?? unknown
3046		0 = Normal
3047		1 = Misaligned fields (Correctable through 289C & 28A4)
3048
3049	bit 4
3050		?? unknown
3051
3052	bit 8
3053		?? unknown
3054
3055	Warning: Bad values will require a firmware reload to recover.
3056			Known to be bad are 0x000,0x011,0x100,0x111
3057	--------------------------------------------------------------------------------
3058	288C
3059	bits 0:15
3060		osd ?? unknown
3061		Appears to affect the osd position stability. The higher the value the
3062		more unstable it becomes. Decoder output remains stable.
3063
3064	bits 16:31
3065		osd ?? unknown
3066		Same as bits 0:15
3067
3068	--------------------------------------------------------------------------------
3069	2890
3070	bits 0:11
3071		Decoder output horizontal offset.
3072
3073	Horizontal offset moves the video image right. A small left shift is
3074	possible, but it's better to use reg 2870 for that due to its greater
3075	range.
3076
3077	NOTE: Video corruption will occur if video window is shifted off the right
3078	edge. To avoid this read the notes for 2834 & 2838.
3079	--------------------------------------------------------------------------------
3080	2894
3081	bits 0:23
3082		Decoder output video surround colour.
3083
3084	Contains the colour (in yuv) used to fill the screen when the video is
3085	running in a window.
3086	--------------------------------------------------------------------------------
3087	2898
3088	bits 0:23
3089		Decoder video window colour
3090		Contains the colour (in yuv) used to fill the video window when the
3091		video is turned off.
3092
3093	bit 24
3094		Decoder video output
3095		0 = Video on
3096		1 = Video off
3097
3098	bit 28
3099		Decoder plane order
3100		0 = Y,UV
3101		1 = UV,Y
3102
3103	bit 29
3104		Decoder second plane byte order
3105		0 = Normal (UV)
3106		1 = Swapped (VU)
3107
3108	In normal usage, the first plane is Y & the second plane is UV. Though the
3109	order of the planes can be swapped, only the byte order of the second plane
3110	can be swapped. This isn't much use for the Y plane, but can be useful for
3111	the UV plane.
3112
3113	--------------------------------------------------------------------------------
3114	289C
3115	bits 0:15
3116		Decoder vertical field offset 1
3117
3118	bits 16:31
3119		Decoder vertical field offset 2
3120
3121	Controls field output vertical alignment. The higher the number, the lower
3122	the image on screen. Known starting values are 0x011E0017 (NTSC) &
3123	0x01500017 (PAL)
3124	--------------------------------------------------------------------------------
3125	28A0
3126	bits 0:15
3127		Decoder & osd width in pixels
3128
3129	bits 16:31
3130		Decoder & osd height in pixels
3131
3132	All output from the decoder & osd are disabled beyond this area. Decoder
3133	output will simply go black outside of this region. If the osd tries to
3134	exceed this area it will become corrupt.
3135	--------------------------------------------------------------------------------
3136	28A4
3137	bits 0:11
3138		osd left shift.
3139
3140	Has a range of 0x770->0x7FF. With the exception of 0, any value outside of
3141	this range corrupts the osd.
3142	--------------------------------------------------------------------------------
3143	28A8
3144	bits 0:15
3145		osd vertical field offset 1
3146
3147	bits 16:31
3148		osd vertical field offset 2
3149
3150	Controls field output vertical alignment. The higher the number, the lower
3151	the image on screen. Known starting values are 0x011E0017 (NTSC) &
3152	0x01500017 (PAL)
3153	--------------------------------------------------------------------------------
3154	28AC  --------    ?? unknown
3155	|
3156	V
3157	28BC  --------    ?? unknown
3158	--------------------------------------------------------------------------------
3159	28C0
3160	bit 0
3161		Current output field
3162		0 = first field
3163		1 = second field
3164
3165	bits 16:31
3166		Current scanline
3167		The scanline counts from the top line of the first field
3168		through to the last line of the second field.
3169	--------------------------------------------------------------------------------
3170	28C4  --------    ?? unknown
3171	|
3172	V
3173	28F8  --------    ?? unknown
3174	--------------------------------------------------------------------------------
3175	28FC
3176	bit 0
3177		?? unknown
3178		0 = Normal
3179		1 = Breaks decoder & osd output
3180	--------------------------------------------------------------------------------
3181	2900
3182	bits 0:31
3183		Decoder vertical Y alias register 1
3184	---------------
3185	2904
3186	bits 0:31
3187		Decoder vertical Y alias register 2
3188	---------------
3189	2908
3190	bits 0:31
3191		Decoder vertical Y alias trigger
3192
3193	These three registers control the vertical aliasing filter for the Y plane.
3194	Operation is similar to the horizontal Y filter (2804). The only real
3195	difference is that there are only two registers to set before accessing
3196	the trigger register (2908). As for the horizontal filter, the values are
3197	taken from a lookup table in the firmware, and the procedure must be
3198	repeated 16 times to fully program the filter.
3199	--------------------------------------------------------------------------------
3200	290C
3201	bits 0:31
3202		Decoder vertical UV alias register 1
3203	---------------
3204	2910
3205	bits 0:31
3206		Decoder vertical UV alias register 2
3207	---------------
3208	2914
3209	bits 0:31
3210		Decoder vertical UV alias trigger
3211
3212	These three registers control the vertical aliasing filter for the UV
3213	plane. Operation is the same as the Y filter, with 2914 being the trigger.
3214	--------------------------------------------------------------------------------
3215	2918
3216	bits 0:15
3217		Decoder Y source height in pixels
3218
3219	bits 16:31
3220		Decoder Y destination height in pixels
3221	---------------
3222	291C
3223	bits 0:15
3224		Decoder UV source height in pixels divided by 2
3225
3226	bits 16:31
3227		Decoder UV destination height in pixels
3228
3229	NOTE: For both registers, the resulting image must be fully visible on
3230	screen. If the image exceeds the bottom edge both the source and
3231	destination size must be adjusted to reflect the visible portion. For the
3232	source height, you must take into account the scaling when calculating the
3233	new value.
3234	--------------------------------------------------------------------------------
3235	2920
3236	bits 0:31
3237		Decoder Y vertical scaling
3238		Normally = Reg 2930 >> 2
3239	---------------
3240	2924
3241	bits 0:31
3242		Decoder Y vertical scaling
3243		Normally = Reg 2920 + 0x514
3244	---------------
3245	2928
3246	bits 0:31
3247		Decoder UV vertical scaling
3248		When enlarging = Reg 2930 >> 2
3249		When reducing = Reg 2930 >> 3
3250	---------------
3251	292C
3252	bits 0:31
3253		Decoder UV vertical scaling
3254		Normally = Reg 2928 + 0x514
3255	---------------
3256	2930
3257	bits 0:31
3258		Decoder 'master' value for vertical scaling
3259	---------------
3260	2934
3261	bits 0:31
3262		Decoder ?? unknown - Y vertical scaling
3263	---------------
3264	2938
3265	bits 0:31
3266		Decoder Y vertical scaling
3267		Normally = Reg 2930
3268	---------------
3269	293C
3270	bits 0:31
3271		Decoder ?? unknown - Y vertical scaling
3272	---------------
3273	2940
3274	bits 0:31
3275		Decoder UV vertical scaling
3276		When enlarging = Reg 2930 >> 1
3277		When reducing = Reg 2930
3278	---------------
3279	2944
3280	bits 0:31
3281		Decoder ?? unknown - UV vertical scaling
3282	---------------
3283	2948
3284	bits 0:31
3285		Decoder UV vertical scaling
3286		Normally = Reg 2940
3287	---------------
3288	294C
3289	bits 0:31
3290		Decoder ?? unknown - UV vertical scaling
3291
3292	Most of these registers either control vertical scaling, or appear linked
3293	to it in some way. Register 2930 contains the 'master' value & all other
3294	registers can be calculated from that one. You must also remember to
3295	correctly set the divider in Reg 296C
3296
3297	To enlarge:
3298		Reg 2930 = (source_height * 0x00200000) / destination_height
3299		Reg 296C = No divide
3300
3301	To reduce from full size down to half size:
3302		Reg 2930 = (source_height/2 * 0x00200000) / destination height
3303		Reg 296C = Divide by 2
3304
3305	To reduce from half down to quarter.
3306		Reg 2930 = (source_height/4 * 0x00200000) / destination height
3307		Reg 296C = Divide by 4
3308
3309	--------------------------------------------------------------------------------
3310	2950
3311	bits 0:15
3312		Decoder Y line index into display buffer, first field
3313
3314	bits 16:31
3315		Decoder Y vertical line skip, first field
3316	--------------------------------------------------------------------------------
3317	2954
3318	bits 0:15
3319		Decoder Y line index into display buffer, second field
3320
3321	bits 16:31
3322		Decoder Y vertical line skip, second field
3323	--------------------------------------------------------------------------------
3324	2958
3325	bits 0:15
3326		Decoder UV line index into display buffer, first field
3327
3328	bits 16:31
3329		Decoder UV vertical line skip, first field
3330	--------------------------------------------------------------------------------
3331	295C
3332	bits 0:15
3333		Decoder UV line index into display buffer, second field
3334
3335	bits 16:31
3336		Decoder UV vertical line skip, second field
3337	--------------------------------------------------------------------------------
3338	2960
3339	bits 0:15
3340		Decoder destination height minus 1
3341
3342	bits 16:31
3343		Decoder destination height divided by 2
3344	--------------------------------------------------------------------------------
3345	2964
3346	bits 0:15
3347		Decoder Y vertical offset, second field
3348
3349	bits 16:31
3350		Decoder Y vertical offset, first field
3351
3352	These two registers shift the Y plane up. The higher the number, the
3353	greater the shift.
3354	--------------------------------------------------------------------------------
3355	2968
3356	bits 0:15
3357		Decoder UV vertical offset, second field
3358
3359	bits 16:31
3360		Decoder UV vertical offset, first field
3361
3362	These two registers shift the UV plane up. The higher the number, the
3363	greater the shift.
3364	--------------------------------------------------------------------------------
3365	296C
3366	bits 0:1
3367		Decoder vertical Y output size divider
3368		00 = No divide
3369		01 = Divide by 2
3370		10 = Divide by 4
3371
3372	bits 8:9
3373		Decoder vertical UV output size divider
3374		00 = No divide
3375		01 = Divide by 2
3376		10 = Divide by 4
3377	--------------------------------------------------------------------------------
3378	2970
3379	bit 0
3380		Decoder ?? unknown
3381		0 = Normal
3382		1 = Affect video output levels
3383
3384	bit 16
3385		Decoder ?? unknown
3386		0 = Normal
3387		1 = Disable vertical filter
3388
3389	--------------------------------------------------------------------------------
3390	2974  --------   ?? unknown
3391	|
3392	V
3393	29EF  --------   ?? unknown
3394	--------------------------------------------------------------------------------
3395	2A00
3396	bits 0:2
3397		osd colour mode
3398		000 = 8 bit indexed
3399		001 = 16 bit (565)
3400		010 = 15 bit (555)
3401		011 = 12 bit (444)
3402		100 = 32 bit (8888)
3403
3404	bits 4:5
3405		osd display bpp
3406		01 = 8 bit
3407		10 = 16 bit
3408		11 = 32 bit
3409
3410	bit 8
3411		osd global alpha
3412		0 = Off
3413		1 = On
3414
3415	bit 9
3416		osd local alpha
3417		0 = Off
3418		1 = On
3419
3420	bit 10
3421		osd colour key
3422		0 = Off
3423		1 = On
3424
3425	bit 11
3426		osd ?? unknown
3427		Must be 1
3428
3429	bit 13
3430		osd colour space
3431		0 = ARGB
3432		1 = AYVU
3433
3434	bits 16:31
3435		osd ?? unknown
3436		Must be 0x001B (some kind of buffer pointer ?)
3437
3438	When the bits-per-pixel is set to 8, the colour mode is ignored and
3439	assumed to be 8 bit indexed. For 16 & 32 bits-per-pixel the colour depth
3440	is honoured, and when using a colour depth that requires fewer bytes than
3441	allocated the extra bytes are used as padding. So for a 32 bpp with 8 bit
3442	index colour, there are 3 padding bytes per pixel. It's also possible to
3443	select 16bpp with a 32 bit colour mode. This results in the pixel width
3444	being doubled, but the color key will not work as expected in this mode.
3445
3446	Colour key is as it suggests. You designate a colour which will become
3447	completely transparent. When using 565, 555 or 444 colour modes, the
3448	colour key is always 16 bits wide. The colour to key on is set in Reg 2A18.
3449
3450	Local alpha works differently depending on the colour mode. For 32bpp & 8
3451	bit indexed, local alpha is a per-pixel 256 step transparency, with 0 being
3452	transparent and 255 being solid. For the 16bpp modes 555 & 444, the unused
3453	bit(s) act as a simple transparency switch, with 0 being solid & 1 being
3454	fully transparent. There is no local alpha support for 16bit 565.
3455
3456	Global alpha is a 256 step transparency that applies to the entire osd,
3457	with 0 being transparent & 255 being solid.
3458
3459	It's possible to combine colour key, local alpha & global alpha.
3460	--------------------------------------------------------------------------------
3461	2A04
3462	bits 0:15
3463		osd x coord for left edge
3464
3465	bits 16:31
3466		osd y coord for top edge
3467	---------------
3468	2A08
3469	bits 0:15
3470		osd x coord for right edge
3471
3472	bits 16:31
3473		osd y coord for bottom edge
3474
3475	For both registers, (0,0) = top left corner of the display area. These
3476	registers do not control the osd size, only where it's positioned & how
3477	much is visible. The visible osd area cannot exceed the right edge of the
3478	display, otherwise the osd will become corrupt. See reg 2A10 for
3479	setting osd width.
3480	--------------------------------------------------------------------------------
3481	2A0C
3482	bits 0:31
3483		osd buffer index
3484
3485	An index into the osd buffer. Slowly incrementing this moves the osd left,
3486	wrapping around onto the right edge
3487	--------------------------------------------------------------------------------
3488	2A10
3489	bits 0:11
3490		osd buffer 32 bit word width
3491
3492	Contains the width of the osd measured in 32 bit words. This means that all
3493	colour modes are restricted to a byte width which is divisible by 4.
3494	--------------------------------------------------------------------------------
3495	2A14
3496	bits 0:15
3497		osd height in pixels
3498
3499	bits 16:32
3500		osd line index into buffer
3501		osd will start displaying from this line.
3502	--------------------------------------------------------------------------------
3503	2A18
3504	bits 0:31
3505		osd colour key
3506
3507	Contains the colour value which will be transparent.
3508	--------------------------------------------------------------------------------
3509	2A1C
3510	bits 0:7
3511		osd global alpha
3512
3513	Contains the global alpha value (equiv ivtvfbctl --alpha XX)
3514	--------------------------------------------------------------------------------
3515	2A20  --------    ?? unknown
3516	|
3517	V
3518	2A2C  --------    ?? unknown
3519	--------------------------------------------------------------------------------
3520	2A30
3521	bits 0:7
3522		osd colour to change in indexed palette
3523	---------------
3524	2A34
3525	bits 0:31
3526		osd colour for indexed palette
3527
3528	To set the new palette, first load the index of the colour to change into
3529	2A30, then load the new colour into 2A34. The full palette is 256 colours,
3530	so the index range is 0x00-0xFF
3531	--------------------------------------------------------------------------------
3532	2A38  --------    ?? unknown
3533	2A3C  --------    ?? unknown
3534	--------------------------------------------------------------------------------
3535	2A40
3536	bits 0:31
3537		osd ?? unknown
3538
3539	Affects overall brightness, wrapping around to black
3540	--------------------------------------------------------------------------------
3541	2A44
3542	bits 0:31
3543		osd ?? unknown
3544
3545	Green tint
3546	--------------------------------------------------------------------------------
3547	2A48
3548	bits 0:31
3549		osd ?? unknown
3550
3551	Red tint
3552	--------------------------------------------------------------------------------
3553	2A4C
3554	bits 0:31
3555		osd ?? unknown
3556
3557	Affects overall brightness, wrapping around to black
3558	--------------------------------------------------------------------------------
3559	2A50
3560	bits 0:31
3561		osd ?? unknown
3562
3563	Colour shift
3564	--------------------------------------------------------------------------------
3565	2A54
3566	bits 0:31
3567		osd ?? unknown
3568
3569	Colour shift
3570	--------------------------------------------------------------------------------
3571	2A58  --------    ?? unknown
3572	|
3573	V
3574	2AFC  --------    ?? unknown
3575	--------------------------------------------------------------------------------
3576	2B00
3577	bit 0
3578		osd filter control
3579		0 = filter off
3580		1 = filter on
3581
3582	bits 1:4
3583		osd ?? unknown
3584
3585	--------------------------------------------------------------------------------
3586
3587The cx231xx DMA engine
3588----------------------
3589
3590
3591This page describes the structures and procedures used by the cx2341x DMA
3592engine.
3593
3594Introduction
3595~~~~~~~~~~~~
3596
3597The cx2341x PCI interface is busmaster capable. This means it has a DMA
3598engine to efficiently transfer large volumes of data between the card and main
3599memory without requiring help from a CPU. Like most hardware, it must operate
3600on contiguous physical memory. This is difficult to come by in large quantities
3601on virtual memory machines.
3602
3603Therefore, it also supports a technique called "scatter-gather". The card can
3604transfer multiple buffers in one operation. Instead of allocating one large
3605contiguous buffer, the driver can allocate several smaller buffers.
3606
3607In practice, I've seen the average transfer to be roughly 80K, but transfers
3608above 128K were not uncommon, particularly at startup. The 128K figure is
3609important, because that is the largest block that the kernel can normally
3610allocate. Even still, 128K blocks are hard to come by, so the driver writer is
3611urged to choose a smaller block size and learn the scatter-gather technique.
3612
3613Mailbox #10 is reserved for DMA transfer information.
3614
3615Note: the hardware expects little-endian data ('intel format').
3616
3617Flow
3618~~~~
3619
3620This section describes, in general, the order of events when handling DMA
3621transfers. Detailed information follows this section.
3622
3623- The card raises the Encoder interrupt.
3624- The driver reads the transfer type, offset and size from Mailbox #10.
3625- The driver constructs the scatter-gather array from enough free dma buffers
3626  to cover the size.
3627- The driver schedules the DMA transfer via the ScheduleDMAtoHost API call.
3628- The card raises the DMA Complete interrupt.
3629- The driver checks the DMA status register for any errors.
3630- The driver post-processes the newly transferred buffers.
3631
3632NOTE! It is possible that the Encoder and DMA Complete interrupts get raised
3633simultaneously. (End of the last, start of the next, etc.)
3634
3635Mailbox #10
3636~~~~~~~~~~~
3637
3638The Flags, Command, Return Value and Timeout fields are ignored.
3639
3640- Name:       Mailbox #10
3641- Results[0]: Type: 0: MPEG.
3642- Results[1]: Offset: The position relative to the card's memory space.
3643- Results[2]: Size: The exact number of bytes to transfer.
3644
3645My speculation is that since the StartCapture API has a capture type of "RAW"
3646available, that the type field will have other values that correspond to YUV
3647and PCM data.
3648
3649Scatter-Gather Array
3650~~~~~~~~~~~~~~~~~~~~
3651
3652The scatter-gather array is a contiguously allocated block of memory that
3653tells the card the source and destination of each data-block to transfer.
3654Card "addresses" are derived from the offset supplied by Mailbox #10. Host
3655addresses are the physical memory location of the target DMA buffer.
3656
3657Each S-G array element is a struct of three 32-bit words. The first word is
3658the source address, the second is the destination address. Both take up the
3659entire 32 bits. The lowest 18 bits of the third word is the transfer byte
3660count. The high-bit of the third word is the "last" flag. The last-flag tells
3661the card to raise the DMA_DONE interrupt. From hard personal experience, if
3662you forget to set this bit, the card will still "work" but the stream will
3663most likely get corrupted.
3664
3665The transfer count must be a multiple of 256. Therefore, the driver will need
3666to track how much data in the target buffer is valid and deal with it
3667accordingly.
3668
3669Array Element:
3670
3671- 32-bit Source Address
3672- 32-bit Destination Address
3673- 14-bit reserved (high bit is the last flag)
3674- 18-bit byte count
3675
3676DMA Transfer Status
3677~~~~~~~~~~~~~~~~~~~
3678
3679Register 0x0004 holds the DMA Transfer Status:
3680
3681- bit 0:   read completed
3682- bit 1:   write completed
3683- bit 2:   DMA read error
3684- bit 3:   DMA write error
3685- bit 4:   Scatter-Gather array error
3686