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	49	replace typedef dmx_filter_t :c:type:`dmx_filter`
50	50	replace typedef dmx_pes_type_t :c:type:`dmx_pes_type`
51	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	6	Demux Data Types
7	7	****************
8	8
9		−Output for the demux
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		− };
	9	+.. kernel-doc:: include/uapi/linux/dvb/dmx.h

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

@@ -32,26 +32,74 @@ · 31 unmodified lines
32	32
33	33	#define DMX_FILTER_SIZE 16
34	34
35		−enum dmx_output
36		−{
37		− DMX_OUT_DECODER, /* Streaming directly to decoder. */
38		− DMX_OUT_TAP, /* Output going to a memory buffer */
39		− /* (to be retrieved via the read command).*/
40		− DMX_OUT_TS_TAP, /* Output multiplexed into a new TS */
41		− /* (to be retrieved by reading from the */
42		− /* logical DVR device). */
43		− DMX_OUT_TSDEMUX_TAP /* Like TS_TAP but retrieved from the DMX device */
	35	+/**
	36	+ * enum dmx_output - Output for the demux.
	37	+ *
	38	+ * @DMX_OUT_DECODER:
	39	+ * Streaming directly to decoder.
	40	+ * @DMX_OUT_TAP:
	41	+ * Output going to a memory buffer (to be retrieved via the read command).
	42	+ * Delivers the stream output to the demux device on which the ioctl
	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
47		−{
48		− DMX_IN_FRONTEND, /* Input from a front-end device. */
49		− DMX_IN_DVR /* Input from the logical DVR device. */
	59	+
	60	+/**
	61	+ * enum dmx_input - Input from the demux.
	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
54		−{
	102	+enum dmx_ts_pes {
55	103	DMX_PES_AUDIO0,
56	104	DMX_PES_VIDEO0,
57	105	DMX_PES_TELETEXT0,
@@ -86,16 +134,42 @@ enum dmx_ts_pes · 28 unmodified lines
86	134	#define DMX_PES_PCR DMX_PES_PCR0
87	135
88	136
89		−struct dmx_filter
90		−{
	137	+
	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	149	__u8 filter[DMX_FILTER_SIZE];
92	150	__u8 mask[DMX_FILTER_SIZE];
93	151	__u8 mode[DMX_FILTER_SIZE];
94	152	};
95	153
96		−
97		−struct dmx_sct_filter_params
98		−{
	154	+/**
	155	+ * struct dmx_sct_filter_params - Specifies a section filter.
	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	173	__u16 pid;
100	174	struct dmx_filter filter;
101	175	__u32 timeout;
@@ -105,7 +179,16 @@ struct dmx_sct_filter_params · 3 unmodified lines
105	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	192	struct dmx_pes_filter_params
110	193	{
111	194	__u16 pid;
@@ -115,11 +198,17 @@ struct dmx_pes_filter_params · 3 unmodified lines
115	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	208	struct dmx_stc {
120		− unsigned int num; /* input : which STC? 0..N */
121		− unsigned int base; /* output: divisor for stc to get 90 kHz clock */
122		− __u64 stc; /* output: stc in 'base'90 kHz units /
	209	+ unsigned int num;
	210	+ unsigned int base;
	211	+ __u64 stc;
123	212	};
124	213
125	214	#define DMX_START _IO('o', 41)