diff options
author | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-08-31 19:28:52 +0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@s-opensource.com> | 2017-09-05 13:05:40 +0300 |
commit | bb98e6d280e00a1180f47d3391ee0bd1f312b5f6 (patch) | |
tree | e763d8e59879b6d91b1d3b958f393fa1e51af7a3 /include/uapi | |
parent | 2889017c92ddacfbece9a288bbc716e1c5ab719b (diff) | |
download | linux-bb98e6d280e00a1180f47d3391ee0bd1f312b5f6.tar.xz |
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 :-)
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'include/uapi')
-rw-r--r-- | include/uapi/linux/dvb/dmx.h | 139 |
1 files changed, 114 insertions, 25 deletions
diff --git a/include/uapi/linux/dvb/dmx.h b/include/uapi/linux/dvb/dmx.h index 08dc17060321..4e3f3a2fe83f 100644 --- a/include/uapi/linux/dvb/dmx.h +++ b/include/uapi/linux/dvb/dmx.h @@ -32,26 +32,74 @@ #define DMX_FILTER_SIZE 16 -enum dmx_output -{ - DMX_OUT_DECODER, /* Streaming directly to decoder. */ - DMX_OUT_TAP, /* Output going to a memory buffer */ - /* (to be retrieved via the read command).*/ - DMX_OUT_TS_TAP, /* Output multiplexed into a new TS */ - /* (to be retrieved by reading from the */ - /* logical DVR device). */ - DMX_OUT_TSDEMUX_TAP /* Like TS_TAP but retrieved from the DMX device */ +/** + * enum dmx_output - Output for the demux. + * + * @DMX_OUT_DECODER: + * Streaming directly to decoder. + * @DMX_OUT_TAP: + * Output going to a memory buffer (to be retrieved via the read command). + * Delivers the stream output to the demux device on which the ioctl + * is called. + * @DMX_OUT_TS_TAP: + * Output multiplexed into a new TS (to be retrieved by reading from the + * logical DVR device). Routes output to the logical DVR device + * ``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from all + * filters for which @DMX_OUT_TS_TAP was specified. + * @DMX_OUT_TSDEMUX_TAP: + * Like @DMX_OUT_TS_TAP but retrieved from the DMX device. + */ +enum dmx_output { + DMX_OUT_DECODER, + DMX_OUT_TAP, + DMX_OUT_TS_TAP, + DMX_OUT_TSDEMUX_TAP }; -enum dmx_input -{ - DMX_IN_FRONTEND, /* Input from a front-end device. */ - DMX_IN_DVR /* Input from the logical DVR device. */ + +/** + * enum dmx_input - Input from the demux. + * + * @DMX_IN_FRONTEND: Input from a front-end device. + * @DMX_IN_DVR: Input from the logical DVR device. + */ +enum dmx_input { + DMX_IN_FRONTEND, + DMX_IN_DVR }; +/** + * enum dmx_ts_pes - type of the PES filter. + * + * @DMX_PES_AUDIO0: first audio PID. Also referred as @DMX_PES_AUDIO. + * @DMX_PES_VIDEO0: first video PID. Also referred as @DMX_PES_VIDEO. + * @DMX_PES_TELETEXT0: first teletext PID. Also referred as @DMX_PES_TELETEXT. + * @DMX_PES_SUBTITLE0: first subtitle PID. Also referred as @DMX_PES_SUBTITLE. + * @DMX_PES_PCR0: first Program Clock Reference PID. + * Also referred as @DMX_PES_PCR. + * + * @DMX_PES_AUDIO1: second audio PID. + * @DMX_PES_VIDEO1: second video PID. + * @DMX_PES_TELETEXT1: second teletext PID. + * @DMX_PES_SUBTITLE1: second subtitle PID. + * @DMX_PES_PCR1: second Program Clock Reference PID. + * + * @DMX_PES_AUDIO2: third audio PID. + * @DMX_PES_VIDEO2: third video PID. + * @DMX_PES_TELETEXT2: third teletext PID. + * @DMX_PES_SUBTITLE2: third subtitle PID. + * @DMX_PES_PCR2: third Program Clock Reference PID. + * + * @DMX_PES_AUDIO3: fourth audio PID. + * @DMX_PES_VIDEO3: fourth video PID. + * @DMX_PES_TELETEXT3: fourth teletext PID. + * @DMX_PES_SUBTITLE3: fourth subtitle PID. + * @DMX_PES_PCR3: fourth Program Clock Reference PID. + * + * @DMX_PES_OTHER: any other PID. + */ -enum dmx_ts_pes -{ +enum dmx_ts_pes { DMX_PES_AUDIO0, DMX_PES_VIDEO0, DMX_PES_TELETEXT0, @@ -86,16 +134,42 @@ enum dmx_ts_pes #define DMX_PES_PCR DMX_PES_PCR0 -struct dmx_filter -{ + +/** + * struct dmx_filter - Specifies a section header filter. + * + * @filter: bit array with bits to be matched at the section header. + * @mask: bits that are valid at the filter bit array. + * @mode: mode of match: if bit is zero, it will match if equal (positive + * match); if bit is one, it will match if the bit is negated. + * + * Note: All arrays in this struct have a size of DMX_FILTER_SIZE (16 bytes). + */ +struct dmx_filter { __u8 filter[DMX_FILTER_SIZE]; __u8 mask[DMX_FILTER_SIZE]; __u8 mode[DMX_FILTER_SIZE]; }; - -struct dmx_sct_filter_params -{ +/** + * struct dmx_sct_filter_params - Specifies a section filter. + * + * @pid: PID to be filtered. + * @filter: section header filter, as defined by &struct dmx_filter. + * @timeout: maximum time to filter, in milliseconds. + * @flags: extra flags for the section filter. + * + * Carries the configuration for a MPEG-TS section filter. + * + * The @flags can be: + * + * - %DMX_CHECK_CRC - only deliver sections where the CRC check succeeded; + * - %DMX_ONESHOT - disable the section filter after one section + * has been delivered; + * - %DMX_IMMEDIATE_START - Start filter immediately without requiring a + * :ref:`DMX_START`. + */ +struct dmx_sct_filter_params { __u16 pid; struct dmx_filter filter; __u32 timeout; @@ -105,7 +179,16 @@ struct dmx_sct_filter_params #define DMX_IMMEDIATE_START 4 }; - +/** + * struct dmx_pes_filter_params - Specifies Packetized Elementary Stream (PES) + * filter parameters. + * + * @pid: PID to be filtered. + * @input: Demux input, as specified by &enum dmx_input. + * @output: Demux output, as specified by &enum dmx_output. + * @pes_type: Type of the pes filter, as specified by &enum dmx_pes_type. + * @flags: Demux PES flags. + */ struct dmx_pes_filter_params { __u16 pid; @@ -115,11 +198,17 @@ struct dmx_pes_filter_params __u32 flags; }; - +/** + * struct dmx_stc - Stores System Time Counter (STC) information. + * + * @num: input data: number of the STC, from 0 to N. + * @base: output: divisor for STC to get 90 kHz clock. + * @stc: output: stc in @base * 90 kHz units. + */ struct dmx_stc { - unsigned int num; /* input : which STC? 0..N */ - unsigned int base; /* output: divisor for stc to get 90 kHz clock */ - __u64 stc; /* output: stc in 'base'*90 kHz units */ + unsigned int num; + unsigned int base; + __u64 stc; }; #define DMX_START _IO('o', 41) |