1.. SPDX-License-Identifier: GPL-2.0
2
3The cx88 driver
4===============
5
6Author:  Gerd Hoffmann
7
8This is a v4l2 device driver for the cx2388x chip.
9
10
11Current status
12--------------
13
14video
15	- Works.
16	- Overlay isn't supported.
17
18audio
19	- Works. The TV standard detection is made by the driver, as the
20	  hardware has bugs to auto-detect.
21	- audio data dma (i.e. recording without loopback cable to the
22	  sound card) is supported via cx88-alsa.
23
24vbi
25	- Works.
26
27
28How to add support for new cards
29--------------------------------
30
31The driver needs some config info for the TV cards.  This stuff is in
32cx88-cards.c.  If the driver doesn't work well you likely need a new
33entry for your card in that file.  Check the kernel log (using dmesg)
34to see whenever the driver knows your card or not.  There is a line
35like this one:
36
37.. code-block:: none
38
39	cx8800[0]: subsystem: 0070:3400, board: Hauppauge WinTV \
40		34xxx models [card=1,autodetected]
41
42If your card is listed as "board: UNKNOWN/GENERIC" it is unknown to
43the driver.  What to do then?
44
451) Try upgrading to the latest snapshot, maybe it has been added
46   meanwhile.
472) You can try to create a new entry yourself, have a look at
48   cx88-cards.c.  If that worked, mail me your changes as unified
49   diff ("diff -u").
503) Or you can mail me the config information.  We need at least the
51   following information to add the card:
52
53     - the PCI Subsystem ID ("0070:3400" from the line above,
54       "lspci -v" output is fine too).
55     - the tuner type used by the card.  You can try to find one by
56       trial-and-error using the tuner=<n> insmod option.  If you
57       know which one the card has you can also have a look at the
58       list in CARDLIST.tuner
59
60Documentation missing at the cx88 datasheet
61-------------------------------------------
62
63MO_OUTPUT_FORMAT (0x310164)
64
65.. code-block:: none
66
67  Previous default from DScaler: 0x1c1f0008
68  Digit 8: 31-28
69  28: PREVREMOD = 1
70
71  Digit 7: 27-24 (0xc = 12 = b1100 )
72  27: COMBALT = 1
73  26: PAL_INV_PHASE
74    (DScaler apparently set this to 1, resulted in sucky picture)
75
76  Digits 6,5: 23-16
77  25-16: COMB_RANGE = 0x1f [default] (9 bits -> max 512)
78
79  Digit 4: 15-12
80  15: DISIFX = 0
81  14: INVCBF = 0
82  13: DISADAPT = 0
83  12: NARROWADAPT = 0
84
85  Digit 3: 11-8
86  11: FORCE2H
87  10: FORCEREMD
88  9: NCHROMAEN
89  8: NREMODEN
90
91  Digit 2: 7-4
92  7-6: YCORE
93  5-4: CCORE
94
95  Digit 1: 3-0
96  3: RANGE = 1
97  2: HACTEXT
98  1: HSFMT
99
1000x47 is the sync byte for MPEG-2 transport stream packets.
101Datasheet incorrectly states to use 47 decimal. 188 is the length.
102All DVB compliant frontends output packets with this start code.
103
104Hauppauge WinTV cx88 IR information
105-----------------------------------
106
107The controls for the mux are GPIO [0,1] for source, and GPIO 2 for muting.
108
109====== ======== =================================================
110GPIO0  GPIO1
111====== ======== =================================================
112  0        0    TV Audio
113  1        0    FM radio
114  0        1    Line-In
115  1        1    Mono tuner bypass or CD passthru (tuner specific)
116====== ======== =================================================
117
118GPIO 16(I believe) is tied to the IR port (if present).
119
120
121From the data sheet:
122
123- Register 24'h20004  PCI Interrupt Status
124
125 - bit [18]  IR_SMP_INT Set when 32 input samples have been collected over
126 - gpio[16] pin into GP_SAMPLE register.
127
128What's missing from the data sheet:
129
130- Setup 4KHz sampling rate (roughly 2x oversampled; good enough for our RC5
131  compat remote)
132- set register 0x35C050 to  0xa80a80
133- enable sampling
134- set register 0x35C054 to 0x5
135- enable the IRQ bit 18 in the interrupt mask register (and
136  provide for a handler)
137
138GP_SAMPLE register is at 0x35C058
139
140Bits are then right shifted into the GP_SAMPLE register at the specified
141rate; you get an interrupt when a full DWORD is received.
142You need to recover the actual RC5 bits out of the (oversampled) IR sensor
143bits. (Hint: look for the 0/1and 1/0 crossings of the RC5 bi-phase data)  An
144actual raw RC5 code will span 2-3 DWORDS, depending on the actual alignment.
145
146I'm pretty sure when no IR signal is present the receiver is always in a
147marking state(1); but stray light, etc can cause intermittent noise values
148as well.  Remember, this is a free running sample of the IR receiver state
149over time, so don't assume any sample starts at any particular place.
150
151Additional info
152~~~~~~~~~~~~~~~
153
154This data sheet (google search) seems to have a lovely description of the
155RC5 basics:
156http://www.atmel.com/dyn/resources/prod_documents/doc2817.pdf
157
158This document has more data:
159http://www.nenya.be/beor/electronics/rc5.htm
160
161This document has a  how to decode a bi-phase data stream:
162http://www.ee.washington.edu/circuit_archive/text/ir_decode.txt
163
164This document has still more info:
165http://www.xs4all.nl/~sbp/knowledge/ir/rc5.htm
166