Documentation/dvb/README.flexcop - SHIFTPHONES/mainline/linux - Gitiles

 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
	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