From patchwork Mon Jan 7 18:44:14 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 1942071 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork2.kernel.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by patchwork2.kernel.org (Postfix) with ESMTP id 127DFDF230 for ; Mon, 7 Jan 2013 18:44:56 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754976Ab3AGSow (ORCPT ); Mon, 7 Jan 2013 13:44:52 -0500 Received: from mx1.redhat.com ([209.132.183.28]:45248 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754962Ab3AGSou (ORCPT ); Mon, 7 Jan 2013 13:44:50 -0500 Received: from int-mx12.intmail.prod.int.phx2.redhat.com (int-mx12.intmail.prod.int.phx2.redhat.com [10.5.11.25]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id r07Iin7x030715 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 7 Jan 2013 13:44:49 -0500 Received: from pedra (vpn1-7-20.gru2.redhat.com [10.97.7.20]) by int-mx12.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id r07Iil9T004724 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 7 Jan 2013 13:44:49 -0500 Received: from v4l by pedra with local (Exim 4.76) (envelope-from ) id 1TsHgH-0001iq-Vr; Mon, 07 Jan 2013 16:44:18 -0200 From: Mauro Carvalho Chehab Cc: Mauro Carvalho Chehab , Linux Media Mailing List Subject: [PATCH RFCv8 1/2] dvb: Add DVBv5 stats properties for Quality of Service Date: Mon, 7 Jan 2013 16:44:14 -0200 Message-Id: <1357584255-6500-1-git-send-email-mchehab@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.25 To: unlisted-recipients:; (no To-header on input) Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org The DVBv3 quality parameters are limited on several ways: - Doesn't provide any way to indicate the used measure, so userspace need to guess how to calculate the measure; - 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. Signed-off-by: Mauro Carvalho Chehab --- v6: Add DocBook documentation. v7: Some fixes as suggested by Antti V8: Documentation fix, compilation fix and name the stats struct, for its reusage inside the core TODO: - Add a driver implementation. --- Documentation/DocBook/media/dvb/dvbproperty.xml | 97 ++++++++++++++++++++++++- include/uapi/linux/dvb/frontend.h | 83 ++++++++++++++++++++- 2 files changed, 177 insertions(+), 3 deletions(-) diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 957e3ac..9168808 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -7,16 +7,29 @@ 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 { + __u16 value; + __u8 scale; +} __attribute__ ((packed)); + +
DTV property type /* Reserved fields should be set to 0 */ + struct dtv_property { __u32 cmd; union { __u32 data; struct { - __u8 data[32]; + union { + __u8 data[32]; + __u16 data[16]; + } __u32 len; __u32 reserved1[3]; void *reserved2; @@ -850,6 +863,78 @@ enum fe_interleaving { use the special macro LNA_AUTO to set LNA auto
+ +
+ Frontend Quality of Service/Statistics indicators + Except for DTV_QOS_ENUM, + the values are returned via dtv_property.stat. + 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 3 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 at dtv_property.stat.dtv_stats array refers to + a global indicator, if any. 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: + + value - Value of the measure + scale - Scale for the value. It can be: +
+ + FE_SCALE_NOT_AVAILABLE - If it is not possible to collect a given parameter (could be a transitory or permanent condition) + FE_SCALE_DECIBEL - parameter is a signed value, measured in 0.1 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_QOS_ENUM</constant> + A frontend needs to advertise the statistics it provides. This property allows to enumerate all + DTV QoS statistics that are + supported by a given frontend. + + dtv_property.len indicates the number of supported + DTV QoS statistics. + dtv_property.data16 is an 16 bits array of the supported properties. +
+
+ <constant>DTV_QOS_SIGNAL_STRENGTH</constant> + Indicates the signal strength level at the analog part of the tuner. +
+
+ <constant>DTV_QOS_CNR</constant> + Indicates the signal to noise relation for the main carrier. + +
+
+ <constant>DTV_QOS_BIT_ERROR_COUNT</constant> + Measures the number of bit errors since the last counter reset. + In order to get the BER (Bit Error Rate) measurement, it should be divided by + DTV_QOS_TOTAL_BITS_COUNT. +
+
+ <constant>DTV_QOS_TOTAL_BITS_COUNT</constant> + Measures the amount of bits received since the last DTV_QOS_BIT_ERROR_COUNT reset. +
+
+ <constant>DTV_QOS_ERROR_BLOCK_COUNT</constant> + Measures the number of block errors since the last counter reset. +
+
+ <constant>DTV-QOS_TOTAL_BLOCKS_COUNT</constant> + Measures the total number of blocks since the last + DTV_QOS_ERROR_BLOCK_COUNT reset. + It can be used to calculate the PER indicator, by dividing + DTV_QOS_ERROR_BLOCK_COUNT + by DTV-QOS-TOTAL-BLOCKS-COUNT. +
+
+
Properties used on terrestrial delivery systems
@@ -871,6 +956,7 @@ enum fe_interleaving { DTV_HIERARCHY DTV_LNA + In addition, the DTV QoS statistics are also valid.
DVB-T2 delivery system @@ -895,6 +981,7 @@ enum fe_interleaving { DTV_STREAM_ID DTV_LNA + In addition, the DTV QoS statistics are also valid.
ISDB-T delivery system @@ -948,6 +1035,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 +1049,7 @@ enum fe_interleaving { DTV_MODULATION DTV_BANDWIDTH_HZ + In addition, the DTV QoS statistics are also valid.
ATSC-MH delivery system @@ -988,6 +1077,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 +1097,7 @@ enum fe_interleaving { DTV_INTERLEAVING DTV_LNA + In addition, the DTV QoS statistics are also valid.
@@ -1028,6 +1119,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 +1135,7 @@ enum fe_interleaving { DTV_INVERSION DTV_LNA + In addition, the DTV QoS statistics are also valid.
@@ -1062,6 +1155,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 +1171,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/include/uapi/linux/dvb/frontend.h b/include/uapi/linux/dvb/frontend.h index c12d452..437c440 100644 --- a/include/uapi/linux/dvb/frontend.h +++ b/include/uapi/linux/dvb/frontend.h @@ -365,7 +365,16 @@ struct dvb_frontend_event { #define DTV_INTERLEAVING 60 #define DTV_LNA 61 -#define DTV_MAX_COMMAND DTV_LNA +/* Quality parameters */ +#define DTV_QOS_ENUM 62 +#define DTV_QOS_SIGNAL_STRENGTH 63 +#define DTV_QOS_CNR 64 +#define DTV_QOS_BIT_ERROR_COUNT 65 +#define DTV_QOS_TOTAL_BITS_COUNT 66 +#define DTV_QOS_ERROR_BLOCK_COUNT 67 +#define DTV_QOS_TOTAL_BLOCKS_COUNT 68 + +#define DTV_MAX_COMMAND DTV_QOS_TOTAL_BLOCKS_COUNT typedef enum fe_pilot { PILOT_ON, @@ -452,13 +461,83 @@ 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.1 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, + 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 { + __u16 uvalue; /* for counters and relative scales */ + __s16 svalue; /* for 0.1 dB measures */ + }; +} __attribute__ ((packed)); + + +#define MAX_QOS_STATS 4 + +struct dtv_fe_stats { + __u8 len; + struct dtv_stats stat[MAX_QOS_STATS]; +} __attribute__ ((packed)); + struct dtv_property { __u32 cmd; __u32 reserved[3]; union { __u32 data; + struct dtv_fe_stats st; struct { - __u8 data[32]; + union { + __u8 data[32]; + __u16 data16[16]; + }; __u32 len; __u32 reserved1[3]; void *reserved2;