[PATCH 00/26] Some improvements for the media API

[PATCH 00/26] Some improvements for the media API

[Mauro Carvalho Chehab]

Improve documentation for the media core subsystems. The initial patches
of this series improve the documentation for V4L2 core and RC core,
adding documentation for tuner, tveeprom and lirc.

The remaining patches are focused on the DVB API, adding documentation
for the remaining stuff at dvb_ca and moving the kABI functions from the
API docbook into the device-drivers (kdapi.xml), making sure that what's 
documented is what's there at the Kernel. The kdapi.xml was broken for a long
time, since before 2005, when I started maintaining the DVB. After this patch
series, it is now in a better shape.

Mauro Carvalho Chehab (26):
  [media] DocBook: Document include/media/tuner.h
  [media] tuner.h: Make checkpatch.pl happier
  [media] DocBook: convert struct tuner_parms to doc-nano format
  [media] DocBook: add documentation for tuner-types.h
  [media] tveeprom: Remove two unused fields from struct
  [media] DocBook: Document tveeprom.h
  [media] DocBook: Convert struct lirc_driver to doc-nano format
  [media] lirc_dev.h: Make checkpatch happy
  [media] DocBook: document struct dvb_ca_en50221
  [media] dvb_ca_en50221.h: Make checkpatch.pl happy
  [media] DocBook: Move struct dmx_demux kABI doc to demux.h
  [media] DocBook: update documented fields at struct dmx_demux
  [media] dvb: don't keep support for undocumented features
  [media] DocBook: finish documenting struct dmx_demux
  [media] dvb: get rid of enum dmx_success
  [media] dvb: Remove unused frontend sources at demux.h and sync doc
  [media] DocBook: document the other structs/enums of demux.h
  [media] demux.h: make checkpatch.ph happy
  kernel-doc: Add a parser for function typedefs
  kernel-doc: better format typedef function output
  [media] DocBook: document typedef dmx_ts_cb at demux.h
  [media] DocBook: document typedef dmx_section_cb at demux.h
  [media] demux.h: Convert TS filter type into enum
  [media] demux.h: Convert MPEG-TS demux caps to an enum
  [media] DocBook: Add documentation about the demux API
  [media] DocBook: Remove kdapi.xml

 Documentation/DocBook/device-drivers.tmpl  |   80 +-
 Documentation/DocBook/media/dvb/dvbapi.xml |    3 -
 Documentation/DocBook/media/dvb/kdapi.xml  | 2309 ----------------------------
 drivers/media/dvb-core/demux.h             |  613 ++++++--
 drivers/media/dvb-core/dmxdev.c            |   10 +-
 drivers/media/dvb-core/dvb_ca_en50221.h    |   99 +-
 drivers/media/dvb-core/dvb_demux.c         |   11 +-
 drivers/media/dvb-core/dvb_net.c           |    5 +-
 drivers/media/pci/ttpci/av7110.c           |    9 +-
 drivers/media/pci/ttpci/av7110_av.c        |    6 +-
 drivers/media/usb/ttusb-dec/ttusb_dec.c    |   12 +-
 include/media/lirc_dev.h                   |  120 +-
 include/media/tuner-types.h                |  182 ++-
 include/media/tuner.h                      |  152 +-
 include/media/tveeprom.h                   |   83 +-
 scripts/kernel-doc                         |   25 +
 16 files changed, 1005 insertions(+), 2714 deletions(-)
 delete mode 100644 Documentation/DocBook/media/dvb/kdapi.xml

-- 
2.4.3

[PATCH 01/26] [media] DocBook: Document include/media/tuner.h

[Mauro Carvalho Chehab]

This is part of the V4L2 core, so its kABI should be
documented at device-drivers DocBook.

Add the meta-tags for that.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index 31cefc9af98e..2fc3bca44f49 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -221,6 +221,7 @@ X!Isound/sound_firmware.c
      <title>Media Devices</title>
 
      <sect1><title>Video2Linux devices</title>
+!Iinclude/media/tuner.h
 !Iinclude/media/v4l2-async.h
 !Iinclude/media/v4l2-ctrls.h
 !Iinclude/media/v4l2-dv-timings.h
diff --git a/include/media/tuner.h b/include/media/tuner.h
index b46ebb48fe74..4445dcbfdb80 100644
--- a/include/media/tuner.h
+++ b/include/media/tuner.h
@@ -166,33 +166,67 @@
 #define TDA9887_GAIN_NORMAL		(1<<20)
 #define TDA9887_RIF_41_3		(1<<21)  /* radio IF1 41.3 vs 33.3 */
 
+/**
+ * enum tuner_mode      - Mode of the tuner
+ *
+ * @T_RADIO:        Tuner core will work in radio mode
+ * @T_ANALOG_TV:    Tuner core will work in analog TV mode
+ *
+ * Older boards only had a single tuner device, but some devices have a
+ * separate tuner for radio. In any case, the tuner-core needs to know if
+ * the tuner chip(s) will be used in radio mode or analog TV mode, as, on
+ * radio mode, frequencies are specified on a different range than on TV
+ * mode. This enum is used by the tuner core in order to work with the
+ * proper tuner range and eventually use a different tuner chip while in
+ * radio mode.
+ */
 enum tuner_mode {
 	T_RADIO		= 1 << V4L2_TUNER_RADIO,
 	T_ANALOG_TV     = 1 << V4L2_TUNER_ANALOG_TV,
 	/* Don't need to map V4L2_TUNER_DIGITAL_TV, as tuner-core won't use it */
 };
 
-/* Older boards only had a single tuner device. Nowadays multiple tuner
-   devices may be present on a single board. Using TUNER_SET_TYPE_ADDR
-   to pass the tuner_setup structure it is possible to setup each tuner
-   device in turn.
-
-   Since multiple devices may be present it is no longer sufficient to
-   send a command to a single i2c device. Instead you should broadcast
-   the command to all i2c devices.
-
-   By setting the mode_mask correctly you can select which commands are
-   accepted by a specific tuner device. For example, set mode_mask to
-   T_RADIO if the device is a radio-only tuner. That specific tuner will
-   only accept commands when the tuner is in radio mode and ignore them
-   when the tuner is set to TV mode.
+/**
+ * struct tuner_setup   - setup the tuner chipsets
+ *
+ * @addr:		I2C address used to control the tuner device/chipset
+ * @type:		Type of the tuner, as defined at the TUNER_* macros.
+ *			Each different tuner model should have an unique
+ *			identifier.
+ * @mode_mask:		Mask with the allowed tuner modes: V4L2_TUNER_RADIO,
+ *			V4L2_TUNER_ANALOG_TV and/or V4L2_TUNER_DIGITAL_TV,
+ *			describing if the tuner should be used to support
+ *			Radio, analog TV and/or digital TV.
+ * @config:		Used to send tuner-specific configuration for complex
+ *			tuners that require extra parameters to be set.
+ *			Only a very few tuners require it and its usage on
+ *			newer tuners should be avoided.
+ * @tuner_callback:	Some tuners require to call back the bridge driver,
+ *			in order to do some tasks like rising a GPIO at the
+ *			bridge chipset, in order to do things like resetting
+ *			the device.
+ *
+ * Older boards only had a single tuner device. Nowadays multiple tuner
+ * devices may be present on a single board. Using TUNER_SET_TYPE_ADDR
+ * to pass the tuner_setup structure it is possible to setup each tuner
+ * device in turn.
+ *
+ * Since multiple devices may be present it is no longer sufficient to
+ * send a command to a single i2c device. Instead you should broadcast
+ * the command to all i2c devices.
+ *
+ * By setting the mode_mask correctly you can select which commands are
+ * accepted by a specific tuner device. For example, set mode_mask to
+ * T_RADIO if the device is a radio-only tuner. That specific tuner will
+ * only accept commands when the tuner is in radio mode and ignore them
+ * when the tuner is set to TV mode.
  */
 
 struct tuner_setup {
-	unsigned short	addr; 	/* I2C address */
-	unsigned int	type;   /* Tuner type */
-	unsigned int	mode_mask;  /* Allowed tuner modes */
-	void		*config;    /* configuraion for more complex tuners */
+	unsigned short	addr;
+	unsigned int	type;
+	unsigned int	mode_mask;
+	void		*config;
 	int (*tuner_callback) (void *dev, int component, int cmd, int arg);
 };
 
-- 
2.4.3

[PATCH 02/26] [media] tuner.h: Make checkpatch.pl happier

[Mauro Carvalho Chehab]

Remove some bad whitespaces before tabs and fix the initial
comment to be compliant with Kernel coding style.

Now, the only complains are about long comment lines at the
defines. Those warnings should be ok to be kept.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/include/media/tuner.h b/include/media/tuner.h
index 4445dcbfdb80..486b6a54363b 100644
--- a/include/media/tuner.h
+++ b/include/media/tuner.h
@@ -1,23 +1,19 @@
 /*
-    tuner.h - definition for different tuners
-
-    Copyright (C) 1997 Markus Schroeder (schroedm@uni-duesseldorf.de)
-    minor modifications by Ralph Metzler (rjkm@thp.uni-koeln.de)
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-*/
+ * tuner.h - definition for different tuners
+ *
+ * Copyright (C) 1997 Markus Schroeder (schroedm@uni-duesseldorf.de)
+ * minor modifications by Ralph Metzler (rjkm@thp.uni-koeln.de)
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
 
 #ifndef _TUNER_H
 #define _TUNER_H
@@ -83,8 +79,11 @@
 #define TUNER_PHILIPS_FM1236_MK3	43
 
 #define TUNER_PHILIPS_4IN1		44	/* ATI TV Wonder Pro - Conexant */
-/* Microtune merged with Temic 12/31/1999 partially financed by Alps - these may be similar to Temic */
-#define TUNER_MICROTUNE_4049FM5 	45
+	/*
+	 * Microtune merged with Temic 12/31/1999 partially financed by Alps.
+	 * these may be similar to Temic
+	 */
+#define TUNER_MICROTUNE_4049FM5		45
 #define TUNER_PANASONIC_VP27		46
 #define TUNER_LG_NTSC_TAPE		47
 
@@ -115,11 +114,11 @@
 
 #define TUNER_PHILIPS_TUV1236D		68	/* ATI HDTV Wonder */
 #define TUNER_TNF_5335MF                69	/* Sabrent Bt848   */
-#define TUNER_SAMSUNG_TCPN_2121P30A     70 	/* Hauppauge PVR-500MCE NTSC */
+#define TUNER_SAMSUNG_TCPN_2121P30A     70	/* Hauppauge PVR-500MCE NTSC */
 #define TUNER_XC2028			71
 
 #define TUNER_THOMSON_FE6600		72	/* DViCO FusionHDTV DVB-T Hybrid */
-#define TUNER_SAMSUNG_TCPG_6121P30A     73 	/* Hauppauge PVR-500 PAL */
+#define TUNER_SAMSUNG_TCPG_6121P30A     73	/* Hauppauge PVR-500 PAL */
 #define TUNER_TDA9887                   74      /* This tuner should be used only internally */
 #define TUNER_TEA5761			75	/* Only FM Radio Tuner */
 #define TUNER_XC5000			76	/* Xceive Silicon Tuner */
@@ -143,25 +142,26 @@
 #define TUNER_SONY_BTF_PB463Z		91	/* NTSC */
 
 /* tv card specific */
-#define TDA9887_PRESENT 		(1<<0)
-#define TDA9887_PORT1_INACTIVE 		(1<<1)
-#define TDA9887_PORT2_INACTIVE 		(1<<2)
-#define TDA9887_QSS 			(1<<3)
-#define TDA9887_INTERCARRIER 		(1<<4)
-#define TDA9887_PORT1_ACTIVE 		(1<<5)
-#define TDA9887_PORT2_ACTIVE 		(1<<6)
-#define TDA9887_INTERCARRIER_NTSC 	(1<<7)
+#define TDA9887_PRESENT			(1<<0)
+#define TDA9887_PORT1_INACTIVE		(1<<1)
+#define TDA9887_PORT2_INACTIVE		(1<<2)
+#define TDA9887_QSS			(1<<3)
+#define TDA9887_INTERCARRIER		(1<<4)
+#define TDA9887_PORT1_ACTIVE		(1<<5)
+#define TDA9887_PORT2_ACTIVE		(1<<6)
+#define TDA9887_INTERCARRIER_NTSC	(1<<7)
 /* Tuner takeover point adjustment, in dB, -16 <= top <= 15 */
-#define TDA9887_TOP_MASK 		(0x3f << 8)
-#define TDA9887_TOP_SET 		(1 << 13)
-#define TDA9887_TOP(top) 		(TDA9887_TOP_SET | (((16 + (top)) & 0x1f) << 8))
+#define TDA9887_TOP_MASK		(0x3f << 8)
+#define TDA9887_TOP_SET			(1 << 13)
+#define TDA9887_TOP(top)		(TDA9887_TOP_SET | \
+					 (((16 + (top)) & 0x1f) << 8))
 
 /* config options */
-#define TDA9887_DEEMPHASIS_MASK 	(3<<16)
-#define TDA9887_DEEMPHASIS_NONE 	(1<<16)
-#define TDA9887_DEEMPHASIS_50 		(2<<16)
-#define TDA9887_DEEMPHASIS_75 		(3<<16)
-#define TDA9887_AUTOMUTE 		(1<<18)
+#define TDA9887_DEEMPHASIS_MASK		(3<<16)
+#define TDA9887_DEEMPHASIS_NONE		(1<<16)
+#define TDA9887_DEEMPHASIS_50		(2<<16)
+#define TDA9887_DEEMPHASIS_75		(3<<16)
+#define TDA9887_AUTOMUTE		(1<<18)
 #define TDA9887_GATING_18		(1<<19)
 #define TDA9887_GAIN_NORMAL		(1<<20)
 #define TDA9887_RIF_41_3		(1<<21)  /* radio IF1 41.3 vs 33.3 */
@@ -183,7 +183,7 @@
 enum tuner_mode {
 	T_RADIO		= 1 << V4L2_TUNER_RADIO,
 	T_ANALOG_TV     = 1 << V4L2_TUNER_ANALOG_TV,
-	/* Don't need to map V4L2_TUNER_DIGITAL_TV, as tuner-core won't use it */
+	/* Don't map V4L2_TUNER_DIGITAL_TV, as tuner-core won't use it */
 };
 
 /**
@@ -227,7 +227,7 @@ struct tuner_setup {
 	unsigned int	type;
 	unsigned int	mode_mask;
 	void		*config;
-	int (*tuner_callback) (void *dev, int component, int cmd, int arg);
+	int (*tuner_callback)(void *dev, int component, int cmd, int arg);
 };
 
 #endif /* __KERNEL__ */
-- 
2.4.3

[PATCH 03/26] [media] DocBook: convert struct tuner_parms to doc-nano format

[Mauro Carvalho Chehab]

The struct tuner_params is almost fully documented, but
using a non-standard way. Convert it to doc-nano format,
and add descriptions for the parameters that aren't
documented yet.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h
index ab03c5344209..011b4a20ee22 100644
--- a/include/media/tuner-types.h
+++ b/include/media/tuner-types.h
@@ -19,91 +19,119 @@ struct tuner_range {
 	unsigned char cb;
 };
 
+/**
+ * struct tuner_params - Parameters to be used to setup the tuner. Those
+ *			 are used by drivers/media/tuners/tuner-types.c in
+ *			 order to specify the tuner properties. Most of
+ *			 the parameters are for tuners based on tda9887 IF-PLL
+ *			 multi-standard analog TV/Radio demodulator, with is
+ *			 very common on legacy analog tuners.
+ *
+ * @type:			Type of the tuner parameters, as defined at
+ *				enum param_type. If the tuner supports multiple
+ *				standards, an array should be used, with one
+ *				row per different standard.
+ * @cb_first_if_lower_freq:	Many Philips-based tuners have a comment in
+ *				their datasheet like
+ *				"For channel selection involving band
+ *				switching, and to ensure smooth tuning to the
+ *				desired channel without causing unnecessary
+ *				charge pump action, it is recommended to
+ *				consider the difference between wanted channel
+ *				frequency and the current channel frequency.
+ *				Unnecessary charge pump action will result
+ *				in very low tuning voltage which may drive the
+ *				oscillator to extreme conditions".
+ *				Set cb_first_if_lower_freq to 1, if this check
+ *				is required for this tuner. I tested this for
+ *				PAL by first setting the TV frequency to
+ *				203 MHz and then switching to 96.6 MHz FM
+ *				radio. The result was static unless the
+ *				control byte was sent first.
+ * @has_tda9887:		Set to 1 if this tuner uses a tda9887
+ * @port1_fm_high_sensitivity:	Many Philips tuners use tda9887 PORT1 to select
+ *				the FM radio sensitivity. If this setting is 1,
+ *				then set PORT1 to 1 to get proper FM reception.
+ * @port2_fm_high_sensitivity:	Some Philips tuners use tda9887 PORT2 to select
+ *				the FM radio sensitivity. If this setting is 1,
+ *				then set PORT2 to 1 to get proper FM reception.
+ * @fm_gain_normal:		Some Philips tuners use tda9887 cGainNormal to
+ *				select the FM radio sensitivity. If this
+ *				setting is 1, e register will use cGainNormal
+ *				instead of cGainLow.
+ * @intercarrier_mode:		Most tuners with a tda9887 use QSS mode.
+ *				Some (cheaper) tuners use Intercarrier mode.
+ *				If this setting is 1, then the tuner needs to
+ *				be set to intercarrier mode.
+ * @port1_active:		This setting sets the default value for PORT1.
+ *				0 means inactive, 1 means active. Note: the
+ *				actual bit value written to the tda9887 is
+ *				inverted. So a 0 here means a 1 in the B6 bit.
+ * @port2_active:		This setting sets the default value for PORT2.
+ *				0 means inactive, 1 means active. Note: the
+ *				actual bit value written to the tda9887 is
+ *				inverted. So a 0 here means a 1 in the B7 bit.
+ * @port1_invert_for_secam_lc:	Sometimes PORT1 is inverted when the SECAM-L'
+ *				standard is selected. Set this bit to 1 if this
+ *				is needed.
+ * @port2_invert_for_secam_lc:	Sometimes PORT2 is inverted when the SECAM-L'
+ *				standard is selected. Set this bit to 1 if this
+ *				is needed.
+ * @port1_set_for_fm_mono:	Some cards require PORT1 to be 1 for mono Radio
+ *				FM and 0 for stereo.
+ * @default_pll_gating_18:	Select 18% (or according to datasheet 0%)
+ *				L standard PLL gating, vs the driver default
+ *				of 36%.
+ * @radio_if:			IF to use in radio mode.  Tuners with a
+ *				separate radio IF filter seem to use 10.7,
+ *				while those without use 33.3 for PAL/SECAM
+ *				tuners and 41.3 for NTSC tuners.
+ *				0 = 10.7, 1 = 33.3, 2 = 41.3
+ * @default_top_low:		Default tda9887 TOP value in dB for the low
+ *				band. Default is 0. Range: -16:+15
+ * @default_top_mid:		Default tda9887 TOP value in dB for the mid
+ *				band. Default is 0. Range: -16:+15
+ * @default_top_high:		Default tda9887 TOP value in dB for the high
+ *				band. Default is 0. Range: -16:+15
+ * @default_top_secam_low:	Default tda9887 TOP value in dB for SECAM-L/L'
+ *				for the low band. Default is 0. Several tuners
+ *				require a different TOP value for the
+ *				SECAM-L/L' standards. Range: -16:+15
+ * @default_top_secam_mid:	Default tda9887 TOP value in dB for SECAM-L/L'
+ *				for the mid band. Default is 0. Several tuners
+ *				require a different TOP value for the
+ *				SECAM-L/L' standards. Range: -16:+15
+ * @default_top_secam_high:	Default tda9887 TOP value in dB for SECAM-L/L'
+ *				for the high band. Default is 0. Several tuners
+ *				require a different TOP value for the
+ *				SECAM-L/L' standards. Range: -16:+15
+ * @iffreq:			Intermediate frequency (IF) used by the tuner
+ *				on digital mode.
+ * @count:			Size of the ranges array.
+ * @ranges:			Array with the frequency ranges supported by
+ *				the tuner.
+ */
 struct tuner_params {
 	enum param_type type;
 
-	/* Many Philips based tuners have a comment like this in their
-	 * datasheet:
-	 *
-	 *   For channel selection involving band switching, and to ensure
-	 *   smooth tuning to the desired channel without causing
-	 *   unnecessary charge pump action, it is recommended to consider
-	 *   the difference between wanted channel frequency and the
-	 *   current channel frequency.  Unnecessary charge pump action
-	 *   will result in very low tuning voltage which may drive the
-	 *   oscillator to extreme conditions.
-	 *
-	 * Set cb_first_if_lower_freq to 1, if this check is
-	 * required for this tuner.
-	 *
-	 * I tested this for PAL by first setting the TV frequency to
-	 * 203 MHz and then switching to 96.6 MHz FM radio. The result was
-	 * static unless the control byte was sent first.
-	 */
 	unsigned int cb_first_if_lower_freq:1;
-	/* Set to 1 if this tuner uses a tda9887 */
 	unsigned int has_tda9887:1;
-	/* Many Philips tuners use tda9887 PORT1 to select the FM radio
-	   sensitivity. If this setting is 1, then set PORT1 to 1 to
-	   get proper FM reception. */
 	unsigned int port1_fm_high_sensitivity:1;
-	/* Some Philips tuners use tda9887 PORT2 to select the FM radio
-	   sensitivity. If this setting is 1, then set PORT2 to 1 to
-	   get proper FM reception. */
 	unsigned int port2_fm_high_sensitivity:1;
-	/* Some Philips tuners use tda9887 cGainNormal to select the FM radio
-	   sensitivity. If this setting is 1, e register will use cGainNormal
-	   instead of cGainLow. */
 	unsigned int fm_gain_normal:1;
-	/* Most tuners with a tda9887 use QSS mode. Some (cheaper) tuners
-	   use Intercarrier mode. If this setting is 1, then the tuner
-	   needs to be set to intercarrier mode. */
 	unsigned int intercarrier_mode:1;
-	/* This setting sets the default value for PORT1.
-	   0 means inactive, 1 means active. Note: the actual bit
-	   value written to the tda9887 is inverted. So a 0 here
-	   means a 1 in the B6 bit. */
 	unsigned int port1_active:1;
-	/* This setting sets the default value for PORT2.
-	   0 means inactive, 1 means active. Note: the actual bit
-	   value written to the tda9887 is inverted. So a 0 here
-	   means a 1 in the B7 bit. */
 	unsigned int port2_active:1;
-	/* Sometimes PORT1 is inverted when the SECAM-L' standard is selected.
-	   Set this bit to 1 if this is needed. */
 	unsigned int port1_invert_for_secam_lc:1;
-	/* Sometimes PORT2 is inverted when the SECAM-L' standard is selected.
-	   Set this bit to 1 if this is needed. */
 	unsigned int port2_invert_for_secam_lc:1;
-	/* Some cards require PORT1 to be 1 for mono Radio FM and 0 for stereo. */
 	unsigned int port1_set_for_fm_mono:1;
-	/* Select 18% (or according to datasheet 0%) L standard PLL gating,
-	   vs the driver default of 36%. */
 	unsigned int default_pll_gating_18:1;
-	/* IF to use in radio mode.  Tuners with a separate radio IF filter
-	   seem to use 10.7, while those without use 33.3 for PAL/SECAM tuners
-	   and 41.3 for NTSC tuners. 0 = 10.7, 1 = 33.3, 2 = 41.3 */
 	unsigned int radio_if:2;
-	/* Default tda9887 TOP value in dB for the low band. Default is 0.
-	   Range: -16:+15 */
 	signed int default_top_low:5;
-	/* Default tda9887 TOP value in dB for the mid band. Default is 0.
-	   Range: -16:+15 */
 	signed int default_top_mid:5;
-	/* Default tda9887 TOP value in dB for the high band. Default is 0.
-	   Range: -16:+15 */
 	signed int default_top_high:5;
-	/* Default tda9887 TOP value in dB for SECAM-L/L' for the low band.
-	   Default is 0. Several tuners require a different TOP value for
-	   the SECAM-L/L' standards. Range: -16:+15 */
 	signed int default_top_secam_low:5;
-	/* Default tda9887 TOP value in dB for SECAM-L/L' for the mid band.
-	   Default is 0. Several tuners require a different TOP value for
-	   the SECAM-L/L' standards. Range: -16:+15 */
 	signed int default_top_secam_mid:5;
-	/* Default tda9887 TOP value in dB for SECAM-L/L' for the high band.
-	   Default is 0. Several tuners require a different TOP value for
-	   the SECAM-L/L' standards. Range: -16:+15 */
 	signed int default_top_secam_high:5;
 
 	u16 iffreq;
-- 
2.4.3

[PATCH 04/26] [media] DocBook: add documentation for tuner-types.h

[Mauro Carvalho Chehab]

The tuner-types.h is part of the V4L2 core and should be
touched for every new tuner added. So, it deserves to be
documented at the device-drivers DocBook.

Add it to device-drivers.tmpl and add descriptions for
enum param_type and struct tuner_range.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index 2fc3bca44f49..8ce967a48c58 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -222,6 +222,7 @@ X!Isound/sound_firmware.c
 
      <sect1><title>Video2Linux devices</title>
 !Iinclude/media/tuner.h
+!Iinclude/media/tuner-types.h
 !Iinclude/media/v4l2-async.h
 !Iinclude/media/v4l2-ctrls.h
 !Iinclude/media/v4l2-dv-timings.h
diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h
index 011b4a20ee22..094e112cc325 100644
--- a/include/media/tuner-types.h
+++ b/include/media/tuner-types.h
@@ -5,6 +5,15 @@
 #ifndef __TUNER_TYPES_H__
 #define __TUNER_TYPES_H__
 
+/**
+ * enum param_type - type of the tuner pameters
+ *
+ * @TUNER_PARAM_TYPE_RADIO:	Tuner params are for FM and/or AM radio
+ * @TUNER_PARAM_TYPE_PAL:	Tuner params are for PAL color TV standard
+ * @TUNER_PARAM_TYPE_SECAM:	Tuner params are for SECAM color TV standard
+ * @TUNER_PARAM_TYPE_NTSC:	Tuner params are for NTSC color TV standard
+ * @TUNER_PARAM_TYPE_DIGITAL:	Tuner params are for digital TV
+ */
 enum param_type {
 	TUNER_PARAM_TYPE_RADIO,
 	TUNER_PARAM_TYPE_PAL,
@@ -13,6 +22,23 @@ enum param_type {
 	TUNER_PARAM_TYPE_DIGITAL,
 };
 
+/**
+ * struct tuner_range - define the frequencies supported by the tuner
+ *
+ * @limit:		Max frequency supported by that range, in 62.5 kHz
+ *			(TV) or 62.5 Hz (Radio), as defined by
+ *			V4L2_TUNER_CAP_LOW.
+ * @config:		Value of the band switch byte (BB) to setup this mode.
+ * @cb:			Value of the CB byte to setup this mode.
+ *
+ * Please notice that digital tuners like xc3028/xc4000/xc5000 don't use
+ * those ranges, as they're defined inside the driver. This is used by
+ * analog tuners that are compatible with the "Philips way" to setup the
+ * tuners. On those devices, the tuner set is done via 4 bytes:
+ *	divider byte1 (DB1), divider byte 2 (DB2), Control byte (CB) and
+ *	band switch byte (BB).
+ * Some tuners also have an additional optional Auxiliary byte (AB).
+ */
 struct tuner_range {
 	unsigned short limit;
 	unsigned char config;
-- 
2.4.3

[PATCH 05/26] [media] tveeprom: Remove two unused fields from struct

[Mauro Carvalho Chehab]

The digitizer* fields aren't used. Remove them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/include/media/tveeprom.h b/include/media/tveeprom.h
index f7119ee3977b..bb484967ef8b 100644
--- a/include/media/tveeprom.h
+++ b/include/media/tveeprom.h
@@ -32,9 +32,6 @@ struct tveeprom {
 	u32 tuner2_formats;
 	u32 tuner2_hauppauge_model;
 
-	u32 digitizer;
-	u32 digitizer_formats;
-
 	u32 audio_processor;
 	u32 decoder_processor;
 
-- 
2.4.3

[PATCH 06/26] [media] DocBook: Document tveeprom.h

[Mauro Carvalho Chehab]

This header declares the code and structures used to parse
Hauppauge eeproms. As this is part of the V4L2 common, and
used by several drivers, let's properly document it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index 8ce967a48c58..bdc0f7e0a55d 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -223,6 +223,7 @@ X!Isound/sound_firmware.c
      <sect1><title>Video2Linux devices</title>
 !Iinclude/media/tuner.h
 !Iinclude/media/tuner-types.h
+!Iinclude/media/tveeprom.h
 !Iinclude/media/v4l2-async.h
 !Iinclude/media/v4l2-ctrls.h
 !Iinclude/media/v4l2-dv-timings.h
diff --git a/include/media/tveeprom.h b/include/media/tveeprom.h
index bb484967ef8b..8be898739e0c 100644
--- a/include/media/tveeprom.h
+++ b/include/media/tveeprom.h
@@ -1,28 +1,63 @@
+
 /*
+ * tveeprom - Contains structures and functions to work with Hauppauge
+ *	      eeproms.
  */
 
+#include <linux/if_ether.h>
+
+/**
+ * enum tveeprom_audio_processor - Specifies the type of audio processor
+ *				   used on a Hauppauge device.
+ *
+ * @TVEEPROM_AUDPROC_NONE:	No audio processor present
+ * @TVEEPROM_AUDPROC_INTERNAL:	The audio processor is internal to the
+ *				video processor
+ * @TVEEPROM_AUDPROC_MSP:	The audio processor is a MSPXXXX device
+ * @TVEEPROM_AUDPROC_OTHER:	The audio processor is another device
+ */
 enum tveeprom_audio_processor {
-	/* No audio processor present */
 	TVEEPROM_AUDPROC_NONE,
-	/* The audio processor is internal to the video processor */
 	TVEEPROM_AUDPROC_INTERNAL,
-	/* The audio processor is a MSPXXXX device */
 	TVEEPROM_AUDPROC_MSP,
-	/* The audio processor is another device */
 	TVEEPROM_AUDPROC_OTHER,
 };
 
-#include <linux/if_ether.h>
-
+/**
+ * struct tveeprom - Contains the fields parsed from Hauppauge eeproms
+ *
+ * @has_radio:			1 if the device has radio; 0 otherwise.
+ * @has_ir:			If has_ir == 0, then it is unknown what the IR
+ *				capabilities are. Otherwise:
+ *					bit 0) 1 (= IR capabilities are known);
+ *					bit 1) IR receiver present;
+ *					bit 2) IR transmitter (blaster) present.
+ * @has_MAC_address:		0: no MAC, 1: MAC present, 2: unknown.
+ * @tuner_type:			type of the tuner (TUNER_*, as defined at
+ *				include/media/tuner.h).
+ * @tuner_formats:		Supported analog TV standards (V4L2_STD_*).
+ * @tuner_hauppauge_model:	Hauppauge's code for the device model number.
+ * @tuner2_type:		type of the second tuner (TUNER_*, as defined
+ *				at include/media/tuner.h).
+ * @tuner2_formats:		Tuner 2 supported analog TV standards
+ *				(V4L2_STD_*).
+ * @tuner2_hauppauge_model:	tuner 2 Hauppauge's code for the device model
+ *				number.
+ * @audio_processor:		analog audio decoder, as defined by enum
+ *				tveeprom_audio_processor.
+ * @decoder_processor:		Hauppauge's code for the decoder chipset.
+ *				Unused by the drivers, as they probe the
+ *				decoder based on the PCI or USB ID.
+ * @model:			Hauppauge's model number
+ * @revision:			Card revision number
+ * @serial_number:		Card's serial number
+ * @rev_str:			Card revision converted to number
+ * @MAC_address:		MAC address for the network interface
+ */
 struct tveeprom {
 	u32 has_radio;
-	/* If has_ir == 0, then it is unknown what the IR capabilities are,
-	   otherwise:
-	   bit 0: 1 (= IR capabilities are known)
-	   bit 1: IR receiver present
-	   bit 2: IR transmitter (blaster) present */
 	u32 has_ir;
-	u32 has_MAC_address; /* 0: no MAC, 1: MAC present, 2: unknown */
+	u32 has_MAC_address;
 
 	u32 tuner_type;
 	u32 tuner_formats;
@@ -42,7 +77,28 @@ struct tveeprom {
 	u8 MAC_address[ETH_ALEN];
 };
 
+/**
+ * tveeprom_hauppauge_analog - Fill struct tveeprom using the contents
+ *			       of the eeprom previously filled at
+ *			       @eeprom_data field.
+ *
+ * @c:			I2C client struct
+ * @tvee:		Struct to where the eeprom parsed data will be filled;
+ * @eeprom_data:	Array with the contents of the eeprom_data. It should
+ *			contain 256 bytes filled with the contents of the
+ *			eeprom read from the Hauppauge device.
+ */
 void tveeprom_hauppauge_analog(struct i2c_client *c, struct tveeprom *tvee,
 			       unsigned char *eeprom_data);
 
+/**
+ * tveeprom_read - Reads the contents of the eeprom found at the Hauppauge
+ *		   devices.
+ *
+ * @c:		I2C client struct
+ * @eedata:	Array where the eeprom content will be stored.
+ * @len:	Size of @eedata array. If the eeprom content will be latter
+ *		be parsed by tveeprom_hauppauge_analog(), len should be, at
+ *		least, 256.
+ */
 int tveeprom_read(struct i2c_client *c, unsigned char *eedata, int len);
-- 
2.4.3

[PATCH 07/26] [media] DocBook: Convert struct lirc_driver to doc-nano format

[Mauro Carvalho Chehab]

The struct lirc_driver is already documented, but on some
internal format. Convert it to Kernel doc-nano format and
add documentation for some additional parameters that are
also present at the structure.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index bdc0f7e0a55d..44634e295699 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -246,6 +246,7 @@ X!Isound/sound_firmware.c
      </sect1>
      <sect1><title>Remote Controller devices</title>
 !Iinclude/media/rc-core.h
+!Iinclude/media/lirc_dev.h
      </sect1>
      <sect1><title>Media Controller devices</title>
 !Iinclude/media/media-device.h
diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h
index 05e7ad5d2c8b..abb92f879ba2 100644
--- a/include/media/lirc_dev.h
+++ b/include/media/lirc_dev.h
@@ -118,6 +118,71 @@ static inline unsigned int lirc_buffer_write(struct lirc_buffer *buf,
 	return ret;
 }
 
+/**
+ * struct lirc_driver - Defines the parameters on a LIRC driver
+ *
+ * @name:		this string will be used for logs
+ *
+ * @minor:		indicates minor device (/dev/lirc) number for
+ *			registered driver if caller fills it with negative
+ *			value, then the first free minor number will be used
+ *			(if available).
+ *
+ * @code_length:	length of the remote control key code expressed in bits.
+ *
+ * @buffer_size:	Number of FIFO buffers with @chunk_size size. If zero,
+ *			creates a buffer with BUFLEN size (16 bytes).
+ *
+ * @sample_rate:	if zero, the device will wait for an event with a new
+ *			code to be parsed. Otherwise, specifies the sample
+ *			rate for polling. Value should be between 0
+ *			and HZ. If equal to HZ, it would mean one polling per
+ *			second.
+ *
+ * @features:		lirc compatible hardware features, like LIRC_MODE_RAW,
+ *			LIRC_CAN_*, as defined at include/media/lirc.h.
+ *
+ * @chunk_size:		Size of each FIFO buffer.
+ *
+ * @data:		it may point to any driver data and this pointer will
+ *			be passed to all callback functions.
+ *
+ * @min_timeout:	Minimum timeout for record. Valid only if
+ *			LIRC_CAN_SET_REC_TIMEOUT is defined.
+ *
+ * @max_timeout:	Maximum timeout for record. Valid only if
+ *			LIRC_CAN_SET_REC_TIMEOUT is defined.
+ *
+ * @add_to_buf:		add_to_buf will be called after specified period of the
+ *			time or triggered by the external event, this behavior
+ *			depends on value of the sample_rate this function will
+ *			be called in user context. This routine should return
+ *			0 if data was added to the buffer and -ENODATA if none
+ *			was available. This should add some number of bits
+ *			evenly divisible by code_length to the buffer.
+ *
+ * @rbuf:		if not NULL, it will be used as a read buffer, you will
+ *			have to write to the buffer by other means, like irq's
+ *			(see also lirc_serial.c).
+ *
+ * @set_use_inc:	set_use_inc will be called after device is opened
+ *
+ * @set_use_dec:	set_use_dec will be called after device is closed
+ *
+ * @rdev:		Pointed to struct rc_dev associated with the LIRC
+ *			device.
+ *
+ * @fops:		file_operations for drivers which don't fit the current
+ *			driver model.
+ *			Some ioctl's can be directly handled by lirc_dev if the
+ *			driver's ioctl function is NULL or if it returns
+ *			-ENOIOCTLCMD (see also lirc_serial.c).
+ *
+ * @dev:		pointer to the struct device associated with the LIRC
+ *			device.
+ *
+ * @owner:		the module owning this struct
+ */
 struct lirc_driver {
 	char name[40];
 	int minor;
@@ -141,55 +206,6 @@ struct lirc_driver {
 	struct module *owner;
 };
 
-/* name:
- * this string will be used for logs
- *
- * minor:
- * indicates minor device (/dev/lirc) number for registered driver
- * if caller fills it with negative value, then the first free minor
- * number will be used (if available)
- *
- * code_length:
- * length of the remote control key code expressed in bits
- *
- * sample_rate:
- *
- * data:
- * it may point to any driver data and this pointer will be passed to
- * all callback functions
- *
- * add_to_buf:
- * add_to_buf will be called after specified period of the time or
- * triggered by the external event, this behavior depends on value of
- * the sample_rate this function will be called in user context. This
- * routine should return 0 if data was added to the buffer and
- * -ENODATA if none was available. This should add some number of bits
- * evenly divisible by code_length to the buffer
- *
- * rbuf:
- * if not NULL, it will be used as a read buffer, you will have to
- * write to the buffer by other means, like irq's (see also
- * lirc_serial.c).
- *
- * set_use_inc:
- * set_use_inc will be called after device is opened
- *
- * set_use_dec:
- * set_use_dec will be called after device is closed
- *
- * fops:
- * file_operations for drivers which don't fit the current driver model.
- *
- * Some ioctl's can be directly handled by lirc_dev if the driver's
- * ioctl function is NULL or if it returns -ENOIOCTLCMD (see also
- * lirc_serial.c).
- *
- * owner:
- * the module owning this struct
- *
- */
-
-
 /* following functions can be called ONLY from user context
  *
  * returns negative value on error or minor number
-- 
2.4.3

[PATCH 08/26] [media] lirc_dev.h: Make checkpatch happy

[Mauro Carvalho Chehab]

Remove warnings about bad whitespacing at function
struct parameters.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h
index abb92f879ba2..0ab59a571fee 100644
--- a/include/media/lirc_dev.h
+++ b/include/media/lirc_dev.h
@@ -196,10 +196,10 @@ struct lirc_driver {
 	void *data;
 	int min_timeout;
 	int max_timeout;
-	int (*add_to_buf) (void *data, struct lirc_buffer *buf);
+	int (*add_to_buf)(void *data, struct lirc_buffer *buf);
 	struct lirc_buffer *rbuf;
-	int (*set_use_inc) (void *data);
-	void (*set_use_dec) (void *data);
+	int (*set_use_inc)(void *data);
+	void (*set_use_dec)(void *data);
 	struct rc_dev *rdev;
 	const struct file_operations *fops;
 	struct device *dev;
-- 
2.4.3

[PATCH 09/26] [media] DocBook: document struct dvb_ca_en50221

[Mauro Carvalho Chehab]

This struct is already documented at the header file, but it is
not using Kernel doc-nano format. Convert to it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/dvb_ca_en50221.h b/drivers/media/dvb-core/dvb_ca_en50221.h
index aba3b4fbd704..9ec2adc3ea11 100644
--- a/drivers/media/dvb-core/dvb_ca_en50221.h
+++ b/drivers/media/dvb-core/dvb_ca_en50221.h
@@ -39,40 +39,43 @@
 
 
 
-/* Structure describing a CA interface */
+/**
+ * struct dvb_ca_en50221- Structure describing a CA interface
+ *
+ * @owner:		the module owning this structure
+ * @read_attribute_mem:	function for reading attribute memory on the CAM
+ * @write_attribute_mem: function for writing attribute memory on the CAM
+ * @read_cam_control:	function for reading the control interface on the CAM
+ * @write_cam_control:	function for reading the control interface on the CAM
+ * @slot_reset:		function to reset the CAM slot
+ * @slot_shutdown:	function to shutdown a CAM slot
+ * @slot_ts_enable:	function to enable the Transport Stream on a CAM slot
+ * @poll_slot_status:	function to poll slot status. Only necessary if
+ *			DVB_CA_FLAG_EN50221_IRQ_CAMCHANGE is not set.
+ * @data:		private data, used by caller.
+ * @private:		Opaque data used by the dvb_ca core. Do not modify!
+ *
+ * NOTE: the read_*, write_* and poll_slot_status functions will be
+ * called for different slots concurrently and need to use locks where
+ * and if appropriate. There will be no concurrent access to one slot.
+ */
 struct dvb_ca_en50221 {
 
-	/* the module owning this structure */
-	struct module* owner;
 
-	/* NOTE: the read_*, write_* and poll_slot_status functions will be
-	 * called for different slots concurrently and need to use locks where
-	 * and if appropriate. There will be no concurrent access to one slot.
-	 */
 
-	/* functions for accessing attribute memory on the CAM */
-	int (*read_attribute_mem)(struct dvb_ca_en50221* ca, int slot, int address);
 	int (*write_attribute_mem)(struct dvb_ca_en50221* ca, int slot, int address, u8 value);
 
-	/* functions for accessing the control interface on the CAM */
 	int (*read_cam_control)(struct dvb_ca_en50221* ca, int slot, u8 address);
 	int (*write_cam_control)(struct dvb_ca_en50221* ca, int slot, u8 address, u8 value);
 
-	/* Functions for controlling slots */
 	int (*slot_reset)(struct dvb_ca_en50221* ca, int slot);
 	int (*slot_shutdown)(struct dvb_ca_en50221* ca, int slot);
 	int (*slot_ts_enable)(struct dvb_ca_en50221* ca, int slot);
 
-	/*
-	* Poll slot status.
-	* Only necessary if DVB_CA_FLAG_EN50221_IRQ_CAMCHANGE is not set
-	*/
 	int (*poll_slot_status)(struct dvb_ca_en50221* ca, int slot, int open);
 
-	/* private data, used by caller */
 	void* data;
 
-	/* Opaque data used by the dvb_ca core. Do not modify! */
 	void* private;
 };
 
-- 
2.4.3

[PATCH 10/26] [media] dvb_ca_en50221.h: Make checkpatch.pl happy

[Mauro Carvalho Chehab]

There are several CodingStyle violations at the DVB code. While
we won't be fixing them as a hole, let's fix at least the
headers, as we're touching on them already in order to properly
document them.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/dvb_ca_en50221.h b/drivers/media/dvb-core/dvb_ca_en50221.h
index 9ec2adc3ea11..1e4bbbd34d91 100644
--- a/drivers/media/dvb-core/dvb_ca_en50221.h
+++ b/drivers/media/dvb-core/dvb_ca_en50221.h
@@ -12,10 +12,6 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the
  * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  */
 
 #ifndef _DVB_CA_EN50221_H_
@@ -37,8 +33,6 @@
 #define DVB_CA_EN50221_CAMCHANGE_REMOVED		0
 #define DVB_CA_EN50221_CAMCHANGE_INSERTED		1
 
-
-
 /**
  * struct dvb_ca_en50221- Structure describing a CA interface
  *
@@ -60,30 +54,32 @@
  * and if appropriate. There will be no concurrent access to one slot.
  */
 struct dvb_ca_en50221 {
+	struct module *owner;
 
+	int (*read_attribute_mem)(struct dvb_ca_en50221 *ca,
+				  int slot, int address);
+	int (*write_attribute_mem)(struct dvb_ca_en50221 *ca,
+				   int slot, int address, u8 value);
 
+	int (*read_cam_control)(struct dvb_ca_en50221 *ca,
+				int slot, u8 address);
+	int (*write_cam_control)(struct dvb_ca_en50221 *ca,
+				 int slot, u8 address, u8 value);
 
-	int (*write_attribute_mem)(struct dvb_ca_en50221* ca, int slot, int address, u8 value);
+	int (*slot_reset)(struct dvb_ca_en50221 *ca, int slot);
+	int (*slot_shutdown)(struct dvb_ca_en50221 *ca, int slot);
+	int (*slot_ts_enable)(struct dvb_ca_en50221 *ca, int slot);
 
-	int (*read_cam_control)(struct dvb_ca_en50221* ca, int slot, u8 address);
-	int (*write_cam_control)(struct dvb_ca_en50221* ca, int slot, u8 address, u8 value);
+	int (*poll_slot_status)(struct dvb_ca_en50221 *ca, int slot, int open);
 
-	int (*slot_reset)(struct dvb_ca_en50221* ca, int slot);
-	int (*slot_shutdown)(struct dvb_ca_en50221* ca, int slot);
-	int (*slot_ts_enable)(struct dvb_ca_en50221* ca, int slot);
+	void *data;
 
-	int (*poll_slot_status)(struct dvb_ca_en50221* ca, int slot, int open);
-
-	void* data;
-
-	void* private;
+	void *private;
 };
 
-
-
-
-/* ******************************************************************************** */
-/* Functions for reporting IRQ events */
+/*
+ * Functions for reporting IRQ events
+ */
 
 /**
  * dvb_ca_en50221_camchange_irq - A CAMCHANGE IRQ has occurred.
@@ -92,7 +88,8 @@ struct dvb_ca_en50221 {
  * @slot: Slot concerned.
  * @change_type: One of the DVB_CA_CAMCHANGE_* values
  */
-void dvb_ca_en50221_camchange_irq(struct dvb_ca_en50221* pubca, int slot, int change_type);
+void dvb_ca_en50221_camchange_irq(struct dvb_ca_en50221 *pubca, int slot,
+				  int change_type);
 
 /**
  * dvb_ca_en50221_camready_irq - A CAMREADY IRQ has occurred.
@@ -100,7 +97,7 @@ void dvb_ca_en50221_camchange_irq(struct dvb_ca_en50221* pubca, int slot, int ch
  * @pubca: CA instance.
  * @slot: Slot concerned.
  */
-void dvb_ca_en50221_camready_irq(struct dvb_ca_en50221* pubca, int slot);
+void dvb_ca_en50221_camready_irq(struct dvb_ca_en50221 *pubca, int slot);
 
 /**
  * dvb_ca_en50221_frda_irq - An FR or a DA IRQ has occurred.
@@ -108,12 +105,11 @@ void dvb_ca_en50221_camready_irq(struct dvb_ca_en50221* pubca, int slot);
  * @ca: CA instance.
  * @slot: Slot concerned.
  */
-void dvb_ca_en50221_frda_irq(struct dvb_ca_en50221* ca, int slot);
+void dvb_ca_en50221_frda_irq(struct dvb_ca_en50221 *ca, int slot);
 
-
-
-/* ******************************************************************************** */
-/* Initialisation/shutdown functions */
+/*
+ * Initialisation/shutdown functions
+ */
 
 /**
  * dvb_ca_en50221_init - Initialise a new DVB CA device.
@@ -125,15 +121,15 @@ void dvb_ca_en50221_frda_irq(struct dvb_ca_en50221* ca, int slot);
  *
  * @return 0 on success, nonzero on failure
  */
-extern int dvb_ca_en50221_init(struct dvb_adapter *dvb_adapter, struct dvb_ca_en50221* ca, int flags, int slot_count);
+extern int dvb_ca_en50221_init(struct dvb_adapter *dvb_adapter,
+			       struct dvb_ca_en50221 *ca, int flags,
+			       int slot_count);
 
 /**
  * dvb_ca_en50221_release - Release a DVB CA device.
  *
  * @ca: The associated dvb_ca instance.
  */
-extern void dvb_ca_en50221_release(struct dvb_ca_en50221* ca);
-
-
+extern void dvb_ca_en50221_release(struct dvb_ca_en50221 *ca);
 
 #endif
-- 
2.4.3

[PATCH 11/26] [media] DocBook: Move struct dmx_demux kABI doc to demux.h

[Mauro Carvalho Chehab]

The DocBook/media/dvb/kdapi.xml contains the description of
the kABI for DVB. The problem is that, by being maintained
on a separate file and not being updated for years, it got
outdated. So, for example, some callback parameters were
changed, but the DocBook were still using the old stuff.

As a first step to fix it, let's move the documentation of
struct dmx_demux into demux.h and fix the parameters used
there.

For now, don't document any other field nor touch the
descriptions that got moved, letting this job to other
patches. That makes easier to review the patch.

PS.: Please notice that an additional patch will be needed
in order to fix the return values (some uses non-existent
return codes) and to the functions and callbacks mentioned at
the descriptions.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index 44634e295699..8d5620aeaf36 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -239,6 +239,7 @@ X!Isound/sound_firmware.c
      </sect1>
      <sect1><title>Digital TV (DVB) devices</title>
 !Idrivers/media/dvb-core/dvb_ca_en50221.h
+!Idrivers/media/dvb-core/demux.h
 !Idrivers/media/dvb-core/dvb_frontend.h
 !Idrivers/media/dvb-core/dvb_math.h
 !Idrivers/media/dvb-core/dvb_ringbuffer.h
diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml
index 68bcd33a82c3..6efc3ab7944e 100644
--- a/Documentation/DocBook/media/dvb/kdapi.xml
+++ b/Documentation/DocBook/media/dvb/kdapi.xml
@@ -214,62 +214,6 @@ should be kept identical) to the types in the demux device.
   &#x22C6; to the type &#x22C6; dmx_frontend_t
   &#x22C6;.
  &#x22C6;/
-
- #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list)
-
- struct dmx_demux_s {
-	 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
-	 char&#x22C6; id;                    /&#x22C6; Unique demux identifier &#x22C6;/
-	 char&#x22C6; vendor;                /&#x22C6; Name of the demux vendor &#x22C6;/
-	 char&#x22C6; model;                 /&#x22C6; Name of the demux model &#x22C6;/
-	 __u32 capabilities;          /&#x22C6; Bitfield of capability flags &#x22C6;/
-	 dmx_frontend_t&#x22C6; frontend;    /&#x22C6; Front-end connected to the demux &#x22C6;/
-	 struct list_head reg_list;   /&#x22C6; List of registered demuxes &#x22C6;/
-	 void&#x22C6; priv;                  /&#x22C6; Pointer to private data of the API client &#x22C6;/
-	 int users;                   /&#x22C6; Number of users &#x22C6;/
-	 int (&#x22C6;open) (struct dmx_demux_s&#x22C6; demux);
-	 int (&#x22C6;close) (struct dmx_demux_s&#x22C6; demux);
-	 int (&#x22C6;write) (struct dmx_demux_s&#x22C6; demux, const char&#x22C6; buf, size_t count);
-	 int (&#x22C6;allocate_ts_feed) (struct dmx_demux_s&#x22C6; demux,
-				  dmx_ts_feed_t&#x22C6;&#x22C6; feed,
-				  dmx_ts_cb callback);
-	 int (&#x22C6;release_ts_feed) (struct dmx_demux_s&#x22C6; demux,
-				 dmx_ts_feed_t&#x22C6; feed);
-	 int (&#x22C6;allocate_pes_feed) (struct dmx_demux_s&#x22C6; demux,
-				   dmx_pes_feed_t&#x22C6;&#x22C6; feed,
-				   dmx_pes_cb callback);
-	 int (&#x22C6;release_pes_feed) (struct dmx_demux_s&#x22C6; demux,
-				  dmx_pes_feed_t&#x22C6; feed);
-	 int (&#x22C6;allocate_section_feed) (struct dmx_demux_s&#x22C6; demux,
-				       dmx_section_feed_t&#x22C6;&#x22C6; feed,
-				       dmx_section_cb callback);
-	 int (&#x22C6;release_section_feed) (struct dmx_demux_s&#x22C6; demux,
-				      dmx_section_feed_t&#x22C6; feed);
-	 int (&#x22C6;descramble_mac_address) (struct dmx_demux_s&#x22C6; demux,
-					__u8&#x22C6; buffer1,
-					size_t buffer1_length,
-					__u8&#x22C6; buffer2,
-					size_t buffer2_length,
-					__u16 pid);
-	 int (&#x22C6;descramble_section_payload) (struct dmx_demux_s&#x22C6; demux,
-					    __u8&#x22C6; buffer1,
-					    size_t buffer1_length,
-					    __u8&#x22C6; buffer2, size_t buffer2_length,
-					    __u16 pid);
-	 int (&#x22C6;add_frontend) (struct dmx_demux_s&#x22C6; demux,
-			      dmx_frontend_t&#x22C6; frontend);
-	 int (&#x22C6;remove_frontend) (struct dmx_demux_s&#x22C6; demux,
-				 dmx_frontend_t&#x22C6; frontend);
-	 struct list_head&#x22C6; (&#x22C6;get_frontends) (struct dmx_demux_s&#x22C6; demux);
-	 int (&#x22C6;connect_frontend) (struct dmx_demux_s&#x22C6; demux,
-				  dmx_frontend_t&#x22C6; frontend);
-	 int (&#x22C6;disconnect_frontend) (struct dmx_demux_s&#x22C6; demux);
-
-
-	 /&#x22C6; added because js cannot keep track of these himself &#x22C6;/
-	 int (&#x22C6;get_pes_pids) (struct dmx_demux_s&#x22C6; demux, __u16 &#x22C6;pids);
- };
- typedef struct dmx_demux_s dmx_demux_t;
 </programlisting>
 
 </section>
@@ -487,985 +431,7 @@ interface from a bottom half context. Thus, if a demux API function is called fr
 device code, the function must not sleep.
 </para>
 
-
-<section id="kdapi_fopen">
-<title>open()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function reserves the demux for use by the caller and, if necessary,
- initializes the demux. When the demux is no longer needed, the function close()
- should be called. It should be possible for multiple clients to access the demux
- at the same time. Thus, the function implementation should increment the
- demux usage count when open() is called and decrement it when close() is
- called.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int open ( demux_t&#x22C6; demux );</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EUSERS</para>
-</entry><entry
- align="char">
-<para>Maximum usage count reached.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
 </section>
-<section id="kdapi_fclose">
-<title>close()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function reserves the demux for use by the caller and, if necessary,
- initializes the demux. When the demux is no longer needed, the function close()
- should be called. It should be possible for multiple clients to access the demux
- at the same time. Thus, the function implementation should increment the
- demux usage count when open() is called and decrement it when close() is
- called.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int close(demux_t&#x22C6; demux);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENODEV</para>
-</entry><entry
- align="char">
-<para>The demux was not in use.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-<section id="kdapi_fwrite">
-<title>write()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function provides the demux driver with a memory buffer containing TS
- packets. Instead of receiving TS packets from the DVB front-end, the demux
- driver software will read packets from memory. Any clients of this demux
- with active TS, PES or Section filters will receive filtered data via the Demux
- callback API (see 0). The function returns when all the data in the buffer has
- been consumed by the demux. Demux hardware typically cannot read TS from
- memory. If this is the case, memory-based filtering has to be implemented
- entirely in software.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int write(demux_t&#x22C6; demux, const char&#x22C6; buf, size_t
- count);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>const char* buf</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS data in kernel-space memory.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t length</para>
-</entry><entry
- align="char">
-<para>Length of the TS data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>The command is not implemented.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>allocate_ts_feed()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Allocates a new TS feed, which is used to filter the TS packets carrying a
- certain PID. The TS feed normally corresponds to a hardware PID filter on the
- demux chip.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int allocate_ts_feed(dmx_demux_t&#x22C6; demux,
- dmx_ts_feed_t&#x22C6;&#x22C6; feed, dmx_ts_cb callback);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_ts_feed_t**
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_ts_cb callback</para>
-</entry><entry
- align="char">
-<para>Pointer to the callback function for passing received TS
- packet</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EBUSY</para>
-</entry><entry
- align="char">
-<para>No more TS feeds available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>The command is not implemented.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>release_ts_feed()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in
- progress on the TS feed should be stopped before calling this function.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int release_ts_feed(dmx_demux_t&#x22C6; demux,
- dmx_ts_feed_t&#x22C6; feed);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t* demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_ts_feed_t* feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>allocate_section_feed()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Allocates a new section feed, i.e. a demux resource for filtering and receiving
- sections. On platforms with hardware support for section filtering, a section
- feed is directly mapped to the demux HW. On other platforms, TS packets are
- first PID filtered in hardware and a hardware section filter then emulated in
- software. The caller obtains an API pointer of type dmx_section_feed_t as an
- out parameter. Using this API the caller can set filtering parameters and start
- receiving sections.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int allocate_section_feed(dmx_demux_t&#x22C6; demux,
- dmx_section_feed_t &#x22C6;&#x22C6;feed, dmx_section_cb callback);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t *demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_feed_t
- **feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_cb
- callback</para>
-</entry><entry
- align="char">
-<para>Pointer to the callback function for passing received
- sections.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EBUSY</para>
-</entry><entry
- align="char">
-<para>No more section feeds available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>The command is not implemented.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>release_section_feed()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Releases the resources allocated with allocate_section_feed(), including
- allocated filters. Any filtering in progress on the section feed should be stopped
- before calling this function.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int release_section_feed(dmx_demux_t&#x22C6; demux,
- dmx_section_feed_t &#x22C6;feed);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>demux_t *demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_feed_t
- *feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>descramble_mac_address()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function runs a descrambling algorithm on the destination MAC
- address field of a DVB Datagram Section, replacing the original address
- with its un-encrypted version. Otherwise, the description on the function
- descramble_section_payload() applies also to this function.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int descramble_mac_address(dmx_demux_t&#x22C6; demux, __u8
- &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
- size_t buffer2_length, __u16 pid);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t
- *demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8 *buffer1</para>
-</entry><entry
- align="char">
-<para>Pointer to the first byte of the section.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer1_length</para>
-</entry><entry
- align="char">
-<para>Length of the section data, including headers and CRC,
- in buffer1.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8* buffer2</para>
-</entry><entry
- align="char">
-<para>Pointer to the tail of the section data, or NULL. The
- pointer has a non-NULL value if the section wraps past
- the end of a circular buffer.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer2_length</para>
-</entry><entry
- align="char">
-<para>Length of the section data, including headers and CRC,
- in buffer2.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 pid</para>
-</entry><entry
- align="char">
-<para>The PID on which the section was received. Useful
- for obtaining the descrambling key, e.g. from a DVB
- Common Access facility.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>No descrambling facility available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>descramble_section_payload()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function runs a descrambling algorithm on the payload of a DVB
- Datagram Section, replacing the original payload with its un-encrypted
- version. The function will be called from the demux API implementation;
- the API client need not call this function directly. Section-level scrambling
- algorithms are currently standardized only for DVB-RCC (return channel
- over 2-directional cable TV network) systems. For all other DVB networks,
- encryption schemes are likely to be proprietary to each data broadcaster. Thus,
- it is expected that this function pointer will have the value of NULL (i.e.,
- function not available) in most demux API implementations. Nevertheless, it
- should be possible to use the function pointer as a hook for dynamically adding
- a &#8220;plug-in&#8221; descrambling facility to a demux driver.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>While this function is not needed with hardware-based section descrambling,
- the descramble_section_payload function pointer can be used to override the
- default hardware-based descrambling algorithm: if the function pointer has a
- non-NULL value, the corresponding function should be used instead of any
- descrambling hardware.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int descramble_section_payload(dmx_demux_t&#x22C6; demux,
- __u8 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
- size_t buffer2_length, __u16 pid);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t
- *demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8 *buffer1</para>
-</entry><entry
- align="char">
-<para>Pointer to the first byte of the section.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer1_length</para>
-</entry><entry
- align="char">
-<para>Length of the section data, including headers and CRC,
- in buffer1.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8 *buffer2</para>
-</entry><entry
- align="char">
-<para>Pointer to the tail of the section data, or NULL. The
- pointer has a non-NULL value if the section wraps past
- the end of a circular buffer.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer2_length</para>
-</entry><entry
- align="char">
-<para>Length of the section data, including headers and CRC,
- in buffer2.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 pid</para>
-</entry><entry
- align="char">
-<para>The PID on which the section was received. Useful
- for obtaining the descrambling key, e.g. from a DVB
- Common Access facility.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>No descrambling facility available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>add_frontend()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Registers a connectivity between a demux and a front-end, i.e., indicates that
- the demux can be connected via a call to connect_frontend() to use the given
- front-end as a TS source. The client of this function has to allocate dynamic or
- static memory for the frontend structure and initialize its fields before calling
- this function. This function is normally called during the driver initialization.
- The caller must not free the memory of the frontend struct before successfully
- calling remove_frontend().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int add_frontend(dmx_demux_t &#x22C6;demux, dmx_frontend_t
- &#x22C6;frontend);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_frontend_t*
- frontend</para>
-</entry><entry
- align="char">
-<para>Pointer to the front-end instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EEXIST</para>
-</entry><entry
- align="char">
-<para>A front-end with the same value of the id field already
- registered.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINUSE</para>
-</entry><entry
- align="char">
-<para>The demux is in use.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOMEM</para>
-</entry><entry
- align="char">
-<para>No more front-ends can be added.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>remove_frontend()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Indicates that the given front-end, registered by a call to add_frontend(), can
- no longer be connected as a TS source by this demux. The function should be
- called when a front-end driver or a demux driver is removed from the system.
- If the front-end is in use, the function fails with the return value of -EBUSY.
- After successfully calling this function, the caller can free the memory of
- the frontend struct if it was dynamically allocated before the add_frontend()
- operation.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int remove_frontend(dmx_demux_t&#x22C6; demux,
- dmx_frontend_t&#x22C6; frontend);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_frontend_t*
- frontend</para>
-</entry><entry
- align="char">
-<para>Pointer to the front-end instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EBUSY</para>
-</entry><entry
- align="char">
-<para>The front-end is in use, i.e. a call to connect_frontend()
- has not been followed by a call to disconnect_frontend().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>get_frontends()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Provides the APIs of the front-ends that have been registered for this demux.
- Any of the front-ends obtained with this call can be used as a parameter for
- connect_frontend().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The include file demux.h contains the macro DMX_FE_ENTRY() for
- converting an element of the generic type struct list_head* to the type
- dmx_frontend_t*. The caller must not free the memory of any of the elements
- obtained via this function call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>struct list_head&#x22C6; get_frontends(dmx_demux_t&#x22C6; demux);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*</para>
-</entry><entry
- align="char">
-<para>A list of front-end interfaces, or NULL in the case of an
- empty list.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>connect_frontend()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Connects the TS output of the front-end to the input of the demux. A demux
- can only be connected to a front-end registered to the demux with the function
- add_frontend().</para>
-</entry>
- </row><row><entry
- align="char">
-<para>It may or may not be possible to connect multiple demuxes to the same
- front-end, depending on the capabilities of the HW platform. When not used,
- the front-end should be released by calling disconnect_frontend().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int connect_frontend(dmx_demux_t&#x22C6; demux,
- dmx_frontend_t&#x22C6; frontend);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_frontend_t*
- frontend</para>
-</entry><entry
- align="char">
-<para>Pointer to the front-end instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EBUSY</para>
-</entry><entry
- align="char">
-<para>The front-end is in use.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>disconnect_frontend()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Disconnects the demux and a front-end previously connected by a
- connect_frontend() call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int disconnect_frontend(dmx_demux_t&#x22C6; demux);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
 <section id="demux_callback_api">
 <title>Demux Callback API</title>
 <para>This kernel-space API comprises the callback functions that deliver filtered data to the
diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 833191bcd810..54c3df38bb1b 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -202,10 +202,197 @@ struct dmx_frontend {
 
 #define DMX_FE_ENTRY(list) list_entry(list, struct dmx_frontend, connectivity_list)
 
+/**
+ * struct dmx_demux - Structure that contains the demux capabilities and
+ *		      callbacks.
+ *
+ * @capabilities: Bitfield of capability flags
+ *
+ * @frontend: Front-end connected to the demux
+ *
+ * @priv: Pointer to private data of the API client
+ *
+ * @open: This function reserves the demux for use by the caller and, if
+ *	necessary, initializes the demux. When the demux is no longer needed,
+ * 	the function close() should be called. It should be possible for
+ *	multiple clients to access the demux at the same time. Thus, the
+ *	function implementation should increment the demux usage count when
+ *	open() is called and decrement it when close() is called.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	It returns
+ *		0 on success;
+ * 		-EUSERS, if maximum usage count was reached;
+ *		-EINVAL, on bad parameter.
+ *
+ * @close: This function reserves the demux for use by the caller and, if
+ *	necessary, initializes the demux. When the demux is no longer needed,
+ *	the function close() should be called. It should be possible for
+ *	multiple clients to access the demux at the same time. Thus, the
+ *	function implementation should increment the demux usage count when
+ *	open() is called and decrement it when close() is called.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	It returns
+ *		0 on success;
+ *		-ENODEV, if demux was not in use
+ *		-EINVAL, on bad parameter.
+ *
+ * @write: This function provides the demux driver with a memory buffer
+ *	containing TS packets. Instead of receiving TS packets from the DVB
+ *	front-end, the demux driver software will read packets from memory.
+ *	Any clients of this demux with active TS, PES or Section filters will
+ *	receive filtered data via the Demux callback API (see 0). The function
+ *	returns when all the data in the buffer has been consumed by the demux.
+ *	Demux hardware typically cannot read TS from memory. If this is the
+ *	case, memory-based filtering has to be implemented entirely in software.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @buf function parameter contains a pointer to the TS data in
+ *	kernel-space memory.
+ *	The @count function parameter contains the length of the TS data.
+ *	It returns
+ *		0 on success;
+ *		-ENOSYS, if the command is not implemented;
+ *		-EINVAL, on bad parameter.
+ *
+ * @allocate_ts_feed: Allocates a new TS feed, which is used to filter the TS
+ *	packets carrying a certain PID. The TS feed normally corresponds to a
+ *	hardware PID filter on the demux chip.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @feed function parameter contains a pointer to the TS feed API and
+ *	instance data.
+ *	The @callback function parameter contains a pointer to the callback
+ *	function for passing received TS packet.
+ *	It returns
+ *		0 on success;
+ *		-EBUSY, if no more TS feeds is available;
+ *		-ENOSYS, if the command is not implemented;
+ *		-EINVAL, on bad parameter.
+ *
+ * @release_ts_feed: Releases the resources allocated with allocate_ts_feed().
+ *	Any filtering in progress on the TS feed should be stopped before
+ *	calling this function.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @feed function parameter contains a pointer to the TS feed API and
+ *	instance data.
+ *	It returns
+ *		0 on success;
+ *		-EINVAL on bad parameter.
+ *
+ * @allocate_section_feed: Allocates a new section feed, i.e. a demux resource
+ *	for filtering and receiving sections. On platforms with hardware
+ *	support for section filtering, a section feed is directly mapped to
+ *	the demux HW. On other platforms, TS packets are first PID filtered in
+ *	hardware and a hardware section filter then emulated in software. The
+ *	caller obtains an API pointer of type dmx_section_feed_t as an out
+ *	parameter. Using this API the caller can set filtering parameters and
+ *	start receiving sections.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @feed function parameter contains a pointer to the TS feed API and
+ *	instance data.
+ *	The @callback function parameter contains a pointer to the callback
+ *	function for passing received TS packet.
+ *	It returns
+ *		0 on success;
+ *		-EBUSY, if no more TS feeds is available;
+ *		-ENOSYS, if the command is not implemented;
+ *		-EINVAL, on bad parameter.
+ *
+ * @release_section_feed: Releases the resources allocated with
+ *	allocate_section_feed(), including allocated filters. Any filtering in
+ *	progress on the section feed should be stopped before calling this
+ *	function.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @feed function parameter contains a pointer to the TS feed API and
+ *	instance data.
+ *	It returns
+ *		0 on success;
+ *		-EINVAL, on bad parameter.
+ *
+ * @add_frontend: Registers a connectivity between a demux and a front-end,
+ *	i.e., indicates that the demux can be connected via a call to
+ *	connect_frontend() to use the given front-end as a TS source. The
+ *	client of this function has to allocate dynamic or static memory for
+ *	the frontend structure and initialize its fields before calling this
+ *	function. This function is normally called during the driver
+ *	initialization. The caller must not free the memory of the frontend
+ *	struct before successfully calling remove_frontend().
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @frontend function parameter contains a pointer to the front-end
+ *	instance data.
+ *	It returns
+ *		0 on success;
+ *		-EEXIST, if a front-end with the same value of the id field
+ *			already registered;
+ * 		-EINUSE, if the demux is in use;
+ *		-ENOMEM, if no more front-ends can be added;
+ *		-EINVAL, on bad parameter.
+ *
+ * @remove_frontend: Indicates that the given front-end, registered by a call
+ *	to add_frontend(), can no longer be connected as a TS source by this
+ *	demux. The function should be called when a front-end driver or a demux
+ *	driver is removed from the system. If the front-end is in use, the
+ *	function fails with the return value of -EBUSY. After successfully
+ *	calling this function, the caller can free the memory of the frontend
+ *	struct if it was dynamically allocated before the add_frontend()
+ *	operation.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @frontend function parameter contains a pointer to the front-end
+ *	instance data.
+ *	It returns
+ *		0 on success;
+ *		-EBUSY, if the front-end is in use, i.e. a call to
+ *			connect_frontend() has not been followed by a call to
+ *			disconnect_frontend();
+ *		-EINVAL, on bad parameter.
+ *
+ * @get_frontends: Provides the APIs of the front-ends that have been
+ *	registered for this demux. Any of the front-ends obtained with this
+ *	call can be used as a parameter for connect_frontend(). The include
+ *	file demux.h contains the macro DMX_FE_ENTRY() for converting an
+ *	element of the generic type struct list_head* to the type
+ * 	dmx_frontend_t*. The caller must not free the memory of any of the
+ *	elements obtained via this function call.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	It returns a struct list_head pointer to the list of front-end
+ *	interfaces, or NULL in the case of an empty list.
+ *
+ * @connect_frontend: Connects the TS output of the front-end to the input of
+ *	the demux. A demux can only be connected to a front-end registered to
+ *	the demux with the function add_frontend(). It may or may not be
+ *	possible to connect multiple demuxes to the same front-end, depending
+ *	on the capabilities of the HW platform. When not used, the front-end
+ *	should be released by calling disconnect_frontend().
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @frontend function parameter contains a pointer to the front-end
+ *	instance data.
+ *	It returns
+ *		0 on success;
+ *		-EBUSY, if the front-end is in use;
+ *		-EINVAL, on bad parameter.
+ *
+ * @disconnect_frontend: Disconnects the demux and a front-end previously
+ *	connected by a connect_frontend() call.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	It returns
+ *		0 on success;
+ *		-EINVAL on bad parameter.
+ */
+
 struct dmx_demux {
-	u32 capabilities;            /* Bitfield of capability flags */
-	struct dmx_frontend* frontend;    /* Front-end connected to the demux */
-	void* priv;                  /* Pointer to private data of the API client */
+	u32 capabilities;
+	struct dmx_frontend* frontend;
+	void* priv;
 	int (*open) (struct dmx_demux* demux);
 	int (*close) (struct dmx_demux* demux);
 	int (*write) (struct dmx_demux* demux, const char __user *buf, size_t count);
-- 
2.4.3

[PATCH 12/26] [media] DocBook: update documented fields at struct dmx_demux

[Mauro Carvalho Chehab]

There are a few inconsistencies between the old documentation
that got imported into the header and the current status.

Update them, and use the proper doc-nano nomenclature for
struct artuments "@", instead of foo().

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 54c3df38bb1b..ca56d1cc57bd 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -214,10 +214,10 @@ struct dmx_frontend {
  *
  * @open: This function reserves the demux for use by the caller and, if
  *	necessary, initializes the demux. When the demux is no longer needed,
- * 	the function close() should be called. It should be possible for
+ * 	the function @close should be called. It should be possible for
  *	multiple clients to access the demux at the same time. Thus, the
  *	function implementation should increment the demux usage count when
- *	open() is called and decrement it when close() is called.
+ *	@open is called and decrement it when @close is called.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
  *	It returns
@@ -227,15 +227,15 @@ struct dmx_frontend {
  *
  * @close: This function reserves the demux for use by the caller and, if
  *	necessary, initializes the demux. When the demux is no longer needed,
- *	the function close() should be called. It should be possible for
+ *	the function @close should be called. It should be possible for
  *	multiple clients to access the demux at the same time. Thus, the
  *	function implementation should increment the demux usage count when
- *	open() is called and decrement it when close() is called.
+ *	@open is called and decrement it when @close is called.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
  *	It returns
  *		0 on success;
- *		-ENODEV, if demux was not in use
+ *		-ENODEV, if demux was not in use (e. g. no users);
  *		-EINVAL, on bad parameter.
  *
  * @write: This function provides the demux driver with a memory buffer
@@ -253,7 +253,9 @@ struct dmx_frontend {
  *	The @count function parameter contains the length of the TS data.
  *	It returns
  *		0 on success;
- *		-ENOSYS, if the command is not implemented;
+ *		-ERESTARTSYS, if mutex lock was interrupted;
+ *		-EINTR, if a signal handling is pending;
+ *		-ENODEV, if demux was removed;
  *		-EINVAL, on bad parameter.
  *
  * @allocate_ts_feed: Allocates a new TS feed, which is used to filter the TS
@@ -267,11 +269,11 @@ struct dmx_frontend {
  *	function for passing received TS packet.
  *	It returns
  *		0 on success;
+ *		-ERESTARTSYS, if mutex lock was interrupted;
  *		-EBUSY, if no more TS feeds is available;
- *		-ENOSYS, if the command is not implemented;
  *		-EINVAL, on bad parameter.
  *
- * @release_ts_feed: Releases the resources allocated with allocate_ts_feed().
+ * @release_ts_feed: Releases the resources allocated with @allocate_ts_feed.
  *	Any filtering in progress on the TS feed should be stopped before
  *	calling this function.
  *	The @demux function parameter contains a pointer to the demux API and
@@ -299,11 +301,10 @@ struct dmx_frontend {
  *	It returns
  *		0 on success;
  *		-EBUSY, if no more TS feeds is available;
- *		-ENOSYS, if the command is not implemented;
  *		-EINVAL, on bad parameter.
  *
  * @release_section_feed: Releases the resources allocated with
- *	allocate_section_feed(), including allocated filters. Any filtering in
+ *	@allocate_section_feed, including allocated filters. Any filtering in
  *	progress on the section feed should be stopped before calling this
  *	function.
  *	The @demux function parameter contains a pointer to the demux API and
@@ -316,31 +317,27 @@ struct dmx_frontend {
  *
  * @add_frontend: Registers a connectivity between a demux and a front-end,
  *	i.e., indicates that the demux can be connected via a call to
- *	connect_frontend() to use the given front-end as a TS source. The
+ *	@connect_frontend to use the given front-end as a TS source. The
  *	client of this function has to allocate dynamic or static memory for
  *	the frontend structure and initialize its fields before calling this
  *	function. This function is normally called during the driver
  *	initialization. The caller must not free the memory of the frontend
- *	struct before successfully calling remove_frontend().
+ *	struct before successfully calling @remove_frontend.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
  *	The @frontend function parameter contains a pointer to the front-end
  *	instance data.
  *	It returns
  *		0 on success;
- *		-EEXIST, if a front-end with the same value of the id field
- *			already registered;
- * 		-EINUSE, if the demux is in use;
- *		-ENOMEM, if no more front-ends can be added;
  *		-EINVAL, on bad parameter.
  *
  * @remove_frontend: Indicates that the given front-end, registered by a call
- *	to add_frontend(), can no longer be connected as a TS source by this
+ *	to @add_frontend, can no longer be connected as a TS source by this
  *	demux. The function should be called when a front-end driver or a demux
  *	driver is removed from the system. If the front-end is in use, the
  *	function fails with the return value of -EBUSY. After successfully
  *	calling this function, the caller can free the memory of the frontend
- *	struct if it was dynamically allocated before the add_frontend()
+ *	struct if it was dynamically allocated before the @add_frontend
  *	operation.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
@@ -348,18 +345,16 @@ struct dmx_frontend {
  *	instance data.
  *	It returns
  *		0 on success;
- *		-EBUSY, if the front-end is in use, i.e. a call to
- *			connect_frontend() has not been followed by a call to
- *			disconnect_frontend();
+ *		-ENODEV, if the front-end was not found,
  *		-EINVAL, on bad parameter.
  *
  * @get_frontends: Provides the APIs of the front-ends that have been
  *	registered for this demux. Any of the front-ends obtained with this
- *	call can be used as a parameter for connect_frontend(). The include
+ *	call can be used as a parameter for @connect_frontend. The include
  *	file demux.h contains the macro DMX_FE_ENTRY() for converting an
- *	element of the generic type struct list_head* to the type
- * 	dmx_frontend_t*. The caller must not free the memory of any of the
- *	elements obtained via this function call.
+ *	element of the generic type struct &list_head * to the type
+ * 	struct &dmx_frontend *. The caller must not free the memory of any of
+ *	the elements obtained via this function call.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
  *	It returns a struct list_head pointer to the list of front-end
@@ -367,21 +362,20 @@ struct dmx_frontend {
  *
  * @connect_frontend: Connects the TS output of the front-end to the input of
  *	the demux. A demux can only be connected to a front-end registered to
- *	the demux with the function add_frontend(). It may or may not be
+ *	the demux with the function @add_frontend. It may or may not be
  *	possible to connect multiple demuxes to the same front-end, depending
  *	on the capabilities of the HW platform. When not used, the front-end
- *	should be released by calling disconnect_frontend().
+ *	should be released by calling @disconnect_frontend.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
  *	The @frontend function parameter contains a pointer to the front-end
  *	instance data.
  *	It returns
  *		0 on success;
- *		-EBUSY, if the front-end is in use;
  *		-EINVAL, on bad parameter.
  *
  * @disconnect_frontend: Disconnects the demux and a front-end previously
- *	connected by a connect_frontend() call.
+ *	connected by a @connect_frontend call.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
  *	It returns
-- 
2.4.3

[PATCH 13/26] [media] dvb: don't keep support for undocumented features

[Mauro Carvalho Chehab]

There are two DVB demux callbacks and ioctls that aren't documented
and aren't used at all by the DVB core or by any DVB driver upstream.

Let's comment out the code for those two ioctls and remove on some
future version.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index ca56d1cc57bd..53c82514ede5 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -411,10 +411,12 @@ struct dmx_demux {
 
 	int (*get_pes_pids) (struct dmx_demux* demux, u16 *pids);
 
+	/* private: Not used upstream and never documented */
+#if 0
 	int (*get_caps) (struct dmx_demux* demux, struct dmx_caps *caps);
-
 	int (*set_source) (struct dmx_demux* demux, const dmx_source_t *src);
-
+#endif
+	/* public: */
 	int (*get_stc) (struct dmx_demux* demux, unsigned int num,
 			u64 *stc, unsigned int *base);
 };
diff --git a/drivers/media/dvb-core/dmxdev.c b/drivers/media/dvb-core/dmxdev.c
index d0e3f9d85f34..86a987ef13e1 100644
--- a/drivers/media/dvb-core/dmxdev.c
+++ b/drivers/media/dvb-core/dmxdev.c
@@ -1023,6 +1023,9 @@ static int dvb_demux_do_ioctl(struct file *file,
 		dmxdev->demux->get_pes_pids(dmxdev->demux, parg);
 		break;
 
+#if 0
+	/* Not used upstream and never documented */
+
 	case DMX_GET_CAPS:
 		if (!dmxdev->demux->get_caps) {
 			ret = -EINVAL;
@@ -1038,6 +1041,7 @@ static int dvb_demux_do_ioctl(struct file *file,
 		}
 		ret = dmxdev->demux->set_source(dmxdev->demux, parg);
 		break;
+#endif
 
 	case DMX_GET_STC:
 		if (!dmxdev->demux->get_stc) {
-- 
2.4.3

[PATCH 14/26] [media] DocBook: finish documenting struct dmx_demux

[Mauro Carvalho Chehab]

There are two callbacks still not documented:
	.//drivers/media/dvb-core/demux.h:422: warning: No description found for parameter 'get_pes_pids'
	.//drivers/media/dvb-core/demux.h:422: warning: No description found for parameter 'get_stc'

The purpose of first one is clear. The second one is used only
on the obsolete av7110 driver, and its purpose is not clear,
as it just returns a 64-bit word from the firmware to userspace.

Let's document get_pes_pids and mark get_stc as private, adding
a comment to not use it, while this is not documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 53c82514ede5..b045a598fb2d 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -381,6 +381,16 @@ struct dmx_frontend {
  *	It returns
  *		0 on success;
  *		-EINVAL on bad parameter.
+ *
+ * @get_pes_pids: Get the PIDs for DMX_PES_AUDIO0, DMX_PES_VIDEO0,
+ *	DMX_PES_TELETEXT0, DMX_PES_SUBTITLE0 and DMX_PES_PCR0.
+ *	The @demux function parameter contains a pointer to the demux API and
+ *	instance data.
+ *	The @pids function parameter contains an array with five u16 elements
+ *	where the PIDs will be stored.
+ *	It returns
+ *		0 on success;
+ *		-EINVAL on bad parameter.
  */
 
 struct dmx_demux {
@@ -416,7 +426,11 @@ struct dmx_demux {
 	int (*get_caps) (struct dmx_demux* demux, struct dmx_caps *caps);
 	int (*set_source) (struct dmx_demux* demux, const dmx_source_t *src);
 #endif
-	/* public: */
+	/*
+	 * private: Only used at av7110, to read some data from firmware.
+	 *	As this was never documented, we have no clue about what's
+	 * 	there, and its usage on other drivers aren't encouraged.
+	 */
 	int (*get_stc) (struct dmx_demux* demux, unsigned int num,
 			u64 *stc, unsigned int *base);
 };
-- 
2.4.3

[PATCH 15/26] [media] dvb: get rid of enum dmx_success

[Mauro Carvalho Chehab]

This enum is not actually used anymore. The only value used from
the enum is DMX_OK, passed as a parameter on two callbacks.

Yet, this value is not used anywhere. So, just remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml
index 6efc3ab7944e..1acae6730151 100644
--- a/Documentation/DocBook/media/dvb/kdapi.xml
+++ b/Documentation/DocBook/media/dvb/kdapi.xml
@@ -11,20 +11,6 @@ DVB device driver writers. The header file for this API is named <constant>demux
 <title>Kernel Demux Data Types</title>
 
 
-<section id="dmx_success_t">
-<title>dmx_success_t</title>
- <programlisting>
- typedef enum {
-   DMX_OK = 0, /&#x22C6; Received Ok &#x22C6;/
-   DMX_LENGTH_ERROR, /&#x22C6; Incorrect length &#x22C6;/
-   DMX_OVERRUN_ERROR, /&#x22C6; Receiver ring buffer overrun &#x22C6;/
-   DMX_CRC_ERROR, /&#x22C6; Incorrect CRC &#x22C6;/
-   DMX_FRAME_ERROR, /&#x22C6; Frame alignment error &#x22C6;/
-   DMX_FIFO_ERROR, /&#x22C6; Receiver FIFO overrun &#x22C6;/
-   DMX_MISSED_ERROR /&#x22C6; Receiver missed packet &#x22C6;/
- } dmx_success_t;
-</programlisting>
-
 </section>
 <section id="ts_filter_types">
 <title>TS filter types</title>
@@ -143,22 +129,19 @@ should be kept identical) to the types in the demux device.
 			    size_t buffer1_length,
 			    __u8 &#x22C6; buffer2,
 			    size_t buffer2_length,
-			    dmx_ts_feed_t&#x22C6; source,
-			    dmx_success_t success);
+			    dmx_ts_feed_t&#x22C6; source)
 
  typedef int (&#x22C6;dmx_section_cb) ( __u8 &#x22C6; buffer1,
 				 size_t buffer1_len,
 				 __u8 &#x22C6; buffer2,
 				 size_t buffer2_len,
-				 dmx_section_filter_t &#x22C6; source,
-				 dmx_success_t success);
+				 dmx_section_filter_t &#x22C6; source);
 
  typedef int (&#x22C6;dmx_pes_cb) ( __u8 &#x22C6; buffer1,
 			     size_t buffer1_len,
 			     __u8 &#x22C6; buffer2,
 			     size_t buffer2_len,
-			     dmx_pes_filter_t&#x22C6; source,
-			     dmx_success_t success);
+			     dmx_pes_filter_t&#x22C6; source);
 
  /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
  /&#x22C6; DVB Front-End &#x22C6;/
@@ -523,7 +506,7 @@ role="subsection"><title>dmx_ts_cb()</title>
  align="char">
 <para>int dmx_ts_cb(__u8&#x22C6; buffer1, size_t buffer1_length,
  __u8&#x22C6; buffer2, size_t buffer2_length, dmx_ts_feed_t&#x22C6;
- source, dmx_success_t success);</para>
+ source);</para>
 </entry>
  </row></tbody></tgroup></informaltable>
 <para>PARAMETERS
@@ -564,14 +547,6 @@ role="subsection"><title>dmx_ts_cb()</title>
  align="char">
 <para>Indicates which TS feed is the source of the callback.</para>
 </entry>
- </row><row><entry
- align="char">
-<para>dmx_success_t
- success</para>
-</entry><entry
- align="char">
-<para>Indicates if there was an error in TS reception.</para>
-</entry>
  </row></tbody></tgroup></informaltable>
 <para>RETURNS
 </para>
@@ -623,8 +598,7 @@ role="subsection"><title>dmx_section_cb()</title>
  align="char">
 <para>int dmx_section_cb(__u8&#x22C6; buffer1, size_t
  buffer1_length, __u8&#x22C6; buffer2, size_t
- buffer2_length, dmx_section_filter_t&#x22C6; source,
- dmx_success_t success);</para>
+ buffer2_length, dmx_section_filter_t&#x22C6; source);</para>
 </entry>
  </row></tbody></tgroup></informaltable>
 <para>PARAMETERS
@@ -669,14 +643,6 @@ role="subsection"><title>dmx_section_cb()</title>
  align="char">
 <para>Indicates the filter that triggered the callback.</para>
 </entry>
- </row><row><entry
- align="char">
-<para>dmx_success_t
- success</para>
-</entry><entry
- align="char">
-<para>Indicates if there was an error in section reception.</para>
-</entry>
  </row></tbody></tgroup></informaltable>
 <para>RETURNS
 </para>
diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index b045a598fb2d..2d036b36f551 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -55,21 +55,6 @@
 #define DMX_MAX_SECFEED_SIZE (DMX_MAX_SECTION_SIZE + 188)
 #endif
 
-
-/*
- * enum dmx_success: Success codes for the Demux Callback API.
- */
-
-enum dmx_success {
-  DMX_OK = 0, /* Received Ok */
-  DMX_LENGTH_ERROR, /* Incorrect length */
-  DMX_OVERRUN_ERROR, /* Receiver ring buffer overrun */
-  DMX_CRC_ERROR, /* Incorrect CRC */
-  DMX_FRAME_ERROR, /* Frame alignment error */
-  DMX_FIFO_ERROR, /* Receiver FIFO overrun */
-  DMX_MISSED_ERROR /* Receiver missed packet */
-} ;
-
 /*--------------------------------------------------------------------------*/
 /* TS packet reception */
 /*--------------------------------------------------------------------------*/
@@ -141,15 +126,13 @@ typedef int (*dmx_ts_cb) ( const u8 * buffer1,
 			   size_t buffer1_length,
 			   const u8 * buffer2,
 			   size_t buffer2_length,
-			   struct dmx_ts_feed* source,
-			   enum dmx_success success);
+			   struct dmx_ts_feed* source);
 
 typedef int (*dmx_section_cb) (	const u8 * buffer1,
 				size_t buffer1_len,
 				const u8 * buffer2,
 				size_t buffer2_len,
-				struct dmx_section_filter * source,
-				enum dmx_success success);
+				struct dmx_section_filter * source);
 
 /*--------------------------------------------------------------------------*/
 /* DVB Front-End */
diff --git a/drivers/media/dvb-core/dmxdev.c b/drivers/media/dvb-core/dmxdev.c
index 86a987ef13e1..ea9abde902e9 100644
--- a/drivers/media/dvb-core/dmxdev.c
+++ b/drivers/media/dvb-core/dmxdev.c
@@ -352,8 +352,7 @@ static void dvb_dmxdev_filter_timer(struct dmxdev_filter *dmxdevfilter)
 
 static int dvb_dmxdev_section_callback(const u8 *buffer1, size_t buffer1_len,
 				       const u8 *buffer2, size_t buffer2_len,
-				       struct dmx_section_filter *filter,
-				       enum dmx_success success)
+				       struct dmx_section_filter *filter)
 {
 	struct dmxdev_filter *dmxdevfilter = filter->priv;
 	int ret;
@@ -386,8 +385,7 @@ static int dvb_dmxdev_section_callback(const u8 *buffer1, size_t buffer1_len,
 
 static int dvb_dmxdev_ts_callback(const u8 *buffer1, size_t buffer1_len,
 				  const u8 *buffer2, size_t buffer2_len,
-				  struct dmx_ts_feed *feed,
-				  enum dmx_success success)
+				  struct dmx_ts_feed *feed)
 {
 	struct dmxdev_filter *dmxdevfilter = feed->priv;
 	struct dvb_ringbuffer *buffer;
diff --git a/drivers/media/dvb-core/dvb_demux.c b/drivers/media/dvb-core/dvb_demux.c
index 6c7ff0cdcd32..0cc5e935166c 100644
--- a/drivers/media/dvb-core/dvb_demux.c
+++ b/drivers/media/dvb-core/dvb_demux.c
@@ -130,7 +130,7 @@ static inline int dvb_dmx_swfilter_payload(struct dvb_demux_feed *feed,
 
 	feed->peslen += count;
 
-	return feed->cb.ts(&buf[p], count, NULL, 0, &feed->feed.ts, DMX_OK);
+	return feed->cb.ts(&buf[p], count, NULL, 0, &feed->feed.ts);
 }
 
 static int dvb_dmx_swfilter_sectionfilter(struct dvb_demux_feed *feed,
@@ -152,7 +152,7 @@ static int dvb_dmx_swfilter_sectionfilter(struct dvb_demux_feed *feed,
 		return 0;
 
 	return feed->cb.sec(feed->feed.sec.secbuf, feed->feed.sec.seclen,
-			    NULL, 0, &f->filter, DMX_OK);
+			    NULL, 0, &f->filter);
 }
 
 static inline int dvb_dmx_swfilter_section_feed(struct dvb_demux_feed *feed)
@@ -367,8 +367,7 @@ static inline void dvb_dmx_swfilter_packet_type(struct dvb_demux_feed *feed,
 			if (feed->ts_type & TS_PAYLOAD_ONLY)
 				dvb_dmx_swfilter_payload(feed, buf);
 			else
-				feed->cb.ts(buf, 188, NULL, 0, &feed->feed.ts,
-					    DMX_OK);
+				feed->cb.ts(buf, 188, NULL, 0, &feed->feed.ts);
 		}
 		if (feed->ts_type & TS_DECODER)
 			if (feed->demux->write_to_decoder)
@@ -469,7 +468,7 @@ static void dvb_dmx_swfilter_packet(struct dvb_demux *demux, const u8 *buf)
 		if (feed->pid == pid)
 			dvb_dmx_swfilter_packet_type(feed, buf);
 		else if (feed->pid == 0x2000)
-			feed->cb.ts(buf, 188, NULL, 0, &feed->feed.ts, DMX_OK);
+			feed->cb.ts(buf, 188, NULL, 0, &feed->feed.ts);
 	}
 }
 
@@ -588,7 +587,7 @@ void dvb_dmx_swfilter_raw(struct dvb_demux *demux, const u8 *buf, size_t count)
 
 	spin_lock_irqsave(&demux->lock, flags);
 
-	demux->feed->cb.ts(buf, count, NULL, 0, &demux->feed->feed.ts, DMX_OK);
+	demux->feed->cb.ts(buf, count, NULL, 0, &demux->feed->feed.ts);
 
 	spin_unlock_irqrestore(&demux->lock, flags);
 }
diff --git a/drivers/media/dvb-core/dvb_net.c b/drivers/media/dvb-core/dvb_net.c
index b81e026edab3..ce4332e80a91 100644
--- a/drivers/media/dvb-core/dvb_net.c
+++ b/drivers/media/dvb-core/dvb_net.c
@@ -761,7 +761,7 @@ static void dvb_net_ule( struct net_device *dev, const u8 *buf, size_t buf_len )
 
 static int dvb_net_ts_callback(const u8 *buffer1, size_t buffer1_len,
 			       const u8 *buffer2, size_t buffer2_len,
-			       struct dmx_ts_feed *feed, enum dmx_success success)
+			       struct dmx_ts_feed *feed)
 {
 	struct net_device *dev = feed->priv;
 
@@ -870,8 +870,7 @@ static void dvb_net_sec(struct net_device *dev,
 
 static int dvb_net_sec_callback(const u8 *buffer1, size_t buffer1_len,
 		 const u8 *buffer2, size_t buffer2_len,
-		 struct dmx_section_filter *filter,
-		 enum dmx_success success)
+		 struct dmx_section_filter *filter)
 {
 	struct net_device *dev = filter->priv;
 
diff --git a/drivers/media/pci/ttpci/av7110.c b/drivers/media/pci/ttpci/av7110.c
index 3f24fce74fc1..f89364951ebd 100644
--- a/drivers/media/pci/ttpci/av7110.c
+++ b/drivers/media/pci/ttpci/av7110.c
@@ -303,7 +303,6 @@ static int arm_thread(void *data)
 static int DvbDmxFilterCallback(u8 *buffer1, size_t buffer1_len,
 				u8 *buffer2, size_t buffer2_len,
 				struct dvb_demux_filter *dvbdmxfilter,
-				enum dmx_success success,
 				struct av7110 *av7110)
 {
 	if (!dvbdmxfilter->feed->demux->dmx.frontend)
@@ -329,16 +328,14 @@ static int DvbDmxFilterCallback(u8 *buffer1, size_t buffer1_len,
 		}
 		return dvbdmxfilter->feed->cb.sec(buffer1, buffer1_len,
 						  buffer2, buffer2_len,
-						  &dvbdmxfilter->filter,
-						  DMX_OK);
+						  &dvbdmxfilter->filter);
 	case DMX_TYPE_TS:
 		if (!(dvbdmxfilter->feed->ts_type & TS_PACKET))
 			return 0;
 		if (dvbdmxfilter->feed->ts_type & TS_PAYLOAD_ONLY)
 			return dvbdmxfilter->feed->cb.ts(buffer1, buffer1_len,
 							 buffer2, buffer2_len,
-							 &dvbdmxfilter->feed->feed.ts,
-							 DMX_OK);
+							 &dvbdmxfilter->feed->feed.ts);
 		else
 			av7110_p2t_write(buffer1, buffer1_len,
 					 dvbdmxfilter->feed->pid,
@@ -422,7 +419,7 @@ static void debiirq(unsigned long cookie)
 			DvbDmxFilterCallback((u8 *)av7110->debi_virt,
 					     av7110->debilen, NULL, 0,
 					     av7110->handle2filter[handle],
-					     DMX_OK, av7110);
+					     av7110);
 		xfer = RX_BUFF;
 		break;
 
diff --git a/drivers/media/pci/ttpci/av7110_av.c b/drivers/media/pci/ttpci/av7110_av.c
index 9544cfc06601..9ed1ec7d3551 100644
--- a/drivers/media/pci/ttpci/av7110_av.c
+++ b/drivers/media/pci/ttpci/av7110_av.c
@@ -102,7 +102,7 @@ int av7110_record_cb(struct dvb_filter_pes2ts *p2t, u8 *buf, size_t len)
 		buf[4] = buf[5] = 0;
 	if (dvbdmxfeed->ts_type & TS_PAYLOAD_ONLY)
 		return dvbdmxfeed->cb.ts(buf, len, NULL, 0,
-					 &dvbdmxfeed->feed.ts, DMX_OK);
+					 &dvbdmxfeed->feed.ts);
 	else
 		return dvb_filter_pes2ts(p2t, buf, len, 1);
 }
@@ -112,7 +112,7 @@ static int dvb_filter_pes2ts_cb(void *priv, unsigned char *data)
 	struct dvb_demux_feed *dvbdmxfeed = (struct dvb_demux_feed *) priv;
 
 	dvbdmxfeed->cb.ts(data, 188, NULL, 0,
-			  &dvbdmxfeed->feed.ts, DMX_OK);
+			  &dvbdmxfeed->feed.ts);
 	return 0;
 }
 
@@ -815,7 +815,7 @@ static void p_to_t(u8 const *buf, long int length, u16 pid, u8 *counter,
 			memcpy(obuf + l, buf + c, TS_SIZE - l);
 			c = length;
 		}
-		feed->cb.ts(obuf, 188, NULL, 0, &feed->feed.ts, DMX_OK);
+		feed->cb.ts(obuf, 188, NULL, 0, &feed->feed.ts);
 		pes_start = 0;
 	}
 }
diff --git a/drivers/media/usb/ttusb-dec/ttusb_dec.c b/drivers/media/usb/ttusb-dec/ttusb_dec.c
index 7c3a7c55d969..a5de46f04247 100644
--- a/drivers/media/usb/ttusb-dec/ttusb_dec.c
+++ b/drivers/media/usb/ttusb-dec/ttusb_dec.c
@@ -375,8 +375,7 @@ static int ttusb_dec_audio_pes2ts_cb(void *priv, unsigned char *data)
 	struct ttusb_dec *dec = priv;
 
 	dec->audio_filter->feed->cb.ts(data, 188, NULL, 0,
-				       &dec->audio_filter->feed->feed.ts,
-				       DMX_OK);
+				       &dec->audio_filter->feed->feed.ts);
 
 	return 0;
 }
@@ -386,8 +385,7 @@ static int ttusb_dec_video_pes2ts_cb(void *priv, unsigned char *data)
 	struct ttusb_dec *dec = priv;
 
 	dec->video_filter->feed->cb.ts(data, 188, NULL, 0,
-				       &dec->video_filter->feed->feed.ts,
-				       DMX_OK);
+				       &dec->video_filter->feed->feed.ts);
 
 	return 0;
 }
@@ -439,7 +437,7 @@ static void ttusb_dec_process_pva(struct ttusb_dec *dec, u8 *pva, int length)
 
 		if (output_pva) {
 			dec->video_filter->feed->cb.ts(pva, length, NULL, 0,
-				&dec->video_filter->feed->feed.ts, DMX_OK);
+				&dec->video_filter->feed->feed.ts);
 			return;
 		}
 
@@ -500,7 +498,7 @@ static void ttusb_dec_process_pva(struct ttusb_dec *dec, u8 *pva, int length)
 	case 0x02:		/* MainAudioStream */
 		if (output_pva) {
 			dec->audio_filter->feed->cb.ts(pva, length, NULL, 0,
-				&dec->audio_filter->feed->feed.ts, DMX_OK);
+				&dec->audio_filter->feed->feed.ts);
 			return;
 		}
 
@@ -538,7 +536,7 @@ static void ttusb_dec_process_filter(struct ttusb_dec *dec, u8 *packet,
 
 	if (filter)
 		filter->feed->cb.sec(&packet[2], length - 2, NULL, 0,
-				     &filter->filter, DMX_OK);
+				     &filter->filter);
 }
 
 static void ttusb_dec_process_packet(struct ttusb_dec *dec)
-- 
2.4.3

[PATCH 16/26] [media] dvb: Remove unused frontend sources at demux.h and sync doc

[Mauro Carvalho Chehab]

The DVB core has a provision for other frontend sources, but no
drivers use it. The kdapi.xml contains provision for some other
frontend source types, but it is not in sync with the code.

So, remove the unused types and sync both files.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml
index 1acae6730151..ff133a326d50 100644
--- a/Documentation/DocBook/media/dvb/kdapi.xml
+++ b/Documentation/DocBook/media/dvb/kdapi.xml
@@ -148,14 +148,9 @@ should be kept identical) to the types in the demux device.
  /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
 
  typedef enum {
-	 DMX_OTHER_FE = 0,
-	 DMX_SATELLITE_FE,
-	 DMX_CABLE_FE,
-	 DMX_TERRESTRIAL_FE,
-	 DMX_LVDS_FE,
-	 DMX_ASI_FE, /&#x22C6; DVB-ASI interface &#x22C6;/
-	 DMX_MEMORY_FE
- } dmx_frontend_source_t;
+	 DMX_MEMORY_FE,
+	 DMX_FRONTEND_0,
+ } dmx_frontend_source;
 
  typedef struct {
 	 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
@@ -166,7 +161,7 @@ should be kept identical) to the types in the demux device.
 						be connected to a particular
 						demux &#x22C6;/
 	 void&#x22C6; priv;     /&#x22C6; Pointer to private data of the API client &#x22C6;/
-	 dmx_frontend_source_t source;
+	 dmx_frontend_source source;
  } dmx_frontend_t;
 
  /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 2d036b36f551..15b79bdee465 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -141,13 +141,6 @@ typedef int (*dmx_section_cb) (	const u8 * buffer1,
 enum dmx_frontend_source {
 	DMX_MEMORY_FE,
 	DMX_FRONTEND_0,
-	DMX_FRONTEND_1,
-	DMX_FRONTEND_2,
-	DMX_FRONTEND_3,
-	DMX_STREAM_0,    /* external stream input, e.g. LVDS */
-	DMX_STREAM_1,
-	DMX_STREAM_2,
-	DMX_STREAM_3
 };
 
 struct dmx_frontend {
-- 
2.4.3

[PATCH 17/26] [media] DocBook: document the other structs/enums of demux.h

[Mauro Carvalho Chehab]

Document the following data types:
	struct dmx_ts_feed
	struct dmx_section_filter
	struct dmx_section_feed
	enum dmx_frontend_source
	struct dmx_frontend

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 15b79bdee465..b344cad096cd 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -68,10 +68,24 @@
 #define TS_DEMUX        8   /* in case TS_PACKET is set, send the TS to
 			       the demux device, not to the dvr device */
 
+/**
+ * struct dmx_ts_feed - Structure that contains a TS feed filter
+ *
+ * @is_filtering:	Set to non-zero when filtering in progress
+ * @parent:		pointer to struct dmx_demux
+ * @priv:		pointer to private data of the API client
+ * @set:		sets the TS filter
+ * @start_filtering:	starts TS filtering
+ * @stop_filtering:	stops TS filtering
+ *
+ * A TS feed is typically mapped to a hardware PID filter on the demux chip.
+ * Using this API, the client can set the filtering properties to start/stop
+ * filtering TS packets on a particular TS feed.
+ */
 struct dmx_ts_feed {
-	int is_filtering; /* Set to non-zero when filtering in progress */
-	struct dmx_demux *parent; /* Back-pointer */
-	void *priv; /* Pointer to private data of the API client */
+	int is_filtering;
+	struct dmx_demux *parent;
+	void *priv;
 	int (*set) (struct dmx_ts_feed *feed,
 		    u16 pid,
 		    int type,
@@ -86,6 +100,24 @@ struct dmx_ts_feed {
 /* Section reception */
 /*--------------------------------------------------------------------------*/
 
+/**
+ * struct dmx_section_filter - Structure that describes a section filter
+ *
+ * @filter_value: Contains up to 16 bytes (128 bits) of the TS section header
+ *		  that will be matched by the section filter
+ * @filter_mask:  Contains a 16 bytes (128 bits) filter mask with the bits
+ *		  specified by @filter_value that will be used on the filter
+ *		  match logic.
+ * @filter_mode:  Contains a 16 bytes (128 bits) filter mode.
+ * @parent:	  Pointer to struct dmx_section_feed.
+ * @priv:	  Pointer to private data of the API client.
+ *
+ *
+ * The @filter_mask controls which bits of @filter_value are compared with
+ * the section headers/payload. On a binary value of 1 in filter_mask, the
+ * corresponding bits are compared. The filter only accepts sections that are
+ * equal to filter_value in all the tested bit positions.
+ */
 struct dmx_section_filter {
 	u8 filter_value [DMX_MAX_FILTER_SIZE];
 	u8 filter_mask [DMX_MAX_FILTER_SIZE];
@@ -94,18 +126,46 @@ struct dmx_section_filter {
 	void* priv; /* Pointer to private data of the API client */
 };
 
+/**
+ * struct dmx_section_feed - Structure that contains a section feed filter
+ *
+ * @is_filtering:	Set to non-zero when filtering in progress
+ * @parent:		pointer to struct dmx_demux
+ * @priv:		pointer to private data of the API client
+ * @check_crc:		If non-zero, check the CRC values of filtered sections.
+ * @set:		sets the section filter
+ * @allocate_filter:	This function is used to allocate a section filter on
+ *			the demux. It should only be called when no filtering
+ *			is in progress on this section feed. If a filter cannot
+ *			be allocated, the function fails with -ENOSPC.
+ * @release_filter:	This function releases all the resources of a
+ * 			previously allocated section filter. The function
+ *			should not be called while filtering is in progress
+ *			on this section feed. After calling this function,
+ *			the caller should not try to dereference the filter
+ *			pointer.
+ * @start_filtering:	starts section filtering
+ * @stop_filtering:	stops section filtering
+ *
+ * A TS feed is typically mapped to a hardware PID filter on the demux chip.
+ * Using this API, the client can set the filtering properties to start/stop
+ * filtering TS packets on a particular TS feed.
+ */
 struct dmx_section_feed {
-	int is_filtering; /* Set to non-zero when filtering in progress */
-	struct dmx_demux* parent; /* Back-pointer */
-	void* priv; /* Pointer to private data of the API client */
+	int is_filtering;
+	struct dmx_demux* parent;
+	void* priv;
 
 	int check_crc;
+
+	/* private: Used internally at dvb_demux.c */
 	u32 crc_val;
 
 	u8 *secbuf;
 	u8 secbuf_base[DMX_MAX_SECFEED_SIZE];
 	u16 secbufp, seclen, tsfeedp;
 
+	/* public: */
 	int (*set) (struct dmx_section_feed* feed,
 		    u16 pid,
 		    size_t circular_buffer_size,
@@ -138,15 +198,34 @@ typedef int (*dmx_section_cb) (	const u8 * buffer1,
 /* DVB Front-End */
 /*--------------------------------------------------------------------------*/
 
+/**
+ * enum dmx_frontend_source - Used to identify the type of frontend
+ *
+ * @DMX_MEMORY_FE:	The source of the demux is memory. It means that
+ *			the MPEG-TS to be filtered comes from userspace,
+ *			via write() syscall.
+ *
+ * @DMX_FRONTEND_0:	The source of the demux is a frontend connected
+ *			to the demux.
+ */
 enum dmx_frontend_source {
 	DMX_MEMORY_FE,
 	DMX_FRONTEND_0,
 };
 
+/**
+ * struct dmx_frontend - Structure that lists the frontends associated with
+ *			 a demux
+ *
+ * @connectivity_list:	List of front-ends that can be connected to a
+ *			particular demux;
+ * @source:		Type of the frontend.
+ *
+ * FIXME: this structure should likely be replaced soon by some
+ *	media-controller based logic.
+ */
 struct dmx_frontend {
-	struct list_head connectivity_list; /* List of front-ends that can
-					       be connected to a particular
-					       demux */
+	struct list_head connectivity_list;
 	enum dmx_frontend_source source;
 };
 
-- 
2.4.3

[PATCH 18/26] [media] demux.h: make checkpatch.ph happy

[Mauro Carvalho Chehab]

There are lots of CodingStyle violations here. Now that we're
touching a log on this header files, adding the documentation
here, make sure that this will follow the Kernel CodingStyle.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index b344cad096cd..7405d6e2297d 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -32,9 +32,9 @@
 #include <linux/time.h>
 #include <linux/dvb/dmx.h>
 
-/*--------------------------------------------------------------------------*/
-/* Common definitions */
-/*--------------------------------------------------------------------------*/
+/*
+ * Common definitions
+ */
 
 /*
  * DMX_MAX_FILTER_SIZE: Maximum length (in bytes) of a section/PES filter.
@@ -45,7 +45,8 @@
 #endif
 
 /*
- * DMX_MAX_SECFEED_SIZE: Maximum length (in bytes) of a private section feed filter.
+ * DMX_MAX_SECFEED_SIZE: Maximum length (in bytes) of a private section feed
+ * filter.
  */
 
 #ifndef DMX_MAX_SECTION_SIZE
@@ -55,18 +56,30 @@
 #define DMX_MAX_SECFEED_SIZE (DMX_MAX_SECTION_SIZE + 188)
 #endif
 
-/*--------------------------------------------------------------------------*/
-/* TS packet reception */
-/*--------------------------------------------------------------------------*/
+/*
+ * TS packet reception
+ */
 
 /* TS filter type for set() */
 
-#define TS_PACKET       1   /* send TS packets (188 bytes) to callback (default) */
-#define	TS_PAYLOAD_ONLY 2   /* in case TS_PACKET is set, only send the TS
-			       payload (<=184 bytes per packet) to callback */
-#define TS_DECODER      4   /* send stream to built-in decoder (if present) */
-#define TS_DEMUX        8   /* in case TS_PACKET is set, send the TS to
-			       the demux device, not to the dvr device */
+#define TS_PACKET       1   /*
+			     * send TS packets (188 bytes) to callback
+			     * (default)
+			     */
+
+#define	TS_PAYLOAD_ONLY 2   /*
+			     * in case TS_PACKET is set, only send the TS
+			     * payload (<=184 bytes per packet) to callback
+			     */
+
+#define TS_DECODER      4   /*
+			     * send stream to built-in decoder (if present)
+			     */
+
+#define TS_DEMUX        8   /*
+			     * in case TS_PACKET is set, send the TS to
+			     * the demux device, not to the dvr device
+			     */
 
 /**
  * struct dmx_ts_feed - Structure that contains a TS feed filter
@@ -86,19 +99,19 @@ struct dmx_ts_feed {
 	int is_filtering;
 	struct dmx_demux *parent;
 	void *priv;
-	int (*set) (struct dmx_ts_feed *feed,
-		    u16 pid,
-		    int type,
-		    enum dmx_ts_pes pes_type,
-		    size_t circular_buffer_size,
-		    struct timespec timeout);
-	int (*start_filtering) (struct dmx_ts_feed* feed);
-	int (*stop_filtering) (struct dmx_ts_feed* feed);
+	int (*set)(struct dmx_ts_feed *feed,
+		   u16 pid,
+		   int type,
+		   enum dmx_ts_pes pes_type,
+		   size_t circular_buffer_size,
+		   struct timespec timeout);
+	int (*start_filtering)(struct dmx_ts_feed *feed);
+	int (*stop_filtering)(struct dmx_ts_feed *feed);
 };
 
-/*--------------------------------------------------------------------------*/
-/* Section reception */
-/*--------------------------------------------------------------------------*/
+/*
+ * Section reception
+ */
 
 /**
  * struct dmx_section_filter - Structure that describes a section filter
@@ -119,11 +132,11 @@ struct dmx_ts_feed {
  * equal to filter_value in all the tested bit positions.
  */
 struct dmx_section_filter {
-	u8 filter_value [DMX_MAX_FILTER_SIZE];
-	u8 filter_mask [DMX_MAX_FILTER_SIZE];
-	u8 filter_mode [DMX_MAX_FILTER_SIZE];
-	struct dmx_section_feed* parent; /* Back-pointer */
-	void* priv; /* Pointer to private data of the API client */
+	u8 filter_value[DMX_MAX_FILTER_SIZE];
+	u8 filter_mask[DMX_MAX_FILTER_SIZE];
+	u8 filter_mode[DMX_MAX_FILTER_SIZE];
+	struct dmx_section_feed *parent; /* Back-pointer */
+	void *priv; /* Pointer to private data of the API client */
 };
 
 /**
@@ -139,7 +152,7 @@ struct dmx_section_filter {
  *			is in progress on this section feed. If a filter cannot
  *			be allocated, the function fails with -ENOSPC.
  * @release_filter:	This function releases all the resources of a
- * 			previously allocated section filter. The function
+ *			previously allocated section filter. The function
  *			should not be called while filtering is in progress
  *			on this section feed. After calling this function,
  *			the caller should not try to dereference the filter
@@ -153,8 +166,8 @@ struct dmx_section_filter {
  */
 struct dmx_section_feed {
 	int is_filtering;
-	struct dmx_demux* parent;
-	void* priv;
+	struct dmx_demux *parent;
+	void *priv;
 
 	int check_crc;
 
@@ -166,33 +179,33 @@ struct dmx_section_feed {
 	u16 secbufp, seclen, tsfeedp;
 
 	/* public: */
-	int (*set) (struct dmx_section_feed* feed,
-		    u16 pid,
-		    size_t circular_buffer_size,
-		    int check_crc);
-	int (*allocate_filter) (struct dmx_section_feed* feed,
-				struct dmx_section_filter** filter);
-	int (*release_filter) (struct dmx_section_feed* feed,
-			       struct dmx_section_filter* filter);
-	int (*start_filtering) (struct dmx_section_feed* feed);
-	int (*stop_filtering) (struct dmx_section_feed* feed);
+	int (*set)(struct dmx_section_feed *feed,
+		   u16 pid,
+		   size_t circular_buffer_size,
+		   int check_crc);
+	int (*allocate_filter)(struct dmx_section_feed *feed,
+			       struct dmx_section_filter **filter);
+	int (*release_filter)(struct dmx_section_feed *feed,
+			      struct dmx_section_filter *filter);
+	int (*start_filtering)(struct dmx_section_feed *feed);
+	int (*stop_filtering)(struct dmx_section_feed *feed);
 };
 
-/*--------------------------------------------------------------------------*/
-/* Callback functions */
-/*--------------------------------------------------------------------------*/
+/*
+ * Callback functions
+ */
 
-typedef int (*dmx_ts_cb) ( const u8 * buffer1,
-			   size_t buffer1_length,
-			   const u8 * buffer2,
-			   size_t buffer2_length,
-			   struct dmx_ts_feed* source);
+typedef int (*dmx_ts_cb)(const u8 *buffer1,
+			 size_t buffer1_length,
+			 const u8 *buffer2,
+			 size_t buffer2_length,
+			 struct dmx_ts_feed *source);
 
-typedef int (*dmx_section_cb) (	const u8 * buffer1,
-				size_t buffer1_len,
-				const u8 * buffer2,
-				size_t buffer2_len,
-				struct dmx_section_filter * source);
+typedef int (*dmx_section_cb)(const u8 *buffer1,
+			      size_t buffer1_len,
+			      const u8 *buffer2,
+			      size_t buffer2_len,
+			     struct dmx_section_filter *source);
 
 /*--------------------------------------------------------------------------*/
 /* DVB Front-End */
@@ -229,9 +242,9 @@ struct dmx_frontend {
 	enum dmx_frontend_source source;
 };
 
-/*--------------------------------------------------------------------------*/
-/* MPEG-2 TS Demux */
-/*--------------------------------------------------------------------------*/
+/*
+ * MPEG-2 TS Demux
+ */
 
 /*
  * Flags OR'ed in the capabilities field of struct dmx_demux.
@@ -255,7 +268,8 @@ struct dmx_frontend {
  *.
 */
 
-#define DMX_FE_ENTRY(list) list_entry(list, struct dmx_frontend, connectivity_list)
+#define DMX_FE_ENTRY(list) \
+	list_entry(list, struct dmx_frontend, connectivity_list)
 
 /**
  * struct dmx_demux - Structure that contains the demux capabilities and
@@ -269,7 +283,7 @@ struct dmx_frontend {
  *
  * @open: This function reserves the demux for use by the caller and, if
  *	necessary, initializes the demux. When the demux is no longer needed,
- * 	the function @close should be called. It should be possible for
+ *	the function @close should be called. It should be possible for
  *	multiple clients to access the demux at the same time. Thus, the
  *	function implementation should increment the demux usage count when
  *	@open is called and decrement it when @close is called.
@@ -277,7 +291,7 @@ struct dmx_frontend {
  *	instance data.
  *	It returns
  *		0 on success;
- * 		-EUSERS, if maximum usage count was reached;
+ *		-EUSERS, if maximum usage count was reached;
  *		-EINVAL, on bad parameter.
  *
  * @close: This function reserves the demux for use by the caller and, if
@@ -408,7 +422,7 @@ struct dmx_frontend {
  *	call can be used as a parameter for @connect_frontend. The include
  *	file demux.h contains the macro DMX_FE_ENTRY() for converting an
  *	element of the generic type struct &list_head * to the type
- * 	struct &dmx_frontend *. The caller must not free the memory of any of
+ *	struct &dmx_frontend *. The caller must not free the memory of any of
  *	the elements obtained via this function call.
  *	The @demux function parameter contains a pointer to the demux API and
  *	instance data.
@@ -450,44 +464,45 @@ struct dmx_frontend {
 
 struct dmx_demux {
 	u32 capabilities;
-	struct dmx_frontend* frontend;
-	void* priv;
-	int (*open) (struct dmx_demux* demux);
-	int (*close) (struct dmx_demux* demux);
-	int (*write) (struct dmx_demux* demux, const char __user *buf, size_t count);
-	int (*allocate_ts_feed) (struct dmx_demux* demux,
-				 struct dmx_ts_feed** feed,
-				 dmx_ts_cb callback);
-	int (*release_ts_feed) (struct dmx_demux* demux,
-				struct dmx_ts_feed* feed);
-	int (*allocate_section_feed) (struct dmx_demux* demux,
-				      struct dmx_section_feed** feed,
-				      dmx_section_cb callback);
-	int (*release_section_feed) (struct dmx_demux* demux,
-				     struct dmx_section_feed* feed);
-	int (*add_frontend) (struct dmx_demux* demux,
-			     struct dmx_frontend* frontend);
-	int (*remove_frontend) (struct dmx_demux* demux,
-				struct dmx_frontend* frontend);
-	struct list_head* (*get_frontends) (struct dmx_demux* demux);
-	int (*connect_frontend) (struct dmx_demux* demux,
-				 struct dmx_frontend* frontend);
-	int (*disconnect_frontend) (struct dmx_demux* demux);
+	struct dmx_frontend *frontend;
+	void *priv;
+	int (*open)(struct dmx_demux *demux);
+	int (*close)(struct dmx_demux *demux);
+	int (*write)(struct dmx_demux *demux, const char __user *buf,
+		     size_t count);
+	int (*allocate_ts_feed)(struct dmx_demux *demux,
+				struct dmx_ts_feed **feed,
+				dmx_ts_cb callback);
+	int (*release_ts_feed)(struct dmx_demux *demux,
+			       struct dmx_ts_feed *feed);
+	int (*allocate_section_feed)(struct dmx_demux *demux,
+				     struct dmx_section_feed **feed,
+				     dmx_section_cb callback);
+	int (*release_section_feed)(struct dmx_demux *demux,
+				    struct dmx_section_feed *feed);
+	int (*add_frontend)(struct dmx_demux *demux,
+			    struct dmx_frontend *frontend);
+	int (*remove_frontend)(struct dmx_demux *demux,
+			       struct dmx_frontend *frontend);
+	struct list_head *(*get_frontends)(struct dmx_demux *demux);
+	int (*connect_frontend)(struct dmx_demux *demux,
+				struct dmx_frontend *frontend);
+	int (*disconnect_frontend)(struct dmx_demux *demux);
 
-	int (*get_pes_pids) (struct dmx_demux* demux, u16 *pids);
+	int (*get_pes_pids)(struct dmx_demux *demux, u16 *pids);
 
 	/* private: Not used upstream and never documented */
 #if 0
-	int (*get_caps) (struct dmx_demux* demux, struct dmx_caps *caps);
-	int (*set_source) (struct dmx_demux* demux, const dmx_source_t *src);
+	int (*get_caps)(struct dmx_demux *demux, struct dmx_caps *caps);
+	int (*set_source)(struct dmx_demux *demux, const dmx_source_t *src);
 #endif
 	/*
 	 * private: Only used at av7110, to read some data from firmware.
 	 *	As this was never documented, we have no clue about what's
-	 * 	there, and its usage on other drivers aren't encouraged.
+	 *	there, and its usage on other drivers aren't encouraged.
 	 */
-	int (*get_stc) (struct dmx_demux* demux, unsigned int num,
-			u64 *stc, unsigned int *base);
+	int (*get_stc)(struct dmx_demux *demux, unsigned int num,
+		       u64 *stc, unsigned int *base);
 };
 
 #endif /* #ifndef __DEMUX_H */
-- 
2.4.3

[PATCH 19/26] kernel-doc: Add a parser for function typedefs

[Mauro Carvalho Chehab]

The current typedef parser only works for non-function typedefs.

As we need to also document some function typedefs, add a
parser for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9a08fb5c1af6..55ce47ffa02d 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1886,6 +1886,18 @@ sub dump_typedef($$) {
 			    'purpose' => $declaration_purpose
 			   });
     }
+    elsif ($x =~ /typedef\s+\w+\s*\(\*\s*(\w\S+)\s*\)\s*\(/) { # functions
+	$declaration_name = $1;
+
+	output_declaration($declaration_name,
+			   'typedef',
+			   {'typedef' => $declaration_name,
+			    'module' => $modulename,
+			    'sectionlist' => \@sectionlist,
+			    'sections' => \%sections,
+			    'purpose' => $declaration_purpose
+			   });
+    }
     else {
 	print STDERR "${file}:$.: error: Cannot parse typedef!\n";
 	++$errors;
-- 
2.4.3

[PATCH 20/26] kernel-doc: better format typedef function output

[Mauro Carvalho Chehab]

A typedef function looks more likely a function and not a
normal typedef. Change the code to use the output_function_*,
in order to properly parse the function prototype parameters.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 55ce47ffa02d..0276d2b5eefe 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1869,6 +1869,31 @@ sub dump_typedef($$) {
     my $file = shift;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
+
+    # Parse function prototypes
+    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
+	# Function typedefs
+	$return_type = $1;
+	$declaration_name = $2;
+	my $args = $3;
+
+	create_parameterlist($args, ',', $file);
+
+	output_declaration($declaration_name,
+			   'function',
+			   {'function' => $declaration_name,
+			    'module' => $modulename,
+			    'functiontype' => $return_type,
+			    'parameterlist' => \@parameterlist,
+			    'parameterdescs' => \%parameterdescs,
+			    'parametertypes' => \%parametertypes,
+			    'sectionlist' => \@sectionlist,
+			    'sections' => \%sections,
+			    'purpose' => $declaration_purpose
+			   });
+	return;
+    }
+
     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
 	$x =~ s/\(*.\)\s*;$/;/;
 	$x =~ s/\[*.\]\s*;$/;/;
@@ -1886,18 +1911,6 @@ sub dump_typedef($$) {
 			    'purpose' => $declaration_purpose
 			   });
     }
-    elsif ($x =~ /typedef\s+\w+\s*\(\*\s*(\w\S+)\s*\)\s*\(/) { # functions
-	$declaration_name = $1;
-
-	output_declaration($declaration_name,
-			   'typedef',
-			   {'typedef' => $declaration_name,
-			    'module' => $modulename,
-			    'sectionlist' => \@sectionlist,
-			    'sections' => \%sections,
-			    'purpose' => $declaration_purpose
-			   });
-    }
     else {
 	print STDERR "${file}:$.: error: Cannot parse typedef!\n";
 	++$errors;
-- 
2.4.3

[PATCH 21/26] [media] DocBook: document typedef dmx_ts_cb at demux.h

[Mauro Carvalho Chehab]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=true, Size: 3876 bytes --]

The dvb/kdapi.tmpl has already an extensive documentation about
this callback. Now that we've added function typedefs at kernel-doc,
add such documentation at demux.h, for it to appear at device-drivers
DocBook.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 7405d6e2297d..39e644113350 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -195,6 +195,61 @@ struct dmx_section_feed {
  * Callback functions
  */
 
+/**
+ * typedef dmx_ts_cb - DVB demux TS filter callback function prototype
+ *
+ * @buffer1:		Pointer to the start of the filtered TS packets.
+ * @buffer1_length:	Length of the TS data in buffer1.
+ * @buffer2:		Pointer to the tail of the filtered TS packets, or NULL.
+ * @buffer2_length:	Length of the TS data in buffer2.
+ * @source:		Indicates which TS feed is the source of the callback.
+ *
+ * This function callback prototype, provided by the client of the demux API,
+ * is called from the demux code. The function is only called when filtering
+ * on ae TS feed has been enabled using the start_filtering() function at
+ * the &dmx_demux.
+ * Any TS packets that match the filter settings are copied to a circular
+ * buffer. The filtered TS packets are delivered to the client using this
+ * callback function. The size of the circular buffer is controlled by the
+ * circular_buffer_size parameter of the &dmx_ts_feed.@set function.
+ * It is expected that the @buffer1 and @buffer2 callback parameters point to
+ * addresses within the circular buffer, but other implementations are also
+ * possible. Note that the called party should not try to free the memory
+ * the @buffer1 and @buffer2 parameters point to.
+ *
+ * When this function is called, the @buffer1 parameter typically points to
+ * the start of the first undelivered TS packet within a circular buffer.
+ * The @buffer2 buffer parameter is normally NULL, except when the received
+ * TS packets have crossed the last address of the circular buffer and
+ * ”wrapped” to the beginning of the buffer. In the latter case the @buffer1
+ * parameter would contain an address within the circular buffer, while the
+ * @buffer2 parameter would contain the first address of the circular buffer.
+ * The number of bytes delivered with this function (i.e. @buffer1_length +
+ * @buffer2_length) is usually equal to the value of callback_length parameter
+ * given in the set() function, with one exception: if a timeout occurs before
+ * receiving callback_length bytes of TS data, any undelivered packets are
+ * immediately delivered to the client by calling this function. The timeout
+ * duration is controlled by the set() function in the TS Feed API.
+ *
+ * If a TS packet is received with errors that could not be fixed by the
+ * TS-level forward error correction (FEC), the Transport_error_indicator
+ * flag of the TS packet header should be set. The TS packet should not be
+ * discarded, as the error can possibly be corrected by a higher layer
+ * protocol. If the called party is slow in processing the callback, it
+ * is possible that the circular buffer eventually fills up. If this happens,
+ * the demux driver should discard any TS packets received while the buffer
+ * is full and return -EOVERFLOW.
+ *
+ * The type of data returned to the callback can be selected by the
+ * &dmx_ts_feed.@set function. The type parameter decides if the raw
+ * TS packet (TS_PACKET) or just the payload (TS_PACKET|TS_PAYLOAD_ONLY)
+ * should be returned. If additionally the TS_DECODER bit is set the stream
+ * will also be sent to the hardware MPEG decoder.
+ *
+ * Return:
+ * 	0, on success;
+ * 	-EOVERFLOW, on buffer overflow.
+ */
 typedef int (*dmx_ts_cb)(const u8 *buffer1,
 			 size_t buffer1_length,
 			 const u8 *buffer2,
-- 
2.4.3

[PATCH 22/26] [media] DocBook: document typedef dmx_section_cb at demux.h

[Mauro Carvalho Chehab]

The dvb/kdapi.tmpl has already an extensive documentation about
this callback. Now that we've added function typedefs at kernel-doc,
add such documentation at demux.h, for it to appear at device-drivers
DocBook.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 39e644113350..576e30fc5c18 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -256,11 +256,46 @@ typedef int (*dmx_ts_cb)(const u8 *buffer1,
 			 size_t buffer2_length,
 			 struct dmx_ts_feed *source);
 
+/**
+ * typedef dmx_section_cb - DVB demux TS filter callback function prototype
+ *
+ * @buffer1:		Pointer to the start of the filtered section, e.g.
+ *			within the circular buffer of the demux driver.
+ * @buffer1_len:	Length of the filtered section data in @buffer1,
+ *			including headers and CRC.
+ * @buffer2:		Pointer to the tail of the filtered section data,
+ *			or NULL. Useful to handle the wrapping of a
+ *			circular buffer.
+ * @buffer2_len:	Length of the filtered section data in @buffer2,
+ *			including headers and CRC.
+ * @source:		Indicates which section feed is the source of the
+ *			callback.
+ *
+ * This function callback prototype, provided by the client of the demux API,
+ * is called from the demux code. The function is only called when
+ * filtering of sections has been enabled using the function
+ * &dmx_ts_feed.@start_filtering. When the demux driver has received a
+ * complete section that matches at least one section filter, the client
+ * is notified via this callback function. Normally this function is called
+ * for each received section; however, it is also possible to deliver
+ * multiple sections with one callback, for example when the system load
+ * is high. If an error occurs while receiving a section, this
+ * function should be called with the corresponding error type set in the
+ * success field, whether or not there is data to deliver. The Section Feed
+ * implementation should maintain a circular buffer for received sections.
+ * However, this is not necessary if the Section Feed API is implemented as
+ * a client of the TS Feed API, because the TS Feed implementation then
+ * buffers the received data. The size of the circular buffer can be
+ * configured using the &dmx_ts_feed.@set function in the Section Feed API.
+ * If there is no room in the circular buffer when a new section is received,
+ * the section must be discarded. If this happens, the value of the success
+ * parameter should be DMX_OVERRUN_ERROR on the next callback.
+ */
 typedef int (*dmx_section_cb)(const u8 *buffer1,
 			      size_t buffer1_len,
 			      const u8 *buffer2,
 			      size_t buffer2_len,
-			     struct dmx_section_filter *source);
+			      struct dmx_section_filter *source);
 
 /*--------------------------------------------------------------------------*/
 /* DVB Front-End */
-- 
2.4.3

[PATCH 23/26] [media] demux.h: Convert TS filter type into enum

[Mauro Carvalho Chehab]

The usage of #define at the kABI is fine, but it doesn't
allow adding a proper description. As those defines deserve
a proper documentation, let's convert them into an enum and
document them at device-drivers DocBook.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 576e30fc5c18..98bff5cc4ff4 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -60,26 +60,22 @@
  * TS packet reception
  */
 
-/* TS filter type for set() */
-
-#define TS_PACKET       1   /*
-			     * send TS packets (188 bytes) to callback
-			     * (default)
-			     */
-
-#define	TS_PAYLOAD_ONLY 2   /*
-			     * in case TS_PACKET is set, only send the TS
-			     * payload (<=184 bytes per packet) to callback
-			     */
-
-#define TS_DECODER      4   /*
-			     * send stream to built-in decoder (if present)
-			     */
-
-#define TS_DEMUX        8   /*
-			     * in case TS_PACKET is set, send the TS to
-			     * the demux device, not to the dvr device
-			     */
+/**
+ * enum ts_filter_type - filter type bitmap for dmx_ts_feed.set()
+ *
+ * @TS_PACKET:		Send TS packets (188 bytes) to callback (default).
+ * @TS_PAYLOAD_ONLY:	In case TS_PACKET is set, only send the TS payload
+ *			(<=184 bytes per packet) to callback
+ * @TS_DECODER:		Send stream to built-in decoder (if present).
+ * @TS_DEMUX:		In case TS_PACKET is set, send the TS to the demux
+ *			device, not to the dvr device
+ */
+enum ts_filter_type {
+	TS_PACKET = 1,
+	TS_PAYLOAD_ONLY = 2,
+	TS_DECODER = 4,
+	TS_DEMUX = 8,
+};
 
 /**
  * struct dmx_ts_feed - Structure that contains a TS feed filter
-- 
2.4.3

[PATCH 24/26] [media] demux.h: Convert MPEG-TS demux caps to an enum

[Mauro Carvalho Chehab]

While we can't document #defines, documenting enums are
well supported by kernel-doc. So, convert the bitmap defines
into an enum.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 98bff5cc4ff4..ccc1f43cb9a9 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -332,16 +332,20 @@ struct dmx_frontend {
  * MPEG-2 TS Demux
  */
 
-/*
- * Flags OR'ed in the capabilities field of struct dmx_demux.
+/**
+ * enum dmx_demux_caps - MPEG-2 TS Demux capabilities bitmap
+ *
+ * @DMX_TS_FILTERING:		set if TS filtering is supported;
+ * @DMX_SECTION_FILTERING:	set if section filtering is supported;
+ * @DMX_MEMORY_BASED_FILTERING:	set if write() available.
+ *
+ * Those flags are OR'ed in the &dmx_demux.&capabilities field
  */
-
-#define DMX_TS_FILTERING                        1
-#define DMX_PES_FILTERING                       2
-#define DMX_SECTION_FILTERING                   4
-#define DMX_MEMORY_BASED_FILTERING              8    /* write() available */
-#define DMX_CRC_CHECKING                        16
-#define DMX_TS_DESCRAMBLING                     32
+enum dmx_demux_caps {
+	DMX_TS_FILTERING = 1,
+	DMX_SECTION_FILTERING = 4,
+	DMX_MEMORY_BASED_FILTERING = 8,
+};
 
 /*
  * Demux resource type identifier.
@@ -361,7 +365,7 @@ struct dmx_frontend {
  * struct dmx_demux - Structure that contains the demux capabilities and
  *		      callbacks.
  *
- * @capabilities: Bitfield of capability flags
+ * @capabilities: Bitfield of capability flags.
  *
  * @frontend: Front-end connected to the demux
  *
@@ -549,7 +553,7 @@ struct dmx_frontend {
  */
 
 struct dmx_demux {
-	u32 capabilities;
+	enum dmx_demux_caps capabilities;
 	struct dmx_frontend *frontend;
 	void *priv;
 	int (*open)(struct dmx_demux *demux);
-- 
2.4.3

[PATCH 25/26] [media] DocBook: Add documentation about the demux API

[Mauro Carvalho Chehab]

There are several stuff at media's kdapi.xml that don't
belong there, as it documents the Kernel internal ABI, and
not the userspace API.

Add the documentation here. The hole kdapi.xml will be
removed on a latter patch, after we finish documenting
what's there at the proper places.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index 8d5620aeaf36..42a2d8593e39 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -239,21 +239,86 @@ X!Isound/sound_firmware.c
      </sect1>
      <sect1><title>Digital TV (DVB) devices</title>
 !Idrivers/media/dvb-core/dvb_ca_en50221.h
-!Idrivers/media/dvb-core/demux.h
 !Idrivers/media/dvb-core/dvb_frontend.h
 !Idrivers/media/dvb-core/dvb_math.h
 !Idrivers/media/dvb-core/dvb_ringbuffer.h
 !Idrivers/media/dvb-core/dvbdev.h
-     </sect1>
-     <sect1><title>Remote Controller devices</title>
+	<sect1><title>Digital TV Demux API</title>
+	    <para>The kernel demux API defines a driver-internal interface for
+	    registering low-level, hardware specific driver to a hardware
+	    independent demux layer. It is only of interest for Digital TV
+	    device driver writers. The header file for this API is named
+	    <constant>demux.h</constant> and located in
+	    <constant>drivers/media/dvb-core</constant>.</para>
+
+	<para>The demux API should be implemented for each demux in the
+	system. It is used to select the TS source of a demux and to manage
+	the demux resources. When the demux client allocates a resource via
+	the demux API, it receives a pointer to the API of that
+	resource.</para>
+	<para>Each demux receives its TS input from a DVB front-end or from
+	memory, as set via this demux API. In a system with more than one
+	front-end, the API can be used to select one of the DVB front-ends
+	as a TS source for a demux, unless this is fixed in the HW platform.
+	The demux API only controls front-ends regarding to their connections
+	with demuxes; the APIs used to set the other front-end parameters,
+	such as tuning, are not defined in this document.</para>
+	<para>The functions that implement the abstract interface demux should
+	be defined static or module private and registered to the Demux
+	core for external access. It is not necessary to implement every
+	function in the struct <constant>dmx_demux</constant>. For example,
+	a demux interface might support Section filtering, but not PES
+	filtering. The API client is expected to check the value of any
+	function pointer before calling the function: the value of NULL means
+	that the &#8220;function is not available&#8221;.</para>
+	<para>Whenever the functions of the demux API modify shared data,
+	the possibilities of lost update and race condition problems should
+	be addressed, e.g. by protecting parts of code with mutexes.</para>
+	<para>Note that functions called from a bottom half context must not
+	sleep. Even a simple memory allocation without using GFP_ATOMIC can
+	result in a kernel thread being put to sleep if swapping is needed.
+	For example, the Linux kernel calls the functions of a network device
+	interface from a bottom half context. Thus, if a demux API function
+	is called from network device code, the function must not sleep.
+	</para>
+    </sect1>
+
+    <section id="demux_callback_api">
+	<title>Demux Callback API</title>
+	<para>This kernel-space API comprises the callback functions that
+	deliver filtered data to the demux client. Unlike the other DVB
+	kABIs, these functions are provided by the client and called from
+	the demux code.</para>
+	<para>The function pointers of this abstract interface are not
+	packed into a structure as in the other demux APIs, because the
+	callback functions are registered and used independent of each
+	other. As an example, it is possible for the API client to provide
+	several callback functions for receiving TS packets and no
+	callbacks for PES packets or sections.</para>
+	<para>The functions that implement the callback API need not be
+	re-entrant: when a demux driver calls one of these functions,
+	the driver is not allowed to call the function again before
+	the original call returns. If a callback is triggered by a
+	hardware interrupt, it is recommended to use the Linux
+	&#8220;bottom half&#8221; mechanism or start a tasklet instead of
+	making the callback function call directly from a hardware
+	interrupt.</para>
+	<para>This mechanism is implemented by
+	<link linkend='API-dmx-ts-cb'>dmx_ts_cb()</link> and
+	<link linkend='API-dmx-section-cb'>dmx_section_cb()</link>.</para>
+    </section>
+
+!Idrivers/media/dvb-core/demux.h
+    </sect1>
+    <sect1><title>Remote Controller devices</title>
 !Iinclude/media/rc-core.h
 !Iinclude/media/lirc_dev.h
-     </sect1>
-     <sect1><title>Media Controller devices</title>
+    </sect1>
+    <sect1><title>Media Controller devices</title>
 !Iinclude/media/media-device.h
 !Iinclude/media/media-devnode.h
 !Iinclude/media/media-entity.h
-     </sect1>
+    </sect1>
 
   </chapter>
 
-- 
2.4.3

[PATCH 26/26] [media] DocBook: Remove kdapi.xml

[Mauro Carvalho Chehab]

Now that the Demux kABI is documented at device-drivers.xml,
remove it from the API docbook.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>

 delete mode 100644 Documentation/DocBook/media/dvb/kdapi.xml

diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml
index 858fd7d17104..8576481e20ae 100644
--- a/Documentation/DocBook/media/dvb/dvbapi.xml
+++ b/Documentation/DocBook/media/dvb/dvbapi.xml
@@ -125,9 +125,6 @@ Added ISDB-T test originally written by Patrick Boettcher
 	&sub-audio;
     </section>
   </chapter>
-  <chapter id="dvb_kdapi">
-    &sub-kdapi;
-  </chapter>
   <chapter id="dvb_examples">
     &sub-examples;
   </chapter>
diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml
deleted file mode 100644
index ff133a326d50..000000000000
--- a/Documentation/DocBook/media/dvb/kdapi.xml
+++ /dev/null
@@ -1,1236 +0,0 @@
-<title>Kernel Demux API</title>
-<para>The kernel demux API defines a driver-internal interface for registering low-level,
-hardware specific driver to a hardware independent demux layer. It is only of interest for
-DVB device driver writers. The header file for this API is named <constant>demux.h</constant> and located in
-<constant>">drivers/media/dvb-core</constant>.
-</para>
-<para>Maintainer note: This section must be reviewed. It is probably out of date.
-</para>
-
-<section id="kernel_demux_data_types">
-<title>Kernel Demux Data Types</title>
-
-
-</section>
-<section id="ts_filter_types">
-<title>TS filter types</title>
- <programlisting>
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; TS packet reception &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- /&#x22C6; TS filter type for set_type() &#x22C6;/
-
- #define TS_PACKET       1   /&#x22C6; send TS packets (188 bytes) to callback (default) &#x22C6;/
- #define TS_PAYLOAD_ONLY 2   /&#x22C6; in case TS_PACKET is set, only send the TS
-				payload (&#x003C;=184 bytes per packet) to callback &#x22C6;/
- #define TS_DECODER      4   /&#x22C6; send stream to built-in decoder (if present) &#x22C6;/
-</programlisting>
-
-</section>
-<section id="dmx_ts_pes_t">
-<title>dmx_ts_pes_t</title>
-<para>The structure
-</para>
-<programlisting>
- typedef enum
- {
-	 DMX_TS_PES_AUDIO,   /&#x22C6; also send packets to audio decoder (if it exists) &#x22C6;/
-	 DMX_TS_PES_VIDEO,   /&#x22C6; ... &#x22C6;/
-	 DMX_TS_PES_TELETEXT,
-	 DMX_TS_PES_SUBTITLE,
-	 DMX_TS_PES_PCR,
-	 DMX_TS_PES_OTHER,
- } dmx_ts_pes_t;
-</programlisting>
-<para>describes the PES type for filters which write to a built-in decoder. The correspond (and
-should be kept identical) to the types in the demux device.
-</para>
-<programlisting>
- struct dmx_ts_feed_s {
-	 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
-	 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
-	 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
-	 int (&#x22C6;set) (struct dmx_ts_feed_s&#x22C6; feed,
-		     __u16 pid,
-		     size_t callback_length,
-		     size_t circular_buffer_size,
-		     int descramble,
-		     struct timespec timeout);
-	 int (&#x22C6;start_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
-	 int (&#x22C6;stop_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
-	 int (&#x22C6;set_type) (struct dmx_ts_feed_s&#x22C6; feed,
-			  int type,
-			  dmx_ts_pes_t pes_type);
- };
-
- typedef struct dmx_ts_feed_s dmx_ts_feed_t;
-</programlisting>
- <programlisting>
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; PES packet reception (not supported yet) &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- typedef struct dmx_pes_filter_s {
-	 struct dmx_pes_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
-	 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- } dmx_pes_filter_t;
-</programlisting>
- <programlisting>
- typedef struct dmx_pes_feed_s {
-	 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
-	 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
-	 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
-	 int (&#x22C6;set) (struct dmx_pes_feed_s&#x22C6; feed,
-		     __u16 pid,
-		     size_t circular_buffer_size,
-		     int descramble,
-		     struct timespec timeout);
-	 int (&#x22C6;start_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
-	 int (&#x22C6;stop_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
-	 int (&#x22C6;allocate_filter) (struct dmx_pes_feed_s&#x22C6; feed,
-				 dmx_pes_filter_t&#x22C6;&#x22C6; filter);
-	 int (&#x22C6;release_filter) (struct dmx_pes_feed_s&#x22C6; feed,
-				dmx_pes_filter_t&#x22C6; filter);
- } dmx_pes_feed_t;
-</programlisting>
- <programlisting>
- typedef struct {
-	 __u8 filter_value [DMX_MAX_FILTER_SIZE];
-	 __u8 filter_mask [DMX_MAX_FILTER_SIZE];
-	 struct dmx_section_feed_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
-	 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
- } dmx_section_filter_t;
-</programlisting>
- <programlisting>
- struct dmx_section_feed_s {
-	 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
-	 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
-	 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
-	 int (&#x22C6;set) (struct dmx_section_feed_s&#x22C6; feed,
-		     __u16 pid,
-		     size_t circular_buffer_size,
-		     int descramble,
-		     int check_crc);
-	 int (&#x22C6;allocate_filter) (struct dmx_section_feed_s&#x22C6; feed,
-				 dmx_section_filter_t&#x22C6;&#x22C6; filter);
-	 int (&#x22C6;release_filter) (struct dmx_section_feed_s&#x22C6; feed,
-				dmx_section_filter_t&#x22C6; filter);
-	 int (&#x22C6;start_filtering) (struct dmx_section_feed_s&#x22C6; feed);
-	 int (&#x22C6;stop_filtering) (struct dmx_section_feed_s&#x22C6; feed);
- };
- typedef struct dmx_section_feed_s dmx_section_feed_t;
-
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; Callback functions &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- typedef int (&#x22C6;dmx_ts_cb) ( __u8 &#x22C6; buffer1,
-			    size_t buffer1_length,
-			    __u8 &#x22C6; buffer2,
-			    size_t buffer2_length,
-			    dmx_ts_feed_t&#x22C6; source)
-
- typedef int (&#x22C6;dmx_section_cb) ( __u8 &#x22C6; buffer1,
-				 size_t buffer1_len,
-				 __u8 &#x22C6; buffer2,
-				 size_t buffer2_len,
-				 dmx_section_filter_t &#x22C6; source);
-
- typedef int (&#x22C6;dmx_pes_cb) ( __u8 &#x22C6; buffer1,
-			     size_t buffer1_len,
-			     __u8 &#x22C6; buffer2,
-			     size_t buffer2_len,
-			     dmx_pes_filter_t&#x22C6; source);
-
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; DVB Front-End &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- typedef enum {
-	 DMX_MEMORY_FE,
-	 DMX_FRONTEND_0,
- } dmx_frontend_source;
-
- typedef struct {
-	 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
-	 char&#x22C6; id;                    /&#x22C6; Unique front-end identifier &#x22C6;/
-	 char&#x22C6; vendor;                /&#x22C6; Name of the front-end vendor &#x22C6;/
-	 char&#x22C6; model;                 /&#x22C6; Name of the front-end model &#x22C6;/
-	 struct list_head connectivity_list; /&#x22C6; List of front-ends that can
-						be connected to a particular
-						demux &#x22C6;/
-	 void&#x22C6; priv;     /&#x22C6; Pointer to private data of the API client &#x22C6;/
-	 dmx_frontend_source source;
- } dmx_frontend_t;
-
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
- /&#x22C6; MPEG-2 TS Demux &#x22C6;/
- /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
-
- /&#x22C6;
-  &#x22C6; Flags OR'ed in the capabilites field of struct dmx_demux_s.
-  &#x22C6;/
-
- #define DMX_TS_FILTERING                        1
- #define DMX_PES_FILTERING                       2
- #define DMX_SECTION_FILTERING                   4
- #define DMX_MEMORY_BASED_FILTERING              8    /&#x22C6; write() available &#x22C6;/
- #define DMX_CRC_CHECKING                        16
- #define DMX_TS_DESCRAMBLING                     32
- #define DMX_SECTION_PAYLOAD_DESCRAMBLING        64
- #define DMX_MAC_ADDRESS_DESCRAMBLING            128
-</programlisting>
-
-</section>
-<section id="demux_demux_t">
-<title>demux_demux_t</title>
- <programlisting>
- /&#x22C6;
-  &#x22C6; DMX_FE_ENTRY(): Casts elements in the list of registered
-  &#x22C6; front-ends from the generic type struct list_head
-  &#x22C6; to the type &#x22C6; dmx_frontend_t
-  &#x22C6;.
- &#x22C6;/
-</programlisting>
-
-</section>
-<section id="demux_directory">
-<title>Demux directory</title>
- <programlisting>
- /&#x22C6;
-  &#x22C6; DMX_DIR_ENTRY(): Casts elements in the list of registered
-  &#x22C6; demuxes from the generic type struct list_head&#x22C6; to the type dmx_demux_t
-  &#x22C6;.
-  &#x22C6;/
-
- #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)
-
- int dmx_register_demux (dmx_demux_t&#x22C6; demux);
- int dmx_unregister_demux (dmx_demux_t&#x22C6; demux);
- struct list_head&#x22C6; dmx_get_demuxes (void);
-</programlisting>
- </section></section>
-<section id="demux_directory_api">
-<title>Demux Directory API</title>
-<para>The demux directory is a Linux kernel-wide facility for registering and accessing the
-MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
-is possible using this API.
-</para>
-<para>All demux drivers in the directory implement the abstract interface dmx_demux_t.
-</para>
-
-<section
-role="subsection"><title>dmx_register_demux()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function makes a demux driver interface available to the Linux kernel. It is
- usually called by the init_module() function of the kernel module that contains
- the demux driver. The caller of this function is responsible for allocating
- dynamic or static memory for the demux structure and for initializing its fields
- before calling this function. The memory allocated for the demux structure
- must not be freed before calling dmx_unregister_demux(),</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int dmx_register_demux ( dmx_demux_t &#x22C6;demux )</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux structure.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EEXIST</para>
-</entry><entry
- align="char">
-<para>A demux with the same value of the id field already stored
- in the directory.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSPC</para>
-</entry><entry
- align="char">
-<para>No space left in the directory.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>dmx_unregister_demux()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function is called to indicate that the given demux interface is no
- longer available. The caller of this function is responsible for freeing the
- memory of the demux structure, if it was dynamically allocated before calling
- dmx_register_demux(). The cleanup_module() function of the kernel module
- that contains the demux driver should call this function. Note that this function
- fails if the demux is currently in use, i.e., release_demux() has not been called
- for the interface.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int dmx_unregister_demux ( dmx_demux_t &#x22C6;demux )</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_demux_t*
- demux</para>
-</entry><entry
- align="char">
-<para>Pointer to the demux structure which is to be
- unregistered.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>ENODEV</para>
-</entry><entry
- align="char">
-<para>The specified demux is not registered in the demux
- directory.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>EBUSY</para>
-</entry><entry
- align="char">
-<para>The specified demux is currently in use.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>dmx_get_demuxes()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Provides the caller with the list of registered demux interfaces, using the
- standard list structure defined in the include file linux/list.h. The include file
- demux.h defines the macro DMX_DIR_ENTRY() for converting an element of
- the generic type struct list_head* to the type dmx_demux_t*. The caller must
- not free the memory of any of the elements obtained via this function call.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>struct list_head &#x22C6;dmx_get_demuxes ()</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>none</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>struct list_head *</para>
-</entry><entry
- align="char">
-<para>A list of demux interfaces, or NULL in the case of an
- empty list.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
-<section id="demux_api">
-<title>Demux API</title>
-<para>The demux API should be implemented for each demux in the system. It is used to select
-the TS source of a demux and to manage the demux resources. When the demux
-client allocates a resource via the demux API, it receives a pointer to the API of that
-resource.
-</para>
-<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
-demux API. In a system with more than one front-end, the API can be used to select one of
-the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
-demux API only controls front-ends regarding their connections with demuxes; the APIs
-used to set the other front-end parameters, such as tuning, are not defined in this
-document.
-</para>
-<para>The functions that implement the abstract interface demux should be defined static or
-module private and registered to the Demux Directory for external access. It is not necessary
-to implement every function in the demux_t struct, however (for example, a demux interface
-might support Section filtering, but not TS or PES filtering). The API client is expected to
-check the value of any function pointer before calling the function: the value of NULL means
-&#8220;function not available&#8221;.
-</para>
-<para>Whenever the functions of the demux API modify shared data, the possibilities of lost
-update and race condition problems should be addressed, e.g. by protecting parts of code with
-mutexes. This is especially important on multi-processor hosts.
-</para>
-<para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x
-kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
-swapping is needed. For example, the Linux kernel calls the functions of a network device
-interface from a bottom half context. Thus, if a demux API function is called from network
-device code, the function must not sleep.
-</para>
-
-</section>
-<section id="demux_callback_api">
-<title>Demux Callback API</title>
-<para>This kernel-space API comprises the callback functions that deliver filtered data to the
-demux client. Unlike the other APIs, these API functions are provided by the client and called
-from the demux code.
-</para>
-<para>The function pointers of this abstract interface are not packed into a structure as in the
-other demux APIs, because the callback functions are registered and used independent
-of each other. As an example, it is possible for the API client to provide several
-callback functions for receiving TS packets and no callbacks for PES packets or
-sections.
-</para>
-<para>The functions that implement the callback API need not be re-entrant: when a demux
-driver calls one of these functions, the driver is not allowed to call the function again before
-the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
-to use the Linux &#8220;bottom half&#8221; mechanism or start a tasklet instead of making the callback
-function call directly from a hardware interrupt.
-</para>
-
-<section
-role="subsection"><title>dmx_ts_cb()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function, provided by the client of the demux API, is called from the
- demux code. The function is only called when filtering on this TS feed has
- been enabled using the start_filtering() function.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>Any TS packets that match the filter settings are copied to a circular buffer. The
- filtered TS packets are delivered to the client using this callback function. The
- size of the circular buffer is controlled by the circular_buffer_size parameter
- of the set() function in the TS Feed API. It is expected that the buffer1 and
- buffer2 callback parameters point to addresses within the circular buffer, but
- other implementations are also possible. Note that the called party should not
- try to free the memory the buffer1 and buffer2 parameters point to.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>When this function is called, the buffer1 parameter typically points to the
- start of the first undelivered TS packet within a circular buffer. The buffer2
- buffer parameter is normally NULL, except when the received TS packets have
- crossed the last address of the circular buffer and &#8221;wrapped&#8221; to the beginning
- of the buffer. In the latter case the buffer1 parameter would contain an address
- within the circular buffer, while the buffer2 parameter would contain the first
- address of the circular buffer.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The number of bytes delivered with this function (i.e. buffer1_length +
- buffer2_length) is usually equal to the value of callback_length parameter
- given in the set() function, with one exception: if a timeout occurs before
- receiving callback_length bytes of TS data, any undelivered packets are
- immediately delivered to the client by calling this function. The timeout
- duration is controlled by the set() function in the TS Feed API.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>If a TS packet is received with errors that could not be fixed by the TS-level
- forward error correction (FEC), the Transport_error_indicator flag of the TS
- packet header should be set. The TS packet should not be discarded, as
- the error can possibly be corrected by a higher layer protocol. If the called
- party is slow in processing the callback, it is possible that the circular buffer
- eventually fills up. If this happens, the demux driver should discard any TS
- packets received while the buffer is full. The error should be indicated to the
- client on the next callback by setting the success parameter to the value of
- DMX_OVERRUN_ERROR.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The type of data returned to the callback can be selected by the new
- function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t
- pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the
- include file ost/demux.h) The type parameter decides if the raw TS packet
- (TS_PACKET) or just the payload (TS_PACKET&#8212;TS_PAYLOAD_ONLY)
- should be returned. If additionally the TS_DECODER bit is set the stream
- will also be sent to the hardware MPEG decoder. In this case, the second
- flag decides as what kind of data the stream should be interpreted. The
- possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO,
- DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE,
- DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int dmx_ts_cb(__u8&#x22C6; buffer1, size_t buffer1_length,
- __u8&#x22C6; buffer2, size_t buffer2_length, dmx_ts_feed_t&#x22C6;
- source);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>__u8* buffer1</para>
-</entry><entry
- align="char">
-<para>Pointer to the start of the filtered TS packets.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer1_length</para>
-</entry><entry
- align="char">
-<para>Length of the TS data in buffer1.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8* buffer2</para>
-</entry><entry
- align="char">
-<para>Pointer to the tail of the filtered TS packets, or NULL.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer2_length</para>
-</entry><entry
- align="char">
-<para>Length of the TS data in buffer2.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_ts_feed_t*
- source</para>
-</entry><entry
- align="char">
-<para>Indicates which TS feed is the source of the callback.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>Continue filtering.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-1</para>
-</entry><entry
- align="char">
-<para>Stop filtering - has the same effect as a call to
- stop_filtering() on the TS Feed API.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>dmx_section_cb()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function, provided by the client of the demux API, is called from the
- demux code. The function is only called when filtering of sections has been
- enabled using the function start_filtering() of the section feed API. When the
- demux driver has received a complete section that matches at least one section
- filter, the client is notified via this callback function. Normally this function is
- called for each received section; however, it is also possible to deliver multiple
- sections with one callback, for example when the system load is high. If an
- error occurs while receiving a section, this function should be called with
- the corresponding error type set in the success field, whether or not there is
- data to deliver. The Section Feed implementation should maintain a circular
- buffer for received sections. However, this is not necessary if the Section Feed
- API is implemented as a client of the TS Feed API, because the TS Feed
- implementation then buffers the received data. The size of the circular buffer
- can be configured using the set() function in the Section Feed API. If there
- is no room in the circular buffer when a new section is received, the section
- must be discarded. If this happens, the value of the success parameter should
- be DMX_OVERRUN_ERROR on the next callback.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int dmx_section_cb(__u8&#x22C6; buffer1, size_t
- buffer1_length, __u8&#x22C6; buffer2, size_t
- buffer2_length, dmx_section_filter_t&#x22C6; source);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>__u8* buffer1</para>
-</entry><entry
- align="char">
-<para>Pointer to the start of the filtered section, e.g. within the
- circular buffer of the demux driver.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer1_length</para>
-</entry><entry
- align="char">
-<para>Length of the filtered section data in buffer1, including
- headers and CRC.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u8* buffer2</para>
-</entry><entry
- align="char">
-<para>Pointer to the tail of the filtered section data, or NULL.
- Useful to handle the wrapping of a circular buffer.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t buffer2_length</para>
-</entry><entry
- align="char">
-<para>Length of the filtered section data in buffer2, including
- headers and CRC.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_filter_t*
- filter</para>
-</entry><entry
- align="char">
-<para>Indicates the filter that triggered the callback.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>Continue filtering.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-1</para>
-</entry><entry
- align="char">
-<para>Stop filtering - has the same effect as a call to
- stop_filtering() on the Section Feed API.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
-<section id="ts_feed_api">
-<title>TS Feed API</title>
-<para>A TS feed is typically mapped to a hardware PID filter on the demux chip.
-Using this API, the client can set the filtering properties to start/stop filtering TS
-packets on a particular TS feed. The API is defined as an abstract interface of the type
-dmx_ts_feed_t.
-</para>
-<para>The functions that implement the interface should be defined static or module private. The
-client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
-demux API.
-</para>
-
-<section
-role="subsection"><title>set()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function sets the parameters of a TS feed. Any filtering in progress on the
- TS feed must be stopped before calling this function.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int set ( dmx_ts_feed_t&#x22C6; feed, __u16 pid, size_t
- callback_length, size_t circular_buffer_size, int
- descramble, struct timespec timeout);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_ts_feed_t* feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 pid</para>
-</entry><entry
- align="char">
-<para>PID value to filter. Only the TS packets carrying the
- specified PID will be passed to the API client.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t
- callback_length</para>
-</entry><entry
- align="char">
-<para>Number of bytes to deliver with each call to the
- dmx_ts_cb() callback function. The value of this
- parameter should be a multiple of 188.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t
- circular_buffer_size</para>
-</entry><entry
- align="char">
-<para>Size of the circular buffer for the filtered TS packets.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int descramble</para>
-</entry><entry
- align="char">
-<para>If non-zero, descramble the filtered TS packets.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>struct timespec
- timeout</para>
-</entry><entry
- align="char">
-<para>Maximum time to wait before delivering received TS
- packets to the client.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOMEM</para>
-</entry><entry
- align="char">
-<para>Not enough memory for the requested buffer size.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>No descrambling facility available for TS.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>start_filtering()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Starts filtering TS packets on this TS feed, according to its settings. The PID
- value to filter can be set by the API client. All matching TS packets are
- delivered asynchronously to the client, using the callback function registered
- with allocate_ts_feed().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int start_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_ts_feed_t* feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>stop_filtering()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Stops filtering TS packets on this TS feed.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int stop_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_ts_feed_t* feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the TS feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
- </section></section>
-<section id="section_feed_api">
-<title>Section Feed API</title>
-<para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this
-API, the client can set the properties of a section feed and to start/stop filtering. The API is
-defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
-the interface should be defined static or module private. The client can get the handle of
-a section feed API by calling the function allocate_section_feed() in the demux
-API.
-</para>
-<para>On demux platforms that provide section filtering in hardware, the Section Feed API
-implementation provides a software wrapper for the demux hardware. Other platforms may
-support only PID filtering in hardware, requiring that TS packets are converted to sections in
-software. In the latter case the Section Feed API implementation can be a client of the TS
-Feed API.
-</para>
-
-</section>
-<section id="kdapi_set">
-<title>set()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function sets the parameters of a section feed. Any filtering in progress on
- the section feed must be stopped before calling this function. If descrambling
- is enabled, the payload_scrambling_control and address_scrambling_control
- fields of received DVB datagram sections should be observed. If either one is
- non-zero, the section should be descrambled either in hardware or using the
- functions descramble_mac_address() and descramble_section_payload() of the
- demux API. Note that according to the MPEG-2 Systems specification, only
- the payloads of private sections can be scrambled while the rest of the section
- data must be sent in the clear.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int set(dmx_section_feed_t&#x22C6; feed, __u16 pid, size_t
- circular_buffer_size, int descramble, int
- check_crc);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>__u16 pid</para>
-</entry><entry
- align="char">
-<para>PID value to filter; only the TS packets carrying the
- specified PID will be accepted.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>size_t
- circular_buffer_size</para>
-</entry><entry
- align="char">
-<para>Size of the circular buffer for filtered sections.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int descramble</para>
-</entry><entry
- align="char">
-<para>If non-zero, descramble any sections that are scrambled.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>int check_crc</para>
-</entry><entry
- align="char">
-<para>If non-zero, check the CRC values of filtered sections.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOMEM</para>
-</entry><entry
- align="char">
-<para>Not enough memory for the requested buffer size.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSYS</para>
-</entry><entry
- align="char">
-<para>No descrambling facility available for sections.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameters.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>allocate_filter()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function is used to allocate a section filter on the demux. It should only be
- called when no filtering is in progress on this section feed. If a filter cannot be
- allocated, the function fails with -ENOSPC. See in section ?? for the format of
- the section filter.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>The bitfields filter_mask and filter_value should only be modified when no
- filtering is in progress on this section feed. filter_mask controls which bits of
- filter_value are compared with the section headers/payload. On a binary value
- of 1 in filter_mask, the corresponding bits are compared. The filter only accepts
- sections that are equal to filter_value in all the tested bit positions. Any changes
- to the values of filter_mask and filter_value are guaranteed to take effect only
- when the start_filtering() function is called next time. The parent pointer in
- the struct is initialized by the API implementation to the value of the feed
- parameter. The priv pointer is not used by the API implementation, and can
- thus be freely utilized by the caller of this function. Any data pointed to by the
- priv pointer is available to the recipient of the dmx_section_cb() function call.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is
- currently set at 16 bytes, hardware filters of that size are not available on all
- platforms. Therefore, section filtering will often take place first in hardware,
- followed by filtering in software for the header bytes that were not covered
- by a hardware filter. The filter_mask field can be checked to determine how
- many bytes of the section filter are actually used, and if the hardware filter will
- suffice. Additionally, software-only section filters can optionally be allocated
- to clients when all hardware section filters are in use. Note that on most demux
- hardware it is not possible to filter on the section_length field of the section
- header &#8211; thus this field is ignored, even though it is included in filter_value and
- filter_mask fields.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int allocate_filter(dmx_section_feed_t&#x22C6; feed,
- dmx_section_filter_t&#x22C6;&#x22C6; filter);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_filter_t**
- filter</para>
-</entry><entry
- align="char">
-<para>Pointer to the allocated filter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENOSPC</para>
-</entry><entry
- align="char">
-<para>No filters of given type and length available.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameters.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>release_filter()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>This function releases all the resources of a previously allocated section filter.
- The function should not be called while filtering is in progress on this section
- feed. After calling this function, the caller should not try to dereference the
- filter pointer.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int release_filter ( dmx_section_feed_t&#x22C6; feed,
- dmx_section_filter_t&#x22C6; filter);</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>dmx_section_filter_t*
- filter</para>
-</entry><entry
- align="char">
-<para>I/O Pointer to the instance data of a section filter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-ENODEV</para>
-</entry><entry
- align="char">
-<para>No such filter allocated.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>start_filtering()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Starts filtering sections on this section feed, according to its settings. Sections
- are first filtered based on their PID and then matched with the section
- filters allocated for this feed. If the section matches the PID filter and
- at least one section filter, it is delivered to the API client. The section
- is delivered asynchronously using the callback function registered with
- allocate_section_feed().</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int start_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section><section
-role="subsection"><title>stop_filtering()</title>
-<para>DESCRIPTION
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>Stops filtering sections on this section feed. Note that any changes to the
- filtering parameters (filter_value, filter_mask, etc.) should only be made when
- filtering is stopped.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>SYNOPSIS
-</para>
-<informaltable><tgroup cols="1"><tbody><row><entry
- align="char">
-<para>int stop_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>PARAMETERS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>dmx_section_feed_t*
- feed</para>
-</entry><entry
- align="char">
-<para>Pointer to the section feed API and instance data.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-<para>RETURNS
-</para>
-<informaltable><tgroup cols="2"><tbody><row><entry
- align="char">
-<para>0</para>
-</entry><entry
- align="char">
-<para>The function was completed without errors.</para>
-</entry>
- </row><row><entry
- align="char">
-<para>-EINVAL</para>
-</entry><entry
- align="char">
-<para>Bad parameter.</para>
-</entry>
- </row></tbody></tgroup></informaltable>
-
-</section>
-- 
2.4.3