media: dmx.h: add kernel-doc markups and use it at Documentation/

The demux documentation is pretty poor nowadays: most of the structs and enums aren't documented at all. Add proper kernel-doc markups for them and use it. Now, the demux API data structures are fully documented :-)

Mauro Carvalho Chehab committed 9 years ago

Commit bb98e6d1 parent 28890173 files · +120 −197Browse files

Unified · Split

3 files

Documentation/media/dmx.h.rst.exceptions +5 −0
Documentation/media/uapi/dvb/dmx_types.rst +1 −172
include/uapi/linux/dvb/dmx.h +114 −25

Documentation/media/dmx.h.rst.exceptions+5−0

@@ -49,3 +49,8 @@ replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params` · 48 unmodified lines
49	replace typedef dmx_filter_t :c:type:`dmx_filter`	49	replace typedef dmx_filter_t :c:type:`dmx_filter`
50	replace typedef dmx_pes_type_t :c:type:`dmx_pes_type`	50	replace typedef dmx_pes_type_t :c:type:`dmx_pes_type`
51	replace typedef dmx_input_t :c:type:`dmx_input`	51	replace typedef dmx_input_t :c:type:`dmx_input`
		52
		53	ignore symbol DMX_OUT_DECODER
		54	ignore symbol DMX_OUT_TAP
		55	ignore symbol DMX_OUT_TS_TAP
		56	ignore symbol DMX_OUT_TSDEMUX_TAP

Documentation/media/uapi/dvb/dmx_types.rst+1−172

@@ -6,175 +6,4 @@ · 5 unmodified lines
6	Demux Data Types	6	Demux Data Types
7	****************	7	****************
8		8
9	Output for the demux	9	.. kernel-doc:: include/uapi/linux/dvb/dmx.h
10	====================
11
12	.. c:type:: dmx_output
13
14	.. tabularcolumns:: \|p{5.0cm}\|p{12.5cm}\|
15
16	.. flat-table:: enum dmx_output
17	:header-rows: 1
18	:stub-columns: 0
19
20
21	- .. row 1
22
23	- ID
24
25	- Description
26
27	- .. row 2
28
29	- .. _DMX-OUT-DECODER:
30
31	DMX_OUT_DECODER
32
33	- Streaming directly to decoder.
34
35	- .. row 3
36
37	- .. _DMX-OUT-TAP:
38
39	DMX_OUT_TAP
40
41	- Output going to a memory buffer (to be retrieved via the read
42	command). Delivers the stream output to the demux device on which
43	the ioctl is called.
44
45	- .. row 4
46
47	- .. _DMX-OUT-TS-TAP:
48
49	DMX_OUT_TS_TAP
50
51	- Output multiplexed into a new TS (to be retrieved by reading from
52	the logical DVR device). Routes output to the logical DVR device
53	``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from
54	all filters for which ``DMX_OUT_TS_TAP`` was specified.
55
56	- .. row 5
57
58	- .. _DMX-OUT-TSDEMUX-TAP:
59
60	DMX_OUT_TSDEMUX_TAP
61
62	- Like :ref:`DMX_OUT_TS_TAP <DMX-OUT-TS-TAP>` but retrieved
63	from the DMX device.
64
65
66	dmx_input_t
67	===========
68
69	.. c:type:: dmx_input
70
71	.. code-block:: c
72
73	typedef enum
74	{
75	DMX_IN_FRONTEND, /* Input from a front-end device. */
76	DMX_IN_DVR /* Input from the logical DVR device. */
77	} dmx_input_t;
78
79
80	dmx_pes_type_t
81	==============
82
83	.. c:type:: dmx_pes_type
84
85
86	.. code-block:: c
87
88	typedef enum
89	{
90	DMX_PES_AUDIO0,
91	DMX_PES_VIDEO0,
92	DMX_PES_TELETEXT0,
93	DMX_PES_SUBTITLE0,
94	DMX_PES_PCR0,
95
96	DMX_PES_AUDIO1,
97	DMX_PES_VIDEO1,
98	DMX_PES_TELETEXT1,
99	DMX_PES_SUBTITLE1,
100	DMX_PES_PCR1,
101
102	DMX_PES_AUDIO2,
103	DMX_PES_VIDEO2,
104	DMX_PES_TELETEXT2,
105	DMX_PES_SUBTITLE2,
106	DMX_PES_PCR2,
107
108	DMX_PES_AUDIO3,
109	DMX_PES_VIDEO3,
110	DMX_PES_TELETEXT3,
111	DMX_PES_SUBTITLE3,
112	DMX_PES_PCR3,
113
114	DMX_PES_OTHER
115	} dmx_pes_type_t;
116
117
118	struct dmx_filter
119	=================
120
121	.. c:type:: dmx_filter
122
123	.. code-block:: c
124
125	typedef struct dmx_filter
126	{
127	__u8 filter[DMX_FILTER_SIZE];
128	__u8 mask[DMX_FILTER_SIZE];
129	__u8 mode[DMX_FILTER_SIZE];
130	} dmx_filter_t;
131
132
133	.. c:type:: dmx_sct_filter_params
134
135	struct dmx_sct_filter_params
136	============================
137
138
139	.. code-block:: c
140
141	struct dmx_sct_filter_params
142	{
143	__u16 pid;
144	dmx_filter_t filter;
145	__u32 timeout;
146	__u32 flags;
147	#define DMX_CHECK_CRC 1
148	#define DMX_ONESHOT 2
149	#define DMX_IMMEDIATE_START 4
150	};
151
152
153	struct dmx_pes_filter_params
154	============================
155
156	.. c:type:: dmx_pes_filter_params
157
158	.. code-block:: c
159
160	struct dmx_pes_filter_params
161	{
162	__u16 pid;
163	dmx_input_t input;
164	dmx_output_t output;
165	dmx_pes_type_t pes_type;
166	__u32 flags;
167	};
168
169	struct dmx_stc
170	==============
171
172	.. c:type:: dmx_stc
173
174	.. code-block:: c
175
176	struct dmx_stc {
177	unsigned int num; /* input : which STC? 0..N */
178	unsigned int base; /* output: divisor for stc to get 90 kHz clock */
179	__u64 stc; /* output: stc in 'base'90 kHz units /
180	};

include/uapi/linux/dvb/dmx.h+114−25

@@ -32,26 +32,74 @@ · 31 unmodified lines
32		32
33	#define DMX_FILTER_SIZE 16	33	#define DMX_FILTER_SIZE 16
34		34
35	enum dmx_output	35	/**
36	{	36	* enum dmx_output - Output for the demux.
37	DMX_OUT_DECODER, /* Streaming directly to decoder. */	37	*
38	DMX_OUT_TAP, /* Output going to a memory buffer */	38	* @DMX_OUT_DECODER:
39	/* (to be retrieved via the read command).*/	39	* Streaming directly to decoder.
40	DMX_OUT_TS_TAP, /* Output multiplexed into a new TS */	40	* @DMX_OUT_TAP:
41	/* (to be retrieved by reading from the */	41	* Output going to a memory buffer (to be retrieved via the read command).
42	/* logical DVR device). */	42	* Delivers the stream output to the demux device on which the ioctl
43	DMX_OUT_TSDEMUX_TAP /* Like TS_TAP but retrieved from the DMX device */	43	* is called.
		44	* @DMX_OUT_TS_TAP:
		45	* Output multiplexed into a new TS (to be retrieved by reading from the
		46	* logical DVR device). Routes output to the logical DVR device
		47	* ``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from all
		48	* filters for which @DMX_OUT_TS_TAP was specified.
		49	* @DMX_OUT_TSDEMUX_TAP:
		50	* Like @DMX_OUT_TS_TAP but retrieved from the DMX device.
		51	*/
		52	enum dmx_output {
		53	DMX_OUT_DECODER,
		54	DMX_OUT_TAP,
		55	DMX_OUT_TS_TAP,
		56	DMX_OUT_TSDEMUX_TAP
44	};	57	};
45		58
46	enum dmx_input	59
47	{	60	/**
48	DMX_IN_FRONTEND, /* Input from a front-end device. */	61	* enum dmx_input - Input from the demux.
49	DMX_IN_DVR /* Input from the logical DVR device. */	62	*
		63	* @DMX_IN_FRONTEND: Input from a front-end device.
		64	* @DMX_IN_DVR: Input from the logical DVR device.
		65	*/
		66	enum dmx_input {
		67	DMX_IN_FRONTEND,
		68	DMX_IN_DVR
50	};	69	};
51		70
		71	/**
		72	* enum dmx_ts_pes - type of the PES filter.
		73	*
		74	* @DMX_PES_AUDIO0: first audio PID. Also referred as @DMX_PES_AUDIO.
		75	* @DMX_PES_VIDEO0: first video PID. Also referred as @DMX_PES_VIDEO.
		76	* @DMX_PES_TELETEXT0: first teletext PID. Also referred as @DMX_PES_TELETEXT.
		77	* @DMX_PES_SUBTITLE0: first subtitle PID. Also referred as @DMX_PES_SUBTITLE.
		78	* @DMX_PES_PCR0: first Program Clock Reference PID.
		79	* Also referred as @DMX_PES_PCR.
		80	*
		81	* @DMX_PES_AUDIO1: second audio PID.
		82	* @DMX_PES_VIDEO1: second video PID.
		83	* @DMX_PES_TELETEXT1: second teletext PID.
		84	* @DMX_PES_SUBTITLE1: second subtitle PID.
		85	* @DMX_PES_PCR1: second Program Clock Reference PID.
		86	*
		87	* @DMX_PES_AUDIO2: third audio PID.
		88	* @DMX_PES_VIDEO2: third video PID.
		89	* @DMX_PES_TELETEXT2: third teletext PID.
		90	* @DMX_PES_SUBTITLE2: third subtitle PID.
		91	* @DMX_PES_PCR2: third Program Clock Reference PID.
		92	*
		93	* @DMX_PES_AUDIO3: fourth audio PID.
		94	* @DMX_PES_VIDEO3: fourth video PID.
		95	* @DMX_PES_TELETEXT3: fourth teletext PID.
		96	* @DMX_PES_SUBTITLE3: fourth subtitle PID.
		97	* @DMX_PES_PCR3: fourth Program Clock Reference PID.
		98	*
		99	* @DMX_PES_OTHER: any other PID.
		100	*/
52		101
53	enum dmx_ts_pes	102	enum dmx_ts_pes {
54	{
55	DMX_PES_AUDIO0,	103	DMX_PES_AUDIO0,
56	DMX_PES_VIDEO0,	104	DMX_PES_VIDEO0,
57	DMX_PES_TELETEXT0,	105	DMX_PES_TELETEXT0,
@@ -86,16 +134,42 @@ enum dmx_ts_pes · 28 unmodified lines
86	#define DMX_PES_PCR DMX_PES_PCR0	134	#define DMX_PES_PCR DMX_PES_PCR0
87		135
88		136
89	struct dmx_filter	137
90	{	138	/**
		139	* struct dmx_filter - Specifies a section header filter.
		140	*
		141	* @filter: bit array with bits to be matched at the section header.
		142	* @mask: bits that are valid at the filter bit array.
		143	* @mode: mode of match: if bit is zero, it will match if equal (positive
		144	* match); if bit is one, it will match if the bit is negated.
		145	*
		146	* Note: All arrays in this struct have a size of DMX_FILTER_SIZE (16 bytes).
		147	*/
		148	struct dmx_filter {
91	__u8 filter[DMX_FILTER_SIZE];	149	__u8 filter[DMX_FILTER_SIZE];
92	__u8 mask[DMX_FILTER_SIZE];	150	__u8 mask[DMX_FILTER_SIZE];
93	__u8 mode[DMX_FILTER_SIZE];	151	__u8 mode[DMX_FILTER_SIZE];
94	};	152	};
95		153
96		154	/**
97	struct dmx_sct_filter_params	155	* struct dmx_sct_filter_params - Specifies a section filter.
98	{	156	*
		157	* @pid: PID to be filtered.
		158	* @filter: section header filter, as defined by &struct dmx_filter.
		159	* @timeout: maximum time to filter, in milliseconds.
		160	* @flags: extra flags for the section filter.
		161	*
		162	* Carries the configuration for a MPEG-TS section filter.
		163	*
		164	* The @flags can be:
		165	*
		166	* - %DMX_CHECK_CRC - only deliver sections where the CRC check succeeded;
		167	* - %DMX_ONESHOT - disable the section filter after one section
		168	* has been delivered;
		169	* - %DMX_IMMEDIATE_START - Start filter immediately without requiring a
		170	* :ref:`DMX_START`.
		171	*/
		172	struct dmx_sct_filter_params {
99	__u16 pid;	173	__u16 pid;
100	struct dmx_filter filter;	174	struct dmx_filter filter;
101	__u32 timeout;	175	__u32 timeout;
@@ -105,7 +179,16 @@ struct dmx_sct_filter_params · 3 unmodified lines
105	#define DMX_IMMEDIATE_START 4	179	#define DMX_IMMEDIATE_START 4
106	};	180	};
107		181
108		182	/**
		183	* struct dmx_pes_filter_params - Specifies Packetized Elementary Stream (PES)
		184	* filter parameters.
		185	*
		186	* @pid: PID to be filtered.
		187	* @input: Demux input, as specified by &enum dmx_input.
		188	* @output: Demux output, as specified by &enum dmx_output.
		189	* @pes_type: Type of the pes filter, as specified by &enum dmx_pes_type.
		190	* @flags: Demux PES flags.
		191	*/
109	struct dmx_pes_filter_params	192	struct dmx_pes_filter_params
110	{	193	{
111	__u16 pid;	194	__u16 pid;
@@ -115,11 +198,17 @@ struct dmx_pes_filter_params · 3 unmodified lines
115	__u32 flags;	198	__u32 flags;
116	};	199	};
117		200
118		201	/**
		202	* struct dmx_stc - Stores System Time Counter (STC) information.
		203	*
		204	* @num: input data: number of the STC, from 0 to N.
		205	* @base: output: divisor for STC to get 90 kHz clock.
		206	* @stc: output: stc in @base * 90 kHz units.
		207	*/
119	struct dmx_stc {	208	struct dmx_stc {
120	unsigned int num; /* input : which STC? 0..N */	209	unsigned int num;
121	unsigned int base; /* output: divisor for stc to get 90 kHz clock */	210	unsigned int base;
122	__u64 stc; /* output: stc in 'base'90 kHz units /	211	__u64 stc;
123	};	212	};
124		213
125	#define DMX_START _IO('o', 41)	214	#define DMX_START _IO('o', 41)