[PATCH] dvb: b2c2/flexcop driver refactoring part 2: add modular Flexcop driver

b2c2/flexcop driver refactoring to support PCI and USB based cards part 2: add
modular Flexcop driver

Signed-off-by: Patrick Boettcher <pb@linuxtv.org>
Signed-off-by: Johannes Stezenbach <js@linuxtv.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>

1 files changed, 279 insertions, 0 deletions

diff --git a/Documentation/dvb/README.flexcop b/Documentation/dvb/README.flexcop
new file mode 100644
index 000000000000..9ec735714e43
--- /dev/null
+++ b/Documentation/dvb/README.flexcop
@@ -0,0 +1,279 @@
+This README escorted the skystar2-driver rewriting procedure. It describes the
+state of the new flexcop-driver set and some internals are written down here
+too.
+
+How to do something in here?
+============================
+
+make -f Makefile.t
+make -C ../build-2.6
+./in.sh  # load the drivers
+./rm.sh  # unload the drivers
+
+Please read this file, if you want to contribute.
+
+This document hopefully describes things about the flexcop and its
+device-offsprings. Goal is to write a easy-to-write and easy-to-read set of
+drivers based on the skystar2.c and other information.
+
+This directory is temporary. It is used for rewriting the skystar2.c and to
+create shared code, which then can be used by the usb box as well.
+
+Remark: flexcop-pci.c was a copy of skystar2.c, but every line has been
+touched and rewritten.
+
+General coding processing
+=========================
+
+We should proceed as follows (as long as no one complains):
+
+0) Think before start writing code!
+
+1) rewriting the skystar2.c with the help of the flexcop register descriptions
+and splitting up the files to a pci-bus-part and a flexcop-part.
+The new driver will be called b2c2-flexcop-pci.ko/b2c2-flexcop-usb.ko for the
+device-specific part and b2c2-flexcop.ko for the common flexcop-functions.
+
+2) Search for errors in the leftover of flexcop-pci.c (compare with pluto2.c
+and other pci drivers)
+
+3) make some beautification (see 'Improvements when rewriting (refactoring) is
+done')
+
+4) Testing the new driver and maybe substitute the skystar2.c with it, to reach
+a wider tester audience.
+
+5) creating an usb-bus-part using the already written flexcop code for the pci
+card.
+
+Idea: create a kernel-object for the flexcop and export all important
+functions. This option saves kernel-memory, but maybe a lot of functions have
+to be exported to kernel namespace.
+
+
+Current situation
+=================
+
+0) Done :)
+1) Done (some minor issues left)
+2) Done
+3) Not ready yet, more information is necessary
+4) next to be done (see the table below)
+5) USB driver is working (yes, there are some minor issues)
+
+What seems to be ready?
+-----------------------
+
+1) Rewriting
+1a) i2c is cut off from the flexcop-pci.c and seems to work
+1b) moved tuner and demod stuff from flexcop-pci.c to flexcop-tuner-fe.c
+1c) moved lnb and diseqc stuff from flexcop-pci.c to flexcop-tuner-fe.c
+1e) eeprom (reading MAC address)
+1d) sram (no dynamic sll size detection (commented out) (using default as JJ told me))
+1f) misc. register accesses for reading parameters (e.g. resetting, revision)
+1g) pid/mac filter (flexcop-hw-filter.c)
+1i) dvb-stuff initialization in flexcop.c (done)
+1h) dma stuff (now just using the size-irq, instead of all-together, to be done)
+1j) remove flexcop initialization from flexcop-pci.c completely (done)
+1l) use a well working dma IRQ method (done, see 'Known bugs and problems and TODO')
+1k) cleanup flexcop-files (remove unused EXPORT_SYMBOLs, make static from
+non-static where possible, moved code to proper places)
+
+2) Search for errors in the leftover of flexcop-pci.c (partially done)
+5a) add MAC address reading
+
+What to do in the near future?
+--------------------------------------
+(no special order here)
+
+
+5) USB driver
+5b) optimize isoc-transfer (submitting/killing isoc URBs when transfer is starting)
+5c) feeding of ISOC data to the software demux (format of the isochronous data
+and speed optimization, no real error)
+
+Testing changes
+---------------
+
+O             = item is working
+P             = item is partially working
+X             = item is not working
+N             = item does not apply here
+<empty field> = item need to be examined
+
+       | PCI                               | USB
+item   | mt352 | nxt2002 | stv0299 | mt312 | mt352 | nxt2002 | stv0299 | mt312
+-------+-------+---------+---------+-------+-------+---------+---------+-------
+1a)    | O     |         |         |       | N     | N       | N       | N
+1b)    | O     |         |         |       |       |         | O       |
+1c)    | N     | N       |         |       | N     | N       | O       |
+1d)    |                 O                 |                 O
+1e)    |                 O                 |                 O
+1f)    |                                   P
+1g)    |                                   O
+1h)    |                 P                 |
+1i)    |                 O                 |                 N
+1j)    |                 O                 |                 N
+1l)    |                 O                 |                 N
+2)     |                 O                 |                 N
+5a)    |                 N                 |                 O
+5b)*   |                 N                 |
+5c)*   |                 N                 |
+
+* - not done yet
+
+Known bugs and problems and TODO
+--------------------------------
+
+1g/h/l) when pid filtering is enabled on the pci card
+
+DMA usage currently:
+  The DMA is splitted in 2 equal-sized subbuffers. The Flexcop writes to first
+  address and triggers an IRQ when it's full and starts writing to the second
+  address. When the second address is full, the IRQ is triggered again, and
+  the flexcop writes to first address again, and so on.
+  The buffersize of each address is currently 640*188 bytes.
+
+  Problem is, when using hw-pid-filtering and doing some low-bandwidth
+  operation (like scanning) the buffers won't be filled enough to trigger
+  the IRQ. That's why:
+
+  When PID filtering is activated, the timer IRQ is used. Every 1.97 ms the IRQ
+  is triggered.  Is the current write address of DMA1 different to the one
+  during the last IRQ, then the data is passed to the demuxer.
+
+  There is an additional DMA-IRQ-method: packet count IRQ. This isn't
+  implemented correctly yet.
+
+  The solution is to disable HW PID filtering, but I don't know how the DVB
+  API software demux behaves on slow systems with 45MBit/s TS.
+
+Solved bugs :)
+--------------
+1g) pid-filtering (somehow pid index 4 and 5 (EMM_PID and ECM_PID) aren't
+working)
+SOLUTION: also index 0 was affected, because net_translation is done for
+these indexes by default
+
+5b) isochronous transfer does only work in the first attempt (for the Sky2PC USB,
+Air2PC is working)
+SOLUTION: the flexcop was going asleep and never really woke up again (don't
+know if this need fixes, see flexcop-fe-tuner.c:flexcop_sleep)
+
+Improvements when rewriting (refactoring) is done
+=================================================
+
+- split sleeping of the flexcop (misc_204.ACPI3_sig = 1;) from lnb_control
+  (enable sleeping for other demods than dvb-s)
+- add support for CableStar (stv0297 Microtune 203x/ALPS)
+
+Debugging
+---------
+- add verbose debugging to skystar2.c (dump the reg_dw_data) and compare it
+  with this flexcop, this is important, because i2c is now using the
+  flexcop_ibi_value union from flexcop-reg.h (do you have a better idea for
+  that, please tell us so).
+
+Everything which is identical in the following table, can be put into a common
+flexcop-module.
+
+                  PCI                  USB
+-------------------------------------------------------------------------------
+Different:
+Register access:  accessing IO memory  USB control message
+I2C bus:          I2C bus of the FC    USB control message
+Data transfer:    DMA                  isochronous transfer
+EEPROM transfer:  through i2c bus      not clear yet
+
+Identical:
+Streaming:                 accessing registers
+PID Filtering:             accessing registers
+Sram destinations:         accessing registers
+Tuner/Demod:                     I2C bus
+DVB-stuff:            can be written for common use
+
+Restrictions:
+============
+
+We need to create a bus-specific-struct and a flexcop-struct.
+
+bus-specific-struct:
+
+struct flexcop_pci
+...
+
+struct flexcop_usb
+...
+
+
+struct flexcop_device {
+	void *bus_specific; /* container for bus-specific struct */
+...
+}
+
+PCI i2c can read/write max 4 bytes at a time, USB can more
+
+Functions
+=========
+
+Syntax
+------
+
+- Flexcop functions will be called "flexcop(_[a-z0-9]+)+" and exported as such
+  if needed.
+- Flexcop-device functions will be called "flexcop_device(_[a-z0-9]+)+" and
+  exported as such if needed.
+- Both will be compiled to b2c2-flexcop.ko and their source can be found in the
+  flexcop*.[hc]
+
+Callbacks and exports
+---------------------
+
+Bus-specific functions will be given as callbacks (function pointers) to the
+flexcop-module. (within the flexcop_device-struct)
+
+Initialization process
+======================
+
+b2c2-flexcop.ko is loaded
+b2c2-flexcop-<bus>.ko is loaded
+
+suppose a device is found:
+malloc flexcop and the bus-specific variables (via flexcop_device_malloc)
+fill the bus-specific variable
+fill the flexcop variable (especially the bus-specific callbacks)
+bus-specific initialization
+	- ...
+do the common initialization (via flexcop_device_initialize)
+	- reset the card
+	- determine flexcop type (II, IIB, III)
+	- hw_filters (bus dependent)
+	- 0x204
+	- set sram size
+	- create the dvb-stuff
+	- create i2c stuff
+	- frontend-initialization
+done
+bus specific:
+	- media_destination (this and the following 3 are bus specific)
+	- cai_dest
+	- cao_dest
+	- net_destination
+
+Bugs fixed while rewriting the driver
+=====================================
+
+- EEPROM access (to read the MAC address) was fixed to death some time last
+  year. (fixed here and in skystar2.c) (Bjarne, this was the piece of code
+  (fix-chipaddr) we were wondering about)
+
+
+Acknowledgements (just for the rewriting part)
+================
+
+Bjarne Steinsbo thought a lot in the first place of the pci part for this code
+sharing idea.
+
+Andreas Oberritter for providing a recent PCI initialization template (pluto2.c).
+
+comments, critics and ideas to linux-dvb@linuxtv.org or patrick.boettcher@desy.de