]> err.no Git - linux-2.6/blob - Documentation/dvb/README.flexcop
[PATCH] dvb: b2c2/flexcop driver refactoring part 2: add modular Flexcop driver
[linux-2.6] / Documentation / dvb / README.flexcop
1 This README escorted the skystar2-driver rewriting procedure. It describes the
2 state of the new flexcop-driver set and some internals are written down here
3 too.
4
5 How to do something in here?
6 ============================
7
8 make -f Makefile.t
9 make -C ../build-2.6
10 ./in.sh  # load the drivers
11 ./rm.sh  # unload the drivers
12
13 Please read this file, if you want to contribute.
14
15 This document hopefully describes things about the flexcop and its
16 device-offsprings. Goal is to write a easy-to-write and easy-to-read set of
17 drivers based on the skystar2.c and other information.
18
19 This directory is temporary. It is used for rewriting the skystar2.c and to
20 create shared code, which then can be used by the usb box as well.
21
22 Remark: flexcop-pci.c was a copy of skystar2.c, but every line has been
23 touched and rewritten.
24
25 General coding processing
26 =========================
27
28 We should proceed as follows (as long as no one complains):
29
30 0) Think before start writing code!
31
32 1) rewriting the skystar2.c with the help of the flexcop register descriptions
33 and splitting up the files to a pci-bus-part and a flexcop-part.
34 The new driver will be called b2c2-flexcop-pci.ko/b2c2-flexcop-usb.ko for the
35 device-specific part and b2c2-flexcop.ko for the common flexcop-functions.
36
37 2) Search for errors in the leftover of flexcop-pci.c (compare with pluto2.c
38 and other pci drivers)
39
40 3) make some beautification (see 'Improvements when rewriting (refactoring) is
41 done')
42
43 4) Testing the new driver and maybe substitute the skystar2.c with it, to reach
44 a wider tester audience.
45
46 5) creating an usb-bus-part using the already written flexcop code for the pci
47 card.
48
49 Idea: create a kernel-object for the flexcop and export all important
50 functions. This option saves kernel-memory, but maybe a lot of functions have
51 to be exported to kernel namespace.
52
53
54 Current situation
55 =================
56
57 0) Done :)
58 1) Done (some minor issues left)
59 2) Done
60 3) Not ready yet, more information is necessary
61 4) next to be done (see the table below)
62 5) USB driver is working (yes, there are some minor issues)
63
64 What seems to be ready?
65 -----------------------
66
67 1) Rewriting
68 1a) i2c is cut off from the flexcop-pci.c and seems to work
69 1b) moved tuner and demod stuff from flexcop-pci.c to flexcop-tuner-fe.c
70 1c) moved lnb and diseqc stuff from flexcop-pci.c to flexcop-tuner-fe.c
71 1e) eeprom (reading MAC address)
72 1d) sram (no dynamic sll size detection (commented out) (using default as JJ told me))
73 1f) misc. register accesses for reading parameters (e.g. resetting, revision)
74 1g) pid/mac filter (flexcop-hw-filter.c)
75 1i) dvb-stuff initialization in flexcop.c (done)
76 1h) dma stuff (now just using the size-irq, instead of all-together, to be done)
77 1j) remove flexcop initialization from flexcop-pci.c completely (done)
78 1l) use a well working dma IRQ method (done, see 'Known bugs and problems and TODO')
79 1k) cleanup flexcop-files (remove unused EXPORT_SYMBOLs, make static from
80 non-static where possible, moved code to proper places)
81
82 2) Search for errors in the leftover of flexcop-pci.c (partially done)
83 5a) add MAC address reading
84
85 What to do in the near future?
86 --------------------------------------
87 (no special order here)
88
89
90 5) USB driver
91 5b) optimize isoc-transfer (submitting/killing isoc URBs when transfer is starting)
92 5c) feeding of ISOC data to the software demux (format of the isochronous data
93 and speed optimization, no real error)
94
95 Testing changes
96 ---------------
97
98 O             = item is working
99 P             = item is partially working
100 X             = item is not working
101 N             = item does not apply here
102 <empty field> = item need to be examined
103
104        | PCI                               | USB
105 item   | mt352 | nxt2002 | stv0299 | mt312 | mt352 | nxt2002 | stv0299 | mt312
106 -------+-------+---------+---------+-------+-------+---------+---------+-------
107 1a)    | O     |         |         |       | N     | N       | N       | N
108 1b)    | O     |         |         |       |       |         | O       |
109 1c)    | N     | N       |         |       | N     | N       | O       |
110 1d)    |                 O                 |                 O
111 1e)    |                 O                 |                 O
112 1f)    |                                   P
113 1g)    |                                   O
114 1h)    |                 P                 |
115 1i)    |                 O                 |                 N
116 1j)    |                 O                 |                 N
117 1l)    |                 O                 |                 N
118 2)     |                 O                 |                 N
119 5a)    |                 N                 |                 O
120 5b)*   |                 N                 |
121 5c)*   |                 N                 |
122
123 * - not done yet
124
125 Known bugs and problems and TODO
126 --------------------------------
127
128 1g/h/l) when pid filtering is enabled on the pci card
129
130 DMA usage currently:
131   The DMA is splitted in 2 equal-sized subbuffers. The Flexcop writes to first
132   address and triggers an IRQ when it's full and starts writing to the second
133   address. When the second address is full, the IRQ is triggered again, and
134   the flexcop writes to first address again, and so on.
135   The buffersize of each address is currently 640*188 bytes.
136
137   Problem is, when using hw-pid-filtering and doing some low-bandwidth
138   operation (like scanning) the buffers won't be filled enough to trigger
139   the IRQ. That's why:
140
141   When PID filtering is activated, the timer IRQ is used. Every 1.97 ms the IRQ
142   is triggered.  Is the current write address of DMA1 different to the one
143   during the last IRQ, then the data is passed to the demuxer.
144
145   There is an additional DMA-IRQ-method: packet count IRQ. This isn't
146   implemented correctly yet.
147
148   The solution is to disable HW PID filtering, but I don't know how the DVB
149   API software demux behaves on slow systems with 45MBit/s TS.
150
151 Solved bugs :)
152 --------------
153 1g) pid-filtering (somehow pid index 4 and 5 (EMM_PID and ECM_PID) aren't
154 working)
155 SOLUTION: also index 0 was affected, because net_translation is done for
156 these indexes by default
157
158 5b) isochronous transfer does only work in the first attempt (for the Sky2PC USB,
159 Air2PC is working)
160 SOLUTION: the flexcop was going asleep and never really woke up again (don't
161 know if this need fixes, see flexcop-fe-tuner.c:flexcop_sleep)
162
163 Improvements when rewriting (refactoring) is done
164 =================================================
165
166 - split sleeping of the flexcop (misc_204.ACPI3_sig = 1;) from lnb_control
167   (enable sleeping for other demods than dvb-s)
168 - add support for CableStar (stv0297 Microtune 203x/ALPS)
169
170 Debugging
171 ---------
172 - add verbose debugging to skystar2.c (dump the reg_dw_data) and compare it
173   with this flexcop, this is important, because i2c is now using the
174   flexcop_ibi_value union from flexcop-reg.h (do you have a better idea for
175   that, please tell us so).
176
177 Everything which is identical in the following table, can be put into a common
178 flexcop-module.
179
180                   PCI                  USB
181 -------------------------------------------------------------------------------
182 Different:
183 Register access:  accessing IO memory  USB control message
184 I2C bus:          I2C bus of the FC    USB control message
185 Data transfer:    DMA                  isochronous transfer
186 EEPROM transfer:  through i2c bus      not clear yet
187
188 Identical:
189 Streaming:                 accessing registers
190 PID Filtering:             accessing registers
191 Sram destinations:         accessing registers
192 Tuner/Demod:                     I2C bus
193 DVB-stuff:            can be written for common use
194
195 Restrictions:
196 ============
197
198 We need to create a bus-specific-struct and a flexcop-struct.
199
200 bus-specific-struct:
201
202 struct flexcop_pci
203 ...
204
205 struct flexcop_usb
206 ...
207
208
209 struct flexcop_device {
210         void *bus_specific; /* container for bus-specific struct */
211 ...
212 }
213
214 PCI i2c can read/write max 4 bytes at a time, USB can more
215
216 Functions
217 =========
218
219 Syntax
220 ------
221
222 - Flexcop functions will be called "flexcop(_[a-z0-9]+)+" and exported as such
223   if needed.
224 - Flexcop-device functions will be called "flexcop_device(_[a-z0-9]+)+" and
225   exported as such if needed.
226 - Both will be compiled to b2c2-flexcop.ko and their source can be found in the
227   flexcop*.[hc]
228
229 Callbacks and exports
230 ---------------------
231
232 Bus-specific functions will be given as callbacks (function pointers) to the
233 flexcop-module. (within the flexcop_device-struct)
234
235 Initialization process
236 ======================
237
238 b2c2-flexcop.ko is loaded
239 b2c2-flexcop-<bus>.ko is loaded
240
241 suppose a device is found:
242 malloc flexcop and the bus-specific variables (via flexcop_device_malloc)
243 fill the bus-specific variable
244 fill the flexcop variable (especially the bus-specific callbacks)
245 bus-specific initialization
246         - ...
247 do the common initialization (via flexcop_device_initialize)
248         - reset the card
249         - determine flexcop type (II, IIB, III)
250         - hw_filters (bus dependent)
251         - 0x204
252         - set sram size
253         - create the dvb-stuff
254         - create i2c stuff
255         - frontend-initialization
256 done
257 bus specific:
258         - media_destination (this and the following 3 are bus specific)
259         - cai_dest
260         - cao_dest
261         - net_destination
262
263 Bugs fixed while rewriting the driver
264 =====================================
265
266 - EEPROM access (to read the MAC address) was fixed to death some time last
267   year. (fixed here and in skystar2.c) (Bjarne, this was the piece of code
268   (fix-chipaddr) we were wondering about)
269
270
271 Acknowledgements (just for the rewriting part)
272 ================
273
274 Bjarne Steinsbo thought a lot in the first place of the pci part for this code
275 sharing idea.
276
277 Andreas Oberritter for providing a recent PCI initialization template (pluto2.c).
278
279 comments, critics and ideas to linux-dvb@linuxtv.org or patrick.boettcher@desy.de