X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;ds=sidebyside;f=kernel%2FDocumentation%2FDocBook%2Fmedia%2Fdvb%2Fdvbproperty.xml;h=08227d4e915044985b2a6fd7b7966f95dac6e7a0;hb=e09b41010ba33a20a87472ee821fa407a5b8da36;hp=3018564ddfd91a15413093b2fd67480b1ec45b17;hpb=f93b97fd65072de626c074dbe099a1fff05ce060;p=kvmfornfv.git
diff --git a/kernel/Documentation/DocBook/media/dvb/dvbproperty.xml b/kernel/Documentation/DocBook/media/dvb/dvbproperty.xml
index 3018564dd..08227d4e9 100644
--- a/kernel/Documentation/DocBook/media/dvb/dvbproperty.xml
+++ b/kernel/Documentation/DocBook/media/dvb/dvbproperty.xml
@@ -1,14 +1,88 @@
-
-<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant>
-This section describes the DVB version 5 extension of the DVB-API, also
-called "S2API", as this API were added to provide support for DVB-S2. It was
-designed to be able to replace the old frontend API. Yet, the DISEQC and
-the capability ioctls weren't implemented yet via the new way.
-The typical usage for the FE_GET_PROPERTY/FE_SET_PROPERTY
-API is to replace the ioctl's were the
-struct dvb_frontend_parameters were used.
+
+DVB Frontend properties
+Tuning into a Digital TV physical channel and starting decoding it
+ requires changing a set of parameters, in order to control the
+ tuner, the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
+ antenna subsystem via Satellite Equipment Control (SEC), on satellite
+ systems. The actual parameters are specific to each particular digital
+ TV standards, and may change as the digital TV specs evolves.
+In the past, the strategy used was to have a union with the parameters
+ needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped
+ there. The problem is that, as the second generation standards appeared,
+ those structs were not big enough to contain the additional parameters.
+ Also, the union didn't have any space left to be expanded without breaking
+ userspace. So, the decision was to deprecate the legacy union/struct based
+ approach, in favor of a properties set approach.
+
+NOTE: on Linux DVB API version 3, setting a frontend were done via
+ struct dvb_frontend_parameters.
+ This got replaced on version 5 (also called "S2API", as this API were
+ added originally_enabled to provide support for DVB-S2), because the old
+ API has a very limited support to new standards and new hardware. This
+ section describes the new and recommended way to set the frontend, with
+ suppports all digital TV delivery systems.
+
+Example: with the properties based approach, in order to set the tuner
+ to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol
+ rate of 5.217 Mbauds, those properties should be sent to
+ FE_SET_PROPERTY ioctl:
+
+ &DTV-DELIVERY-SYSTEM; = SYS_DVBC_ANNEX_A
+ &DTV-FREQUENCY; = 651000000
+ &DTV-MODULATION; = QAM_256
+ &DTV-INVERSION; = INVERSION_AUTO
+ &DTV-SYMBOL-RATE; = 5217000
+ &DTV-INNER-FEC; = FEC_3_4
+ &DTV-TUNE;
+
+
+The code that would do the above is:
+
+#include <stdio.h>
+#include <fcntl.h>
+#include <sys/ioctl.h>
+#include <linux/dvb/frontend.h>
+
+static struct dtv_property props[] = {
+ { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
+ { .cmd = DTV_FREQUENCY, .u.data = 651000000 },
+ { .cmd = DTV_MODULATION, .u.data = QAM_256 },
+ { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO },
+ { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 },
+ { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 },
+ { .cmd = DTV_TUNE }
+};
+
+static struct dtv_properties dtv_prop = {
+ .num = 6, .props = props
+};
+
+int main(void)
+{
+ int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
+
+ if (!fd) {
+ perror ("open");
+ return -1;
+ }
+ if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
+ perror("ioctl");
+ return -1;
+ }
+ printf("Frontend set\n");
+ return 0;
+}
+
+
+NOTE: While it is possible to directly call the Kernel code like the
+ above example, it is strongly recommended to use
+ libdvbv5,
+ as it provides abstraction to work with the supported digital TV standards
+ and provides methods for usual operations like program scanning and to
+ read/write channel descriptor files.
+
-DTV stats type
+struct <structname>dtv_stats</structname>
struct dtv_stats {
__u8 scale; /* enum fecap_scale_params type */
@@ -20,19 +94,19 @@ struct dtv_stats {
-DTV stats type
+struct <structname>dtv_fe_stats</structname>
#define MAX_DTV_STATS 4
struct dtv_fe_stats {
__u8 len;
- struct dtv_stats stat[MAX_DTV_STATS];
+ &dtv-stats; stat[MAX_DTV_STATS];
} __packed;
-DTV property type
+struct <structname>dtv_property</structname>
/* Reserved fields should be set to 0 */
@@ -41,7 +115,7 @@ struct dtv_property {
__u32 reserved[3];
union {
__u32 data;
- struct dtv_fe_stats st;
+ &dtv-fe-stats; st;
struct {
__u8 data[32];
__u32 len;
@@ -57,115 +131,19 @@ struct dtv_property {
-DTV properties type
+struct <structname>dtv_properties</structname>
struct dtv_properties {
__u32 num;
- struct dtv_property *props;
+ &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.
-
-
-&return-value-dvb;
-
- EOPNOTSUPP
- Property type not supported.
-
-
-
-
-FE_SET_PROPERTY
-DESCRIPTION
-
-
-This ioctl call sets one or more frontend properties. This call
- requires read/write 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.
-
-
-&return-value-dvb;
-
- EOPNOTSUPP
- Property type not supported.
-
-
-
Property types
-On FE_GET_PROPERTY/FE_SET_PROPERTY,
+On FE_GET_PROPERTY and 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.
@@ -193,7 +171,7 @@ get/set up to 64 properties. The actual meaning of each property is described on
Central frequency of the channel.Notes:
- 1)For satellital delivery systems, it is measured in kHz.
+ 1)For satellite delivery systems, it is measured in kHz.
For the other ones, it is measured in Hz.2)For ISDB-T, the channels are usually transmitted with an offset of 143kHz.
E.g. a valid frequency could be 474143 kHz. The stepping is bound to the bandwidth of
@@ -205,25 +183,78 @@ get/set up to 64 properties. The actual meaning of each property is described on
<constant>DTV_MODULATION</constant>
-Specifies the frontend modulation type for cable and satellite types. The modulation can be one of the types bellow:
-
- typedef enum fe_modulation {
- QPSK,
- QAM_16,
- QAM_32,
- QAM_64,
- QAM_128,
- QAM_256,
- QAM_AUTO,
- VSB_8,
- VSB_16,
- PSK_8,
- APSK_16,
- APSK_32,
- DQPSK,
- QAM_4_NR,
- } fe_modulation_t;
-
+Specifies the frontend modulation type for delivery systems that supports
+ more than one modulation type. The modulation can be one of the types
+ defined by &fe-modulation;.
+
+
+
+Modulation property
+
+Most of the digital TV standards currently offers more than one possible
+ modulation (sometimes called as "constellation" on some standards). This
+ enum contains the values used by the Kernel. Please note that not all
+ modulations are supported by a given standard.
+
+
+
+
<constant>DTV_BANDWIDTH_HZ</constant>
@@ -253,19 +284,45 @@ get/set up to 64 properties. The actual meaning of each property is described on
<constant>DTV_INVERSION</constant>
- The Inversion field can take one of these values:
-
-
- typedef enum fe_spectral_inversion {
- INVERSION_OFF,
- INVERSION_ON,
- INVERSION_AUTO
- } fe_spectral_inversion_t;
-
- It indicates if spectral inversion should be presumed or not. In the automatic setting
- (INVERSION_AUTO) the hardware will try to figure out the correct setting by
- itself.
-
+
+ Specifies if the frontend should do spectral inversion or not.
+
+
+enum fe_modulation: Frontend spectral inversion
+
+This parameter indicates if spectral inversion should be presumed or not.
+ In the automatic setting (INVERSION_AUTO) the hardware
+ will try to figure out the correct setting by itself. If the hardware
+ doesn't support, the DVB core will try to lock at the carrier first with
+ inversion off. If it fails, it will try to enable inversion.
+
+
+
+ enum fe_modulation
+
+ &cs-def;
+
+
+ ID
+ Description
+
+
+
+
+ INVERSION_OFF
+ Don't do spectral band inversion.
+
+ INVERSION_ON
+ Do spectral band inversion.
+
+ INVERSION_AUTO
+ Autodetect spectral band inversion.
+
+
+
+
+
+
<constant>DTV_DISEQC_MASTER</constant>
@@ -279,25 +336,64 @@ get/set up to 64 properties. The actual meaning of each property is described on
<constant>DTV_INNER_FEC</constant>Used cable/satellite transmissions. The acceptable values are:
-
-typedef enum fe_code_rate {
- FEC_NONE = 0,
- FEC_1_2,
- FEC_2_3,
- FEC_3_4,
- FEC_4_5,
- FEC_5_6,
- FEC_6_7,
- FEC_7_8,
- FEC_8_9,
- FEC_AUTO,
- FEC_3_5,
- FEC_9_10,
- FEC_2_5,
-} fe_code_rate_t;
-
- which correspond to error correction rates of 1/2, 2/3, etc.,
- no error correction or auto detection.
+
+enum fe_code_rate: type of the Forward Error Correction.
+
+
+<constant>DTV_VOLTAGE</constant>
@@ -305,12 +401,31 @@ typedef enum fe_code_rate {
the polarzation (horizontal/vertical). When using DiSEqC epuipment this
voltage has to be switched consistently to the DiSEqC commands as
described in the DiSEqC spec.
-
- typedef enum fe_sec_voltage {
- SEC_VOLTAGE_13,
- SEC_VOLTAGE_18
- } fe_sec_voltage_t;
-
+
+
+ enum fe_sec_voltage
+
+ &cs-def;
+
+
+ ID
+ Description
+
+
+
+
+ SEC_VOLTAGE_13
+ Set DC voltage level to 13V
+
+ SEC_VOLTAGE_18
+ Set DC voltage level to 18V
+
+ SEC_VOLTAGE_OFF
+ Don't send any voltage to the antenna
+
+
+
+
+ enum atscmh_rs_frame_mode
+
+ &cs-def;
+
+
+ ID
+ Description
+
+
+
+
+ ATSCMH_RSFRAME_PRI_ONLY
+ Single Frame: There is only a primary RS Frame for all
+ Group Regions.
+
+ ATSCMH_RSFRAME_PRI_SEC
+ Dual Frame: There are two separate RS Frames: Primary RS
+ Frame for Group Region A and B and Secondary RS Frame for Group
+ Region C and D.
+
+
+
+
+ enum atscmh_scc_block_mode
+
+ &cs-def;
+
+
+ ID
+ Description
+
+
+
+
+ ATSCMH_SCCC_BLK_SEP
+ Separate SCCC: the SCCC outer code mode shall be set independently
+ for each Group Region (A, B, C, D)
+
+ ATSCMH_SCCC_BLK_COMB
+ Combined SCCC: all four Regions shall have the same SCCC outer
+ code mode.
+
+ ATSCMH_SCCC_BLK_RES
+ Reserved. Shouldn't be used.
+
+
+
+
Notes:1) If DTV_GUARD_INTERVAL is set the GUARD_INTERVAL_AUTO the hardware will
@@ -812,26 +1086,64 @@ typedef enum fe_guard_interval {
in the missing parameters.2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present3) DTMB specifies PN420, PN595 and PN945.
+<constant>DTV_TRANSMISSION_MODE</constant>
- Specifies the number of carriers used by the standard
+ Specifies the number of carriers used by the standard.
+ This is used only on OFTM-based standards, e. g.
+ DVB-T/T2, ISDB-T, DTMB
+
+
+enum fe_transmit_mode: Number of carriers per channel
+
+
+ enum fe_transmit_mode
+
+ &cs-def;
+
+
+ ID
+ Description
+
+
+
+
+ TRANSMISSION_MODE_AUTO
+ Autodetect transmission mode. The hardware will try to find
+ the correct FFT-size (if capable) to fill in the missing
+ parameters.
+
+ TRANSMISSION_MODE_1K
+ Transmission mode 1K
+
+ TRANSMISSION_MODE_2K
+ Transmission mode 2K
+
+ TRANSMISSION_MODE_8K
+ Transmission mode 8K
+
+ TRANSMISSION_MODE_4K
+ Transmission mode 4K
+
+ TRANSMISSION_MODE_16K
+ Transmission mode 16K
+
+ TRANSMISSION_MODE_32K
+ Transmission mode 32K
+
+ TRANSMISSION_MODE_C1
+ Single Carrier (C=1) transmission mode (DTMB)
+
+ TRANSMISSION_MODE_C3780
+ Multi Carrier (C=3780) transmission mode (DTMB)
+
+
+
+
+
- Possible values are:
-
-typedef enum fe_transmit_mode {
- TRANSMISSION_MODE_2K,
- TRANSMISSION_MODE_8K,
- TRANSMISSION_MODE_AUTO,
- TRANSMISSION_MODE_4K,
- TRANSMISSION_MODE_1K,
- TRANSMISSION_MODE_16K,
- TRANSMISSION_MODE_32K,
- TRANSMISSION_MODE_C1,
- TRANSMISSION_MODE_C3780,
-} 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
@@ -842,19 +1154,48 @@ typedef enum fe_transmit_mode {
3) DVB-T specifies 2K and 8K as valid sizes.4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.5) DTMB specifies C1 and C3780.
+<constant>DTV_HIERARCHY</constant>Frontend hierarchy
-
-typedef enum fe_hierarchy {
- HIERARCHY_NONE,
- HIERARCHY_1,
- HIERARCHY_2,
- HIERARCHY_4,
- HIERARCHY_AUTO
- } fe_hierarchy_t;
-
+
+
+
+Frontend hierarchy
+
+
+
<constant>DTV_LNA</constant>
@@ -921,7 +1284,7 @@ enum fe_interleaving {
For most delivery systems, dtv_property.stat.len
will be 1 if the stats is supported, and the properties will
return a single value for each parameter.
- It should be noticed, however, that new OFDM delivery systems
+ It should be noted, however, that new OFDM delivery systems
like ISDB can use different modulation types for each group of
carriers. On such standards, up to 3 groups of statistics can be
provided, and dtv_property.stat.len is updated
@@ -940,10 +1303,10 @@ enum fe_interleaving {
and uvalue is for unsigned values (counters, relative scale)scale - Scale for the value. It can be:
- FE_SCALE_NOT_AVAILABLE - The parameter is supported by the frontend, but it was not possible to collect it (could be a transitory or permanent condition)
- FE_SCALE_DECIBEL - parameter is a signed value, measured in 1/1000 dB
- FE_SCALE_RELATIVE - parameter is a unsigned value, where 0 means 0% and 65535 means 100%.
- FE_SCALE_COUNTER - parameter is a unsigned value that counts the occurrence of an event, like bit error, block error, or lapsed time.
+ FE_SCALE_NOT_AVAILABLE - The parameter is supported by the frontend, but it was not possible to collect it (could be a transitory or permanent condition)
+ FE_SCALE_DECIBEL - parameter is a signed value, measured in 1/1000 dB
+ FE_SCALE_RELATIVE - parameter is a unsigned value, where 0 means 0% and 65535 means 100%.
+ FE_SCALE_COUNTER - parameter is a unsigned value that counts the occurrence of an event, like bit error, block error, or lapsed time.
@@ -953,7 +1316,7 @@ enum fe_interleaving {
Possible scales for this metric are:FE_SCALE_NOT_AVAILABLE - it failed to measure it, or the measurement was not complete yet.
- FE_SCALE_DECIBEL - signal strength is in 0.0001 dBm units, power measured in miliwatts. This value is generally negative.
+ FE_SCALE_DECIBEL - signal strength is in 0.001 dBm units, power measured in miliwatts. This value is generally negative.FE_SCALE_RELATIVE - The frontend provides a 0% to 100% measurement for power (actually, 0 to 65535).
@@ -963,7 +1326,7 @@ enum fe_interleaving {
Possible scales for this metric are:FE_SCALE_NOT_AVAILABLE - it failed to measure it, or the measurement was not complete yet.
- FE_SCALE_DECIBEL - Signal/Noise ratio is in 0.0001 dB units.
+ FE_SCALE_DECIBEL - Signal/Noise ratio is in 0.001 dB units.FE_SCALE_RELATIVE - The frontend provides a 0% to 100% measurement for Signal/Noise (actually, 0 to 65535).
@@ -985,7 +1348,7 @@ enum fe_interleaving {
<constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant>Measures the amount of bits received before the inner code block, during the same period as
DTV_STAT_PRE_ERROR_BIT_COUNT measurement was taken.
- It should be noticed that this measurement can be smaller than the total amount of bits on the transport stream,
+ It should be noted that this measurement can be smaller than the total amount of bits on the transport stream,
as the frontend may need to manually restart the measurement, losing some data between each measurement interval.This measurement is monotonically increased, as the frontend gets more bit count measurements.
The frontend may reset it when a channel/transponder is tuned.
@@ -1014,7 +1377,7 @@ enum fe_interleaving {
<constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant>Measures the amount of bits received after the inner coding, during the same period as
DTV_STAT_POST_ERROR_BIT_COUNT measurement was taken.
- It should be noticed that this measurement can be smaller than the total amount of bits on the transport stream,
+ It should be noted that this measurement can be smaller than the total amount of bits on the transport stream,
as the frontend may need to manually restart the measurement, losing some data between each measurement interval.This measurement is monotonically increased, as the frontend gets more bit count measurements.
The frontend may reset it when a channel/transponder is tuned.
@@ -1255,8 +1618,8 @@ enum fe_interleaving {
In addition, the DTV QoS statistics are also valid.
-
- Properties used on satellital delivery systems
+
+ Properties used on satellite delivery systemsDVB-S delivery systemThe following parameters are valid for DVB-S: