From 9569793a79836320c33d400c686dcb78f886bdad Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 6 Jan 2013 12:22:06 -0300 Subject: [media] dvb: Add DVBv5 statistics properties The DVBv3 statistics parameters are limited on several ways: - It doesn't provide any way to indicate the used measure, so userspace need to guess how to calculate/use it; - Only a limited set of stats are supported; - Can't be called in a way to require them to be filled all at once (atomic reads from the hardware), with may cause troubles on interpreting them on userspace; - On some OFDM delivery systems, the carriers can be independently modulated, having different properties. Currently, there's no way to report per-layer stats. To address the above issues, adding a new DVBv5-based stats API. While here, correct inner code nomenclature on a few places. Reviewed-by: Antti Palosaari Signed-off-by: Mauro Carvalho Chehab diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml index 757488b..0197bcc 100644 --- a/Documentation/DocBook/media/dvb/dvbapi.xml +++ b/Documentation/DocBook/media/dvb/dvbapi.xml @@ -84,7 +84,7 @@ Added ISDB-T test originally written by Patrick Boettcher LINUX DVB API -Version 5.8 +Version 5.10 &sub-intro; diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 957e3ac..4a5eaee 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -7,14 +7,41 @@ 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. +
+DTV stats type + +struct dtv_stats { + __u8 scale; /* enum fecap_scale_params type */ + union { + __u64 uvalue; /* for counters and relative scales */ + __s64 svalue; /* for 1/1000 dB measures */ + }; +} __packed; + +
+
+DTV stats type + +#define MAX_DTV_STATS 4 + +struct dtv_fe_stats { + __u8 len; + struct dtv_stats stat[MAX_DTV_STATS]; +} __packed; + +
+
DTV property type /* Reserved fields should be set to 0 */ + struct dtv_property { __u32 cmd; + __u32 reserved[3]; union { __u32 data; + struct dtv_fe_stats st; struct { __u8 data[32]; __u32 len; @@ -440,7 +467,7 @@ typedef enum fe_delivery_system { <constant>DTV-ISDBT-LAYER*</constant> parameters ISDB-T channels can be coded hierarchically. As opposed to DVB-T in ISDB-T hierarchical layers can be decoded simultaneously. For that - reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders. + reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders. ISDB-T has 3 hierarchical layers which each can use a part of the available segments. The total number of segments over all layers has to 13 in ISDB-T. @@ -850,6 +877,147 @@ enum fe_interleaving { use the special macro LNA_AUTO to set LNA auto
+ +
+ Frontend statistics indicators + The values are returned via dtv_property.stat. + If the property is supported, dtv_property.stat.len is bigger than zero. + 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 + 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 + to reflect the "global" metrics, plus one metric per each carrier + group (called "layer" on ISDB). + So, in order to be consistent with other delivery systems, the first + value at dtv_property.stat.dtv_stats + array refers to the global metric. The other elements of the array + represent each layer, starting from layer A(index 1), + layer B (index 2) and so on. + The number of filled elements are stored at dtv_property.stat.len. + Each element of the dtv_property.stat.dtv_stats array consists on two elements: + + svalue or uvalue, where + svalue is for signed values of the measure (dB measures) + 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. + +
+ + +
+ <constant>DTV_STAT_SIGNAL_STRENGTH</constant> + Indicates the signal strength level at the analog part of the tuner or of the demod. + 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_RELATIVE - The frontend provides a 0% to 100% measurement for power (actually, 0 to 65535). + +
+
+ <constant>DTV_STAT_CNR</constant> + Indicates the Signal to Noise ratio for the main carrier. + 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_RELATIVE - The frontend provides a 0% to 100% measurement for Signal/Noise (actually, 0 to 65535). + +
+
+ <constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant> + Measures the number of bit errors before the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code). + This measure is taken during the same interval as DTV_STAT_PRE_TOTAL_BIT_COUNT. + In order to get the BER (Bit Error Rate) measurement, it should be divided by + DTV_STAT_PRE_TOTAL_BIT_COUNT. + This measurement is monotonically increased, as the frontend gets more bit count measurements. + The frontend may reset it when a channel/transponder is tuned. + Possible scales for this metric are: + + FE_SCALE_NOT_AVAILABLE - it failed to measure it, or the measurement was not complete yet. + FE_SCALE_COUNTER - Number of error bits counted before the inner coding. + +
+
+ <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, + as the frontend may need to manually restart the measurement, loosing 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. + Possible scales for this metric are: + + FE_SCALE_NOT_AVAILABLE - it failed to measure it, or the measurement was not complete yet. + FE_SCALE_COUNTER - Number of bits counted while measuring + DTV_STAT_PRE_ERROR_BIT_COUNT. + +
+
+ <constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant> + Measures the number of bit errors after the forward error correction (FEC) done by inner code block (after Viterbi, LDPC or other inner code). + This measure is taken during the same interval as DTV_STAT_POST_TOTAL_BIT_COUNT. + In order to get the BER (Bit Error Rate) measurement, it should be divided by + DTV_STAT_POST_TOTAL_BIT_COUNT. + This measurement is monotonically increased, as the frontend gets more bit count measurements. + The frontend may reset it when a channel/transponder is tuned. + Possible scales for this metric are: + + FE_SCALE_NOT_AVAILABLE - it failed to measure it, or the measurement was not complete yet. + FE_SCALE_COUNTER - Number of error bits counted after the inner coding. + +
+
+ <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, + as the frontend may need to manually restart the measurement, loosing 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. + Possible scales for this metric are: + + FE_SCALE_NOT_AVAILABLE - it failed to measure it, or the measurement was not complete yet. + FE_SCALE_COUNTER - Number of bits counted while measuring + DTV_STAT_POST_ERROR_BIT_COUNT. + +
+
+ <constant>DTV_STAT_ERROR_BLOCK_COUNT</constant> + Measures the number of block errors after the outer forward error correction coding (after Reed-Solomon or other outer code). + This measurement is monotonically increased, as the frontend gets more bit count measurements. + The frontend may reset it when a channel/transponder is tuned. + Possible scales for this metric are: + + FE_SCALE_NOT_AVAILABLE - it failed to measure it, or the measurement was not complete yet. + FE_SCALE_COUNTER - Number of error blocks counted after the outer coding. + +
+
+ <constant>DTV-STAT_TOTAL_BLOCK_COUNT</constant> + Measures the total number of blocks received during the same period as + DTV_STAT_ERROR_BLOCK_COUNT measurement was taken. + It can be used to calculate the PER indicator, by dividing + DTV_STAT_ERROR_BLOCK_COUNT + by DTV-STAT-TOTAL-BLOCK-COUNT. + Possible scales for this metric are: + + FE_SCALE_NOT_AVAILABLE - it failed to measure it, or the measurement was not complete yet. + FE_SCALE_COUNTER - Number of blocks counted while measuring + DTV_STAT_ERROR_BLOCK_COUNT. + +
+
+
Properties used on terrestrial delivery systems
@@ -871,6 +1039,7 @@ enum fe_interleaving { DTV_HIERARCHY DTV_LNA + In addition, the DTV QoS statistics are also valid.
DVB-T2 delivery system @@ -895,6 +1064,7 @@ enum fe_interleaving { DTV_STREAM_ID DTV_LNA + In addition, the DTV QoS statistics are also valid.
ISDB-T delivery system @@ -948,6 +1118,7 @@ enum fe_interleaving { DTV_ISDBT_LAYERC_SEGMENT_COUNT DTV_ISDBT_LAYERC_TIME_INTERLEAVING + In addition, the DTV QoS statistics are also valid.
ATSC delivery system @@ -961,6 +1132,7 @@ enum fe_interleaving { DTV_MODULATION DTV_BANDWIDTH_HZ + In addition, the DTV QoS statistics are also valid.
ATSC-MH delivery system @@ -988,6 +1160,7 @@ enum fe_interleaving { DTV_ATSCMH_SCCC_CODE_MODE_C DTV_ATSCMH_SCCC_CODE_MODE_D + In addition, the DTV QoS statistics are also valid.
DTMB delivery system @@ -1007,6 +1180,7 @@ enum fe_interleaving { DTV_INTERLEAVING DTV_LNA + In addition, the DTV QoS statistics are also valid.
@@ -1028,6 +1202,7 @@ enum fe_interleaving { DTV_INNER_FEC DTV_LNA + In addition, the DTV QoS statistics are also valid.
DVB-C Annex B delivery system @@ -1043,6 +1218,7 @@ enum fe_interleaving { DTV_INVERSION DTV_LNA + In addition, the DTV QoS statistics are also valid.
@@ -1062,6 +1238,7 @@ enum fe_interleaving { DTV_VOLTAGE DTV_TONE + In addition, the DTV QoS statistics are also valid. Future implementations might add those two missing parameters: DTV_DISEQC_MASTER @@ -1077,6 +1254,7 @@ enum fe_interleaving { DTV_ROLLOFF DTV_STREAM_ID + In addition, the DTV QoS statistics are also valid.
Turbo code delivery system diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml index 426c252..df39ba3 100644 --- a/Documentation/DocBook/media/dvb/frontend.xml +++ b/Documentation/DocBook/media/dvb/frontend.xml @@ -230,7 +230,7 @@ typedef enum fe_status { The frontend has found a DVB signal FE_HAS_VITERBI -The frontend FEC code is stable +The frontend FEC inner coding (Viterbi, LDPC or other inner code) is stable FE_HAS_SYNC Syncronization bytes was found diff --git a/include/uapi/linux/dvb/frontend.h b/include/uapi/linux/dvb/frontend.h index c12d452..c56d77c 100644 --- a/include/uapi/linux/dvb/frontend.h +++ b/include/uapi/linux/dvb/frontend.h @@ -365,7 +365,17 @@ struct dvb_frontend_event { #define DTV_INTERLEAVING 60 #define DTV_LNA 61 -#define DTV_MAX_COMMAND DTV_LNA +/* Quality parameters */ +#define DTV_STAT_SIGNAL_STRENGTH 62 +#define DTV_STAT_CNR 63 +#define DTV_STAT_PRE_ERROR_BIT_COUNT 64 +#define DTV_STAT_PRE_TOTAL_BIT_COUNT 65 +#define DTV_STAT_POST_ERROR_BIT_COUNT 66 +#define DTV_STAT_POST_TOTAL_BIT_COUNT 67 +#define DTV_STAT_ERROR_BLOCK_COUNT 68 +#define DTV_STAT_TOTAL_BLOCK_COUNT 69 + +#define DTV_MAX_COMMAND DTV_STAT_TOTAL_BLOCK_COUNT typedef enum fe_pilot { PILOT_ON, @@ -452,11 +462,78 @@ struct dtv_cmds_h { __u32 reserved:30; /* Align */ }; +/** + * Scale types for the quality parameters. + * @FE_SCALE_NOT_AVAILABLE: That QoS measure is not available. That + * could indicate a temporary or a permanent + * condition. + * @FE_SCALE_DECIBEL: The scale is measured in 0.0001 dB steps, typically + * used on signal measures. + * @FE_SCALE_RELATIVE: The scale is a relative percentual measure, + * ranging from 0 (0%) to 0xffff (100%). + * @FE_SCALE_COUNTER: The scale counts the occurrence of an event, like + * bit error, block error, lapsed time. + */ +enum fecap_scale_params { + FE_SCALE_NOT_AVAILABLE = 0, + FE_SCALE_DECIBEL, + FE_SCALE_RELATIVE, + FE_SCALE_COUNTER +}; + +/** + * struct dtv_stats - Used for reading a DTV status property + * + * @value: value of the measure. Should range from 0 to 0xffff; + * @scale: Filled with enum fecap_scale_params - the scale + * in usage for that parameter + * + * For most delivery systems, this will return a single value for each + * parameter. + * It should be noticed, however, that new OFDM delivery systems like + * ISDB can use different modulation types for each group of carriers. + * On such standards, up to 8 groups of statistics can be provided, one + * for each carrier group (called "layer" on ISDB). + * In order to be consistent with other delivery systems, the first + * value refers to the entire set of carriers ("global"). + * dtv_status:scale should use the value FE_SCALE_NOT_AVAILABLE when + * the value for the entire group of carriers or from one specific layer + * is not provided by the hardware. + * st.len should be filled with the latest filled status + 1. + * + * In other words, for ISDB, those values should be filled like: + * u.st.stat.svalue[0] = global statistics; + * u.st.stat.scale[0] = FE_SCALE_DECIBELS; + * u.st.stat.value[1] = layer A statistics; + * u.st.stat.scale[1] = FE_SCALE_NOT_AVAILABLE (if not available); + * u.st.stat.svalue[2] = layer B statistics; + * u.st.stat.scale[2] = FE_SCALE_DECIBELS; + * u.st.stat.svalue[3] = layer C statistics; + * u.st.stat.scale[3] = FE_SCALE_DECIBELS; + * u.st.len = 4; + */ +struct dtv_stats { + __u8 scale; /* enum fecap_scale_params type */ + union { + __u64 uvalue; /* for counters and relative scales */ + __s64 svalue; /* for 0.0001 dB measures */ + }; +} __attribute__ ((packed)); + + +#define MAX_DTV_STATS 4 + +struct dtv_fe_stats { + __u8 len; + struct dtv_stats stat[MAX_DTV_STATS]; +} __attribute__ ((packed)); + struct dtv_property { __u32 cmd; __u32 reserved[3]; union { __u32 data; + struct dtv_fe_stats st; struct { __u8 data[32]; __u32 len; diff --git a/include/uapi/linux/dvb/version.h b/include/uapi/linux/dvb/version.h index 827cce7..e53e2ad 100644 --- a/include/uapi/linux/dvb/version.h +++ b/include/uapi/linux/dvb/version.h @@ -24,6 +24,6 @@ #define _DVBVERSION_H_ #define DVB_API_VERSION 5 -#define DVB_API_VERSION_MINOR 9 +#define DVB_API_VERSION_MINOR 10 #endif /*_DVBVERSION_H_*/ -- cgit v0.10.2