View source for Multiproto

Multiproto is a proposal for version 3.3 of the linux DVB API which includes extensions for cards which support multiple DVB protocols (DVB-S, DVB-S2, DVB-T, DVB-C, DVB-H, ATSC, DSS).

It is an experimental project and is not currently implemented in any released version of Linux. No firm plan has been made for its inclusion in Linux.

==Overview/Features==
''Discuss the features and facets of the project here ... this means you''

===Design Decisions===
''explain the choices made ... this means you''

===Technical Details===
''give a technical description of how the API change has been implemented ... this means you''

New structs and enums have been added to expand the API for multiple frontends and the parameters required for protocols DVB-S, DSS, DVB-S2, DVB-T, DVB-H and ATSC. These are prefixed (at least for now) with "dvbfe_" and "DVBFE_" as opposed to the old "fe_" and "FE_". For details compare the old and new versions of include/linux/dvb/frontend.h. Currently multiproto implements both the new and old APIs and a glue layer to manage old/new drivers with new/old API calls. Presumably the plan is eventually to move to a pure 3.3 API and update all the drivers.

Simple enough you might think, but progress has been very slow. Since the first version, way back in April 2006, ten (10!) versions of the entire Linux kernel have been released. See http://www.linuxtv.org/pipermail/linux-dvb/2006-April/009522.html and http://kernelnewbies.org/Linux26Changes.

===Evaluation and Alternatives===
''explain whether the design goals have been met or not ... this means you''

1. There is '''repetition''' in the multiproto API arising from the use of
unions of structs to hold parameters (often the same ones) for each type of frontend.
However API calls (eg. ioctl dvbfe_params) are addressed to an individual frontend
/dev/dvb/adapterN/frontendN so this repetition could be removed to create a cleaner
API. For example these variables:

 dvbfe_params.delsys.dvbs.fec
 dvbfe_params.delsys.dss.fec
 dvbfe_params.delsys.dvbs2.fec
 dvbfe_params.delsys.dvbc.fec

could be replaced by the simpler:

 dvbfe_params.fec

Similarly for a number of other variables.

2.''' There is a problem with the design of the multiproto API'''. The routine DVBFE_GET_INFO actually ''changes'' the kernel state (in particular the variable which holds the delivery system). Simply calling DVBFE_SET_PARAMS with a complete correct set of parameters does not work. The corresponding screwy userspace code can be seen in the patched http://abraham.manu.googlepages.com/szap.c where DVBFE_GET_INFO is used to SET the delivery system variable before DVBFE_SET_PARAMS is called. Such odd unexpected behaviour is confusing and should not be accepted in the Linux kernel. At the very least some work needs to be done to rename the routines sensibly. DVBFE_GET_INFO appears to have been
originally intended to provide information about the capabilities of the frontend, which is currently not apparent in its name. See http://www.linuxtv.org/pipermail/linux-dvb/2008-March/024266.html and http://www.linuxtv.org/pipermail/linux-dvb/2008-March/024281.html.

UPDATE: This appears to have been changed with the introduction of DVBFE_SET_DELSYS which is now used
to set the delivery system. Tuning is done with szap2.

'''Alternatives:''' An alternative API has been created for the [[Hauppauge]] [[Hauppauge WinTV-HVR-4000|WinTV-HVR-4000]] which makes minimal changes to the current v4l-dvb API in order to provide multifrontend support for DVB-T,DVB-S and DVB-S2 for that device. It offers backwards compatibility with existing binary multimedia applications for DVB-T and DVB-S without recompilation. Patches providing DVB-S2 support for szap and mythtv have been posted. See http://dev.kewl.org/hauppauge/experimental/, http://dev.kewl.org/hauppauge and http://www.linuxtv.org/pipermail/linux-dvb/2008-March/024243.html.

===Status and Migration Plan===
''explain how a migration from the current API to multiproto could be achieved ... this means you''

No clear migration plan has yet been agreed.

The mantis tree (http://jusst.de/hg/mantis) which also uses the multiproto API has not yet been merged into multiproto, meaning that there is unnecessary duplication of the core code and any code fixes in either
tree are not automatically applied to both trees.

It has been reported  http://www.linuxtv.org/pipermail/linux-dvb/2008-July/027464.html
that the currently available Multiproto needs to be updated to compile cleanly with the
latest kernel version 2.6.26. Volunteer? Last known good version = 2.6.24?

==Making it Work==

How to get it from the author's repository:

 hg clone http://jusst.de/hg/multiproto
or
 http://jusst.de/hg/multiproto/archive/tip.tar.bz2
 
UPDATE 1st Aug 2008: Igor Liplianin has created another repository containing multiproto code and szap2 at http://liplianindvb.sourceforge.net/hg/, reported to be working with the HVR-4000.
See
http://www.linuxtv.org/pipermail/linux-dvb/2008-July/027514.html. This appears to be
similar to the V4L/DVB staging development repository at http://linuxtv.org/hg/v4l-dvb/
but with the addition of multiproto code.

 hg clone http://liplianindvb.sourceforge.net/hg/liplianindvb
 hg clone http://liplianindvb.sourceforge.net/hg/szap2


===Drivers===
There are currently no in-kernel multiproto drivers.  There are several cards which have experimental support in the multiproto tree, perhaps with additional patches.

''Provide details of which drivers work with multiproto ... this means you''

See the descriptions for the following cards:

[[Azurewave AD SP400 CI (VP-1041)|Azurewave AD-SP400 CI (Twinhan VP-1041)]]

[[Hauppauge]] [[Hauppauge WinTV-HVR-4000|WinTV-HVR-4000]] 

[[KNC1]] [[KNC1 DVB-S2 TV Station|DVB-S2 TV Station]] (PCI32, supports CI)

[[TechnoTrend]] [[TechnoTrend TT-budget S2-3200|TT-budget S2-3200]]
 
[[TerraTec]] [[TerraTec Cinergy S2 PCI HD CI| Cinergy S2 PCI HD CI]] (PCI32, CI)

''provide the details of where the drivers and patches and necessary tools are available ... this means you''

''provide details of how to compile for recent kernels -- this means you''

===Sample kernel output===
''provide the relevant portion of dmesg here''

===Tuner / DiSEqC / Player support===
''provide comprehensive details of how to upgrade multimedia applications to work with the new API ... this means you''

Scanning and tuning applications generally will not work with the new API unless they are modified. The situation is arguably improving but the lack of patched applications (and guidance on patching) has hindered completion and testing of multiproto and new drivers, and adoption of the new API. Needless to say, patching drivers and multiple applications is a step too far for most potential testers.

'''dvb-apps''' : There is ''still'' no patched dvb-apps tree. Someone needs to create one ... why don't you?

'''scan''' :  see patched version at http://jusst.de/manu/scan.tar.bz2

'''szap''': see patched version at http://abraham.manu.googlepages.com/szap.c
Also see information about szap2 at http://allrussian.info/thread.php?postid=187408#post187408
and http://www.linuxtv.org/pipermail/linux-dvb/2008-February/023836.html.

'''mplayer''' : someone needs to write a patch ... why don't you?

'''Kaffeine''' / '''xine-lib''' : someone needs to write a patch ... why don't you? There are some posts about getting Kaffeine to work with multiproto in these threads: http://www.linuxtv.org/pipermail/linux-dvb/2008-May/025882.html,
http://www.linuxtv.org/pipermail/linux-dvb/2008-July/027141.html
and in these two messages:
http://sourceforge.net/mailarchive/forum.php?thread_name=48217036.3090709%40gmail.com&forum_name=kaffeine-devel
and
http://sourceforge.net/mailarchive/forum.php?thread_name=481DE023.9000903%40gmail.com&forum_name=kaffeine-devel
.

'''VDR''' : VDR version 1.5.14 and later require multiproto (v1.5.14 announcement: http://www.linuxtv.org/pipermail/vdr/2008-January/015302.html

'''MythTV''' : Two patches (one DVB-S/S2, one DVB-S only) have been posted http://www.linuxtv.org/pipermail/linux-dvb/2008-January/022757.html. Current status?

'''dvbstream''' : Someone needs to write a patch ... why don't you? See http://www.linuxtv.org/pipermail/linux-dvb/2008-February/024056.html.

''provide details of how to use with DiSEqC -- this means you''

===How to patch an application for Multiproto===
''provide guidance on patching applications to use multiproto -- this means you''

'''To tune to a channel''' : using the patched szap above as a guide we see that

 struct dvb_frontend_parameters tuneto;
 ...
 ioctl(fefd, FE_SET_FRONTEND, &tuneto);

must be replaced by
	
 struct dvbfe_params fe_params;
 ...
 ioctl(fefd, DVBFE_SET_PARAMS, &fe_params);

where the parts of dvbfe_params.delsys relevant for the delivery system used (DVB-S/DSS/DVB-S2) need to be set before the call.

To make the userspace code a lot cleaner C preprocessor macros can be used to hide the full details of the multiproto api - here is a short example:

 #if (DVB_API_VERSION==3) && (DVB_API_VERSION_MINOR>=3)
 #define FE_PARAM                struct dvbfe_params
 #define IOCTL_SET_FE            DVBFE_SET_PARAMS
 #define DVB_SET_DELIVERY(a, b)  (a)->delivery=(b)
 #define DVBC_SET_SYMBOLRATE(a, b)       (a)->delsys.dvbc.symbol_rate=(b)
 #else
 #define FE_PARAM                struct dvb_frontend_parameters
 #define IOCTL_SET_FE            FE_SET_FRONTEND
 #define DVB_SET_DELIVERY(a, b)  do{ } while(0)
 #define DVBC_SET_SYMBOLRATE(a, b)       (a)->u.qam.symbol_rate=(b)
 #endif
 
 void tune(int fefd) {
  FE_PARAM        fparm;
  
  memset(&fparm, 0, sizeof(FE_PARM));
  
  DVB_SET_DELIVERY(&fparm, DVBFE_DELSYS_DVBC);
  ...
  DVBC_SET_SYMBOLRATE(&fparm, symbolrate)
  
  if (ioctl(fefd, IOCTL_SET_FE, &fparm) < 0) {
    printf("Tuning failed");
  }
 }

The code itself will stay clean of ifdef spaghetti and the compatibility macros can be hidden in some header file. See getstream [http://silicon-verl.de/home/flo/projects/streaming/] for
a multiproto capable tuner coder without a single ifdef.

==External Links==

Русский:
This page has been translated into Russian here: http://www.free-x.de/wiki/index.php/Multiproto.

[[Category:Development]]