From 0ed08b496c1be29e1b709ee853038f749f550072 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 6 May 2011 12:32:03 -0300 Subject: [PATCH] DocBook/dvb: Improve description of the DVB API v5 Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/dvb/dvbapi.xml | 8 + Documentation/DocBook/dvb/dvbproperty.xml | 375 ++++++++++++++++++---- 2 files changed, 315 insertions(+), 68 deletions(-) diff --git a/Documentation/DocBook/dvb/dvbapi.xml b/Documentation/DocBook/dvb/dvbapi.xml index ad8678d48916..9fad86ce7f5e 100644 --- a/Documentation/DocBook/dvb/dvbapi.xml +++ b/Documentation/DocBook/dvb/dvbapi.xml @@ -34,6 +34,14 @@ + + 2.0.4 + 2011-05-06 + mcc + + Add more information about DVB APIv5, better describing the frontend GET/SET props ioctl's. + + 2.0.3 2010-07-03 diff --git a/Documentation/DocBook/dvb/dvbproperty.xml b/Documentation/DocBook/dvb/dvbproperty.xml index 97f397e2fb3a..05ce60362e23 100644 --- a/Documentation/DocBook/dvb/dvbproperty.xml +++ b/Documentation/DocBook/dvb/dvbproperty.xml @@ -1,6 +1,312 @@ -
+
FE_GET_PROPERTY/FE_SET_PROPERTY + +/* Reserved fields should be set to 0 */ +struct dtv_property { + __u32 cmd; + union { + __u32 data; + struct { + __u8 data[32]; + __u32 len; + __u32 reserved1[3]; + void *reserved2; + } buffer; + } u; + int result; +} __attribute__ ((packed)); + +/* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */ +#define DTV_IOCTL_MAX_MSGS 64 + +struct dtv_properties { + __u32 num; + struct dtv_property *props; +}; + + +
+FE_GET_PROPERTY +DESCRIPTION + + +This ioctl call returns one or more frontend properties. This call only + requires read-only access to the device. + + +SYNOPSIS + + +int ioctl(int fd, int request = FE_GET_PROPERTY, + dtv_properties ⋆props); + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int num + +Equals FE_GET_PROPERTY for this command. + + +struct dtv_property *props + +Points to the location where the front-end property commands are stored. + + +ERRORS + + EINVAL + Invalid parameter(s) received or number of parameters out of the range. + + ENOMEM + Out of memory. + + EFAULT + Failure while copying data from/to userspace. + + EOPNOTSUPP + Property type not supported. + +
+ +
+FE_SET_PROPERTY +DESCRIPTION + + +This ioctl call sets one or more frontend properties. This call only + requires read-only access to the device. + + +SYNOPSIS + + +int ioctl(int fd, int request = FE_SET_PROPERTY, + dtv_properties ⋆props); + + +PARAMETERS + + +int fd + +File descriptor returned by a previous call to open(). + + +int num + +Equals FE_SET_PROPERTY for this command. + + +struct dtv_property *props + +Points to the location where the front-end property commands are stored. + + +ERRORS + + + EINVAL + Invalid parameter(s) received or number of parameters out of the range. + + ENOMEM + Out of memory. + + EFAULT + Failure while copying data from/to userspace. + + EOPNOTSUPP + Property type not supported. + +
+ + +On FE_GET_PROPERTY/FE_SET_PROPERTY, +the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to +get/set up to 64 properties. The actual meaning of each property is described on the next sections. + + +The Available frontend property types are: + +#define DTV_UNDEFINED 0 +#define DTV_TUNE 1 +#define DTV_CLEAR 2 +#define DTV_FREQUENCY 3 +#define DTV_MODULATION 4 +#define DTV_BANDWIDTH_HZ 5 +#define DTV_INVERSION 6 +#define DTV_DISEQC_MASTER 7 +#define DTV_SYMBOL_RATE 8 +#define DTV_INNER_FEC 9 +#define DTV_VOLTAGE 10 +#define DTV_TONE 11 +#define DTV_PILOT 12 +#define DTV_ROLLOFF 13 +#define DTV_DISEQC_SLAVE_REPLY 14 +#define DTV_FE_CAPABILITY_COUNT 15 +#define DTV_FE_CAPABILITY 16 +#define DTV_DELIVERY_SYSTEM 17 +#define DTV_ISDBT_PARTIAL_RECEPTION 18 +#define DTV_ISDBT_SOUND_BROADCASTING 19 +#define DTV_ISDBT_SB_SUBCHANNEL_ID 20 +#define DTV_ISDBT_SB_SEGMENT_IDX 21 +#define DTV_ISDBT_SB_SEGMENT_COUNT 22 +#define DTV_ISDBT_LAYERA_FEC 23 +#define DTV_ISDBT_LAYERA_MODULATION 24 +#define DTV_ISDBT_LAYERA_SEGMENT_COUNT 25 +#define DTV_ISDBT_LAYERA_TIME_INTERLEAVING 26 +#define DTV_ISDBT_LAYERB_FEC 27 +#define DTV_ISDBT_LAYERB_MODULATION 28 +#define DTV_ISDBT_LAYERB_SEGMENT_COUNT 29 +#define DTV_ISDBT_LAYERB_TIME_INTERLEAVING 30 +#define DTV_ISDBT_LAYERC_FEC 31 +#define DTV_ISDBT_LAYERC_MODULATION 32 +#define DTV_ISDBT_LAYERC_SEGMENT_COUNT 33 +#define DTV_ISDBT_LAYERC_TIME_INTERLEAVING 34 +#define DTV_API_VERSION 35 +#define DTV_CODE_RATE_HP 36 +#define DTV_CODE_RATE_LP 37 +#define DTV_GUARD_INTERVAL 38 +#define DTV_TRANSMISSION_MODE 39 +#define DTV_HIERARCHY 40 +#define DTV_ISDBT_LAYER_ENABLED 41 +#define DTV_ISDBS_TS_ID 42 + + +
+ Parameters that are common to all Digital TV standards +
+ <constant>DTV_FREQUENCY</constant> + + Central frequency of the channel, in HZ. + + Notes: + 1)For ISDB-T, the channels are usually transmitted with an offset of 143kHz. + E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of + the channel which is 6MHz. + + 2)As in ISDB-Tsb the channel consists of only one or three segments the + frequency step is 429kHz, 3*429 respectively. As for ISDB-T the + central frequency of the channel is expected. +
+ +
+ <constant>DTV_BANDWIDTH_HZ</constant> + + Bandwidth for the channel, in HZ. + + Possible values: + 6000000, + 7000000, + 8000000. + + + Notes: + + 1) For ISDB-T it should be always 6000000Hz (6MHz) + 2) For ISDB-Tsb it can vary depending on the number of connected segments + 3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth + for DVB-C depends on the symbol rate + 4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from + other parameters (DTV_ISDBT_SB_SEGMENT_IDX, + DTV_ISDBT_SB_SEGMENT_COUNT). +
+ +
+ <constant>DTV_DELIVERY_SYSTEM</constant> + + Specifies the type of Delivery system + + Possible values: + +typedef enum fe_delivery_system { + SYS_UNDEFINED, + SYS_DVBC_ANNEX_AC, + SYS_DVBC_ANNEX_B, + SYS_DVBT, + SYS_DSS, + SYS_DVBS, + SYS_DVBS2, + SYS_DVBH, + SYS_ISDBT, + SYS_ISDBS, + SYS_ISDBC, + SYS_ATSC, + SYS_ATSCMH, + SYS_DMBTH, + SYS_CMMB, + SYS_DAB, +} fe_delivery_system_t; + + +
+ +
+ <constant>DTV_TRANSMISSION_MODE</constant> + + Specifies the number of carriers used by the standard + + Possible values are: + +typedef enum fe_transmit_mode { + TRANSMISSION_MODE_2K, + TRANSMISSION_MODE_8K, + TRANSMISSION_MODE_AUTO, + TRANSMISSION_MODE_4K +} fe_transmit_mode_t; + + + Notes: + 1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called + 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K + + 2) If DTV_TRANSMISSION_MODE is set the TRANSMISSION_MODE_AUTO the + hardware will try to find the correct FFT-size (if capable) and will + use TMCC to fill in the missing parameters. +
+ +
+ <constant>DTV_GUARD_INTERVAL</constant> + + Possible values are: + +typedef enum fe_guard_interval { + GUARD_INTERVAL_1_32, + GUARD_INTERVAL_1_16, + GUARD_INTERVAL_1_8, + GUARD_INTERVAL_1_4, + GUARD_INTERVAL_AUTO +} fe_guard_interval_t; + + + Notes: + 1) If DTV_GUARD_INTERVAL is set the GUARD_INTERVAL_AUTO the hardware will + try to find the correct guard interval (if capable) and will use TMCC to fill + in the missing parameters. +
+
+
ISDB-T frontend This section describes shortly what are the possible parameters in the Linux @@ -32,73 +338,6 @@ Parameters used by ISDB-T and ISDB-Tsb. -
- Parameters that are common with DVB-T and ATSC - -
- <constant>DTV_FREQUENCY</constant> - - Central frequency of the channel. - - For ISDB-T the channels are usually transmitted with an offset of 143kHz. E.g. a - valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of - the channel which is 6MHz. - - As in ISDB-Tsb the channel consists of only one or three segments the - frequency step is 429kHz, 3*429 respectively. As for ISDB-T the - central frequency of the channel is expected. -
- -
- <constant>DTV_BANDWIDTH_HZ</constant> (optional) - - Possible values: - - For ISDB-T it should be always 6000000Hz (6MHz) - For ISDB-Tsb it can vary depending on the number of connected segments - - Note: Hardware specific values might be given here, but standard - applications should not bother to set a value to this field as - standard demods are ignoring it anyway. - - Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from - other parameters (DTV_ISDBT_SB_SEGMENT_IDX, - DTV_ISDBT_SB_SEGMENT_COUNT). -
- -
- <constant>DTV_DELIVERY_SYSTEM</constant> - - Possible values: SYS_ISDBT -
- -
- <constant>DTV_TRANSMISSION_MODE</constant> - - ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called - 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K - - Possible values: TRANSMISSION_MODE_2K, TRANSMISSION_MODE_8K, - TRANSMISSION_MODE_AUTO, TRANSMISSION_MODE_4K - - If DTV_TRANSMISSION_MODE is set the TRANSMISSION_MODE_AUTO the - hardware will try to find the correct FFT-size (if capable) and will - use TMCC to fill in the missing parameters. - - TRANSMISSION_MODE_4K is added at the same time as the other new parameters. -
- -
- <constant>DTV_GUARD_INTERVAL</constant> - - Possible values: GUARD_INTERVAL_1_32, GUARD_INTERVAL_1_16, GUARD_INTERVAL_1_8, - GUARD_INTERVAL_1_4, GUARD_INTERVAL_AUTO - - If DTV_GUARD_INTERVAL is set the GUARD_INTERVAL_AUTO the hardware will - try to find the correct guard interval (if capable) and will use TMCC to fill - in the missing parameters. -
-
ISDB-T only parameters -- 2.30.2