From patchwork Sun Feb 21 21:51:07 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hugo Mills X-Patchwork-Id: 81064 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by demeter.kernel.org (8.14.3/8.14.3) with ESMTP id o1LLvf91006316 for ; Sun, 21 Feb 2010 21:57:41 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753694Ab0BUV5c (ORCPT ); Sun, 21 Feb 2010 16:57:32 -0500 Received: from frost.carfax.org.uk ([212.13.194.111]:1281 "EHLO frost.carfax.org.uk" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753493Ab0BUVvN (ORCPT ); Sun, 21 Feb 2010 16:51:13 -0500 Received: from intmx.carfax.org.uk ([10.0.0.5] helo=vlad.carfax.org.uk ident=Debian-exim) by frost.carfax.org.uk with esmtp (Exim 4.69) (envelope-from ) id 1NjJhl-0001Vf-VR; Sun, 21 Feb 2010 21:51:12 +0000 Received: from selene.carfax.org.uk ([10.0.0.7]) by vlad.carfax.org.uk with smtp (Exim 4.69) (envelope-from ) id 1NjJhj-0002bU-Rm; Sun, 21 Feb 2010 21:51:08 +0000 Received: by selene.carfax.org.uk (sSMTP sendmail emulation); Sun, 21 Feb 2010 21:51:07 +0000 Date: Sun, 21 Feb 2010 21:51:07 +0000 From: Hugo Mills To: Andy Walls Cc: linux-media@vger.kernel.org Subject: [RFC] DVB API v5 Documentation (was: Re: Documentation questions) Message-ID: <20100221215107.GA2247@selene> References: <20100218211224.GA7879@selene> <1266538767.3248.14.camel@palomino.walls.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <1266538767.3248.14.camel@palomino.walls.org> X-GPG-Fingerprint: 8C59 86C7 81F3 93FE BB02 DDB1 20AC B3BE 515C 238D X-GPG-Key: 515C238D X-Parrot: It is no more. It has joined the choir invisible. X-IRC-Nicks: darksatanic darkersatanic darkling darkthing User-Agent: Mutt/1.5.20 (2009-06-14) X-frost.carfax.org.uk-Spam-Score: -101.9 (---------------------------------------------------) X-frost.carfax.org.uk-Spam-Report: Spam detection software, running on the system "spamd0.lon.bitfolk.com", has identified this incoming email as possible spam. The original message has been attached to this so you can view it (if it isn't spam) or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: On Thu, Feb 18, 2010 at 07:19:27PM -0500, Andy Walls wrote: > On Thu, 2010-02-18 at 21:12 +0000, Hugo Mills wrote: > > (Please cc: me, I'm not subscribed yet) > > > > After struggling to work out how stuff worked from the existing DVB > > API docs(+), I'm currently attempting to improve the API > > documentation, to cover the v5 API, and I've got a few questions: > > > > * Is anyone else working on docs right now? (i.e. am I wasting my time?) > > About a year ago, I stated I was going to add the DVB API v5 additions. > Well, you see how far that has gotten: nowhere. :P > > So please, your are welcome to help. [...] Content analysis details: (-101.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -100 SHORTCIRCUIT Not all rules were run, due to a shortcircuited rule [score: 0.0000] -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Greylist: IP, sender and recipient auto-whitelisted, not delayed by milter-greylist-4.2.3 (demeter.kernel.org [140.211.167.41]); Sun, 21 Feb 2010 21:57:42 +0000 (UTC) Index: linux-2.6/Documentation/DocBook/dvb/frontend.xml =================================================================== --- linux-2.6.orig/Documentation/DocBook/dvb/frontend.xml 2010-02-17 13:54:28.000000000 +0000 +++ linux-2.6/Documentation/DocBook/dvb/frontend.xml 2010-02-21 21:40:27.000000000 +0000 @@ -6,19 +6,34 @@ ioctl definitions can be accessed by including linux/dvb/frontend.h in your application. -DVB frontends come in three varieties: DVB-S (satellite), DVB-C -(cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP) -is not yet handled by this API but a future extension is possible. For -DVB-S the frontend device also supports satellite equipment control -(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) -specification is available from -Eutelsat. +DVB frontends come in a large number of varieties (most with few +drivers). The most common three are DVB-S (satellite), DVB-C (cable) +and DVB-T (terrestrial). Transmission via the internet (DVB-IP) is not +yet handled by this API but a future extension is possible. For DVB-S +the frontend device also supports satellite equipment control (SEC) +via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) specification +is available from Eutelsat. Note that the DVB API may also be used for MPEG decoder-only PCI cards, in which case there exists no frontend device. +There are two main ways of interacting with a frontend device: +the v3 API, which comprises a set of 18 ioctls and which supports only +DVB-T, DVB-C and DVB-S, and the v5 API (previously known as S2API), +which is only two ioctls, and can support any type of frontend device. +These two APIs may be mixed if necessary. There are some operations +which are only possible in one API or the other, but the v5 API is +rapidly gaining the full feature set of the v3 API. It is recommended +that the v5 API is used for new applications. +
-Frontend Data Types +Frontend Enumeration Types + +There are many parameters for tuning and controlling frontend +devices. Most of these parameters fall into a small range of +possibilities, and have enumerated types defined for them in the DVB +API. These are listed below.
frontend type @@ -64,59 +79,17 @@ FE_CAN_BANDWIDTH_AUTO = 0x40000, FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, FE_CAN_HIERARCHY_AUTO = 0x100000, - FE_CAN_MUTE_TS = 0x80000000, - FE_CAN_CLEAN_SETUP = 0x40000000 + FE_CAN_8VSB = 0x200000, + FE_CAN_16VSB = 0x400000, + FE_HAS_EXTENDED_CAPS = 0x800000, /* We need more bitspace for newer APIs, indicate this. */ + FE_CAN_2G_MODULATION = 0x10000000, /* frontend supports "2nd generation modulation" (DVB-S2) */ + FE_NEEDS_BENDING = 0x20000000, /* not supported anymore, don't use (frontend requires frequency bending) */ + FE_CAN_RECOVER = 0x40000000, /* frontend can recover from a cable unplug automatically */ + FE_CAN_MUTE_TS = 0x80000000 } fe_caps_t;
-
-frontend information - -Information about the frontend ca be queried with - FE_GET_INFO. - - - struct dvb_frontend_info { - char name[128]; - fe_type_t type; - uint32_t frequency_min; - uint32_t frequency_max; - uint32_t frequency_stepsize; - uint32_t frequency_tolerance; - uint32_t symbol_rate_min; - uint32_t symbol_rate_max; - uint32_t symbol_rate_tolerance; /⋆ ppm ⋆/ - uint32_t notifier_delay; /⋆ ms ⋆/ - fe_caps_t caps; - }; - -
- -
-diseqc master command - -A message sent from the frontend to DiSEqC capable equipment. - - struct dvb_diseqc_master_cmd { - uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ - uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ - }; - -
-
-diseqc slave reply - -A reply to the frontend from DiSEqC 2.0 capable equipment. - - struct dvb_diseqc_slave_reply { - uint8_t msg [4]; /⋆ { framing, data [3] } ⋆/ - uint8_t msg_len; /⋆ valid values are 0...4, 0 means no msg ⋆/ - int timeout; /⋆ return from ioctl after timeout ms with ⋆/ - }; /⋆ errorcode when no message was received ⋆/ - -
-
diseqc slave reply The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation @@ -125,7 +98,8 @@ typedef enum fe_sec_voltage { SEC_VOLTAGE_13, - SEC_VOLTAGE_18 + SEC_VOLTAGE_18, + SEC_VOLTAGE_OFF } fe_sec_voltage_t;
@@ -164,8 +138,9 @@
frontend status -Several functions of the frontend device use the fe_status data type defined -by +Several functions of the frontend device use the fe_status data +type defined below to indicate the current state and/or state changes +of the frontend hardware. typedef enum fe_status { FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/ @@ -175,66 +150,16 @@ FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/ FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/ FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/ - } fe_status_t; /⋆ application is recommned to reset ⋆/ + } fe_status_t; /⋆ application is recommned to reset DiSEqC, tone and parameters ⋆/ -to indicate the current state and/or state changes of the frontend hardware. - -
-
-frontend parameters -The kind of parameters passed to the frontend device for tuning depend on -the kind of hardware you are using. All kinds of parameters are combined as an -union in the FrontendParameters structure: - - struct dvb_frontend_parameters { - uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ - /⋆ intermediate frequency in kHz for QPSK ⋆/ - fe_spectral_inversion_t inversion; - union { - struct dvb_qpsk_parameters qpsk; - struct dvb_qam_parameters qam; - struct dvb_ofdm_parameters ofdm; - } u; - }; - -For satellite QPSK frontends you have to use the QPSKParameters member defined by - - struct dvb_qpsk_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ - }; - -for cable QAM frontend you use the QAMParameters structure - - struct dvb_qam_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ - fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ - }; - -DVB-T frontends are supported by the OFDMParamters structure - - - struct dvb_ofdm_parameters { - fe_bandwidth_t bandwidth; - fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ - fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ - fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ - fe_transmit_mode_t transmission_mode; - fe_guard_interval_t guard_interval; - fe_hierarchy_t hierarchy_information; - }; - -In the case of QPSK frontends the Frequency field specifies the intermediate -frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of -the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and -OFDM frontends the Frequency specifies the absolute frequency and is given in -Hz. - -The Inversion field can take one of these values: - +
+inversion setting +Defines the spectral inversion. Used in tuning operations. 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. typedef enum fe_spectral_inversion { INVERSION_OFF, @@ -242,11 +167,11 @@ 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. - -The possible values for the FEC_inner field are +
+ +
+forward error correction +Possible values for forward error correction types are defined in the enum below. These correspond to error correction rates of 1/2, 2/3, etc., no error correction or autometic detection. typedef enum fe_code_rate { @@ -259,35 +184,51 @@ FEC_6_7, FEC_7_8, FEC_8_9, - FEC_AUTO + FEC_AUTO, + FEC_3_5, + FEC_9_10 } fe_code_rate_t; -which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto -detection. - -For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature -modulation mode which can be one of the following: - +
+ +
+quadrature modulation mode +For cable and terrestrial frontends (QAM and OFDM) one also has +to specify the quadrature modulation mode which can be one of the +following: typedef enum fe_modulation { - QPSK, + QPSK, QAM_16, QAM_32, QAM_64, QAM_128, QAM_256, - QAM_AUTO + QAM_AUTO, + VSB_8, + VSB_16, + PSK_8, + APSK_16, + APSK_32, + DQPSK, } fe_modulation_t; -Finally, there are several more parameters for OFDM: - +
+ +
+transmission mode typedef enum fe_transmit_mode { TRANSMISSION_MODE_2K, TRANSMISSION_MODE_8K, - TRANSMISSION_MODE_AUTO + TRANSMISSION_MODE_AUTO, + TRANSMISSION_MODE_4K, } fe_transmit_mode_t; +
+ +
+bandwidth typedef enum fe_bandwidth { BANDWIDTH_8_MHZ, @@ -296,6 +237,10 @@ BANDWIDTH_AUTO } fe_bandwidth_t; +
+ +
+guard interval typedef enum fe_guard_interval { GUARD_INTERVAL_1_32, @@ -305,6 +250,10 @@ GUARD_INTERVAL_AUTO } fe_guard_interval_t; +
+ +
+hierarchy typedef enum fe_hierarchy { HIERARCHY_NONE, @@ -314,49 +263,169 @@ HIERARCHY_AUTO } fe_hierarchy_t; +
+
+pilot + +typedef enum fe_pilot { + PILOT_ON, + PILOT_OFF, + PILOT_AUTO, +} fe_pilot_t; +
-
-frontend events - - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; +
+rolloff + +typedef enum fe_rolloff { + ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */ + ROLLOFF_20, + ROLLOFF_25, + ROLLOFF_AUTO, +} fe_rolloff_t; + +
+ +
+delivery system + +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; -
+
-
-Frontend Function Calls +
+Frontend Function Calls (v5) +
+Using the version 5 API + +In using version 5 of the Linux DVB API to access DVB frontend +devices, almost all of the version 3 API can be discarded. Instead, +the API is reduced to four functions: + + +open() a frontend device node (either in read-only or read-write mode) + + +close() an open frontend device + + +get a list of parameters from the device, using the FE_GET_PROPERTY ioctl + + +set a list of parameters on the device, using the FE_SET_PROPERTY ioctl + + + +The two ioctls from the v5 API manipulate the internal state of +the device using a sequence of simple tag/data +instructions. Almost all of these tagged +instructions simply read or write a single internal +value. There are four special instructions, DTV_TUNE, DTV_CLEAR, +DTV_VOLTAGE and DTV_TONE, which cause the frontend to perform specific +actions. Use of the FE_GET_PROPERTY and FE_SET_PROPERTY ioctls is +described below. + +All aspects and features of the old version 3 API can be +accessed using the version 5 API, with the exception of the properties +returned from the FE_GET_INFO ioctl, and the DiSEqC control for +satellite receivers. In addition, there are many features of the +version 5 API which are not available in the version 3 API. For +example, all of the ISDB-T-specific properties are available through +the v5 API only. + +
+ +
+Properties structure +This structure is passed to both FE_GET_PROPERTY and +FE_SET_PROPERTY, and simply contains an array of properties to get/set +and a count of how many properties there are. + +struct dtv_properties { + __u32 num; + struct dtv_property *props; +}; + +
-
+
+Single property structure +This structure contains a property +tag (cmd), and a data value +(u.data). At present, all of the data values used in the +v5 API are 32 bit numbers, and so u.buffer is +unused. + +struct dtv_property { + __u32 cmd; + __u32 reserved[3]; + union { + __u32 data; + struct { + __u8 data[32]; + __u32 len; + __u32 reserved1[3]; + void *reserved2; + } buffer; + } u; + int result; +} __attribute__ ((packed)); + +
+ +
open() DESCRIPTION -This system call opens a named frontend device (/dev/dvb/adapter0/frontend0) - for subsequent use. Usually the first thing to do after a successful open is to - find out the frontend type with FE_GET_INFO. -The device can be opened in read-only mode, which only allows monitoring of - device status and statistics, or read/write mode, which allows any kind of use - (e.g. performing tuning operations.) - -In a system with multiple front-ends, it is usually the case that multiple devices - cannot be open in read/write mode simultaneously. As long as a front-end - device is opened in read/write mode, other open() calls in read/write mode will - either fail or block, depending on whether non-blocking or blocking mode was - specified. A front-end device opened in blocking mode can later be put into - non-blocking mode (and vice versa) using the F_SETFL command of the fcntl - system call. This is a standard system call, documented in the Linux manual - page for fcntl. When an open() call has succeeded, the device will be ready - for use in the specified mode. This implies that the corresponding hardware is - powered up, and that other front-ends may have been powered down to make - that possible. - - + +This system call opens a named frontend device +(/dev/dvb/adapter0/frontend0) for subsequent use. + +The device can be opened in read-only mode, which only allows +monitoring of device status and statistics, or read/write mode, which +allows any kind of use (e.g. performing tuning operations). + +In a system with multiple front-ends on the same card, it is +usually the case that multiple devices cannot be open in read/write +mode simultaneously. As long as a front-end device is opened in +read/write mode, other open() calls in read/write mode will either +fail or block, depending on whether non-blocking or blocking mode was +specified. A front-end device opened in blocking mode can later be put +into non-blocking mode (and vice versa) using the F_SETFL command of +the fcntl system call. This is a standard system call, documented in +the Linux manual page for fcntl. When an open() call has succeeded, +the device will be ready for use in the specified mode. This implies +that the corresponding hardware is powered up, and that other +front-ends may have been powered down to make that possible. + + + + + + SYNOPSIS -O_NONBLOCK open in non-blocking mode - - - -(blocking mode is the default) +O_NONBLOCK open in non-blocking mode (blocking mode is the default) ERRORS @@ -479,6 +542,1153 @@
+
+FE_GET_PROPERTY +DESCRIPTION + + + +This ioctl call returns status information about the front-end. +This call only requires read-only access to the device. The data +passed to this ioctl is a counted list of dtv_property structures. The +properties are scanned in sequence, and the value of each property is +written into the dtv_property structure. The valid property names are +given in the table below. +Currently, all properties are a single 32-bit value, and are thus +returned in the dtv_property.u.data element of the +property. + + + +SYNOPSIS + + +int ioctl(int fd, int request = FE_GET_PROPERTY, dtv_properties + ⋆properties); + + +PARAMETERS + + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_GET_PROPERTY for this command. + + +struct dtv_properties *properties + +Pointer to the dtv_properties structure containing a list of +properties to return. The property values are written into the same +list when the function returns. + + +ERRORS + + +EBADF + +fd is not a valid open file descriptor. + + +EFAULT + +properties points to invalid address. + + +
+ +
+FE_SET_PROPERTY +DESCRIPTION + + + +This ioctl call sets properties on the frontend device. This +call requires read-write access to the device. The data passed to this +ioctl is a counted list of dtv_property structures. The properties are +scanned in sequence, and the value of each property is set on the +device. The valid property names are given in the tables below. +Currently, all properties are single 32-bit values, and should thus be +set in the dtv_property.u.data element of the property. +Writing to the DTV_TUNE, DTV_CLEAR, DTV_VOLTAGE and DTV_TONE +properties has side-effects (documented separately, below). + + + + +SYNOPSIS + + +int ioctl(int fd, int request = FE_SET_PROPERTY, + dtv_properties ⋆properties); + + +PARAMETERS + + + +int fd + +File descriptor returned by a previous call to open(). + + +int request + +Equals FE_SET_PROPERTY for this command. + + +struct dtv_properties *properties + +Pointer to the dtv_properties structure containing a list of +properties to set. + + +ERRORS + + +EBADF + +fd is not a valid open file descriptor. + + +EFAULT + +properties points to invalid address. + + +
+ +
+List of properties +The valid properties for the v5 API are listed below. Unless otherwise specified, properties are both readable and writable. + +Semantics of v5 API properties. + + +Name + +Size/type + +Description + + + + + +DTV_API_VERSION + +u32 + +Read-only. Return the API version. Major version is encoded in bits 8-15, minor version in bits 0-7. + + + +DTV_FE_CAPABILITY_COUNT + + +Not implemented. + + + +DTV_FE_CAPABILITY + + +Not implemented. + + + +DTV_DELIVERY_SYSTEM + +u32 + +Read the type of delivery system. Values are defined in fe_delivery_system_t. It is not clear what the effect of writing this property is. + + + +DTV_TUNE + +No value + +Write-only. Set this property to force the frontend device to retune +to its current settings. + + + +DTV_CLEAR + +No value + +Write-only. Set this property to clear the driver's settings and return +them to a default state. + + + +DTV_FREQUENCY + +u32 + +The tuning frequency. Exact interpretation is dependent on the +frontend type. For QPSK (DVB-S), this is the intermediate frequency +in kHz. For other frontend tuners, this parameter is the absolute +frequency in Hz. + + + +DTV_MODULATION + +u32 + +Quadrature modulation type. Use values from fe_modulation_t. + + + +DTV_BANDWIDTH_HZ + +u32 + +The bandwidth of the service, in Hz (note: not an enumerated type) + + + +DTV_INVERSION + +u32 + +The spectral inversion setting. Use values from fe_spectral_inversion_t. + + + +DTV_SYMBOL_RATE + +u32 + +The symbol rate setting, in symbols per second. + + + +DTV_INNER_FEC + +u32 + +The Inner FEC setting. Use values from fe_code_rate_t. + + + +DTV_DISEQC_MASTER + +u32 + +??? + + + +DTV_DISEQC_SLAVE_REPLY + +u32 + +??? + + + +DTV_VOLTAGE + +u32 + +Set higher voltage (18V instead of 13V) for long cable runs. Setting +this parameter takes effect immediately. Use values from fe_sec_voltage_t. + + + +DTV_TONE + +u32 + +Enable/disable the constant 22kHz tone for DiSEqC control. Use values +from fe_sec_tone_mode_t. + + + +DTV_PILOT + +u32 + +??? Use values from fe_pilot_t. + + + +DTV_ROLLOFF + +u32 + +Set rolloff value. Use values from fe_rolloff_t. + + + +DTV_CODE_RATE_HP + +u32 + +Code rate for high priority streams. Use values from fe_code_rate_t. + + + +DTV_CODE_RATE_LP + +u32 + +Code rate for low priority streams. Use values from fe_code_rate_t. + + + +DTV_GUARD_INTERVAL + +u32 + +Guard interval setting. Use values from fe_guard_interval_t. + + + +DTV_TRANSMISSION_MODE + +u32 + +Transmission mode setting. Use values from fe_transmit_mode_t. + + + +DTV_HIERARCHY + +u32 + +Hierarchy setting. Use values from fe_hierarchy_t. + + + +DTV_ISDBT_PARTIAL_RECEPTION + +u32 + +Defines whether the channel is in partial reception mode: 0 (false), 1 (true) or -1 (auto). See ISDB-T for more details. + + + +DTV_ISDBT_SOUND_BROADCASTING + +u32 + +Defines whether the channel is ISDB-T or ISDB-Tsb (sound broadcasting). 0 (false), 1 (true) or -1 (auto). See ISDB-T for more details. + + + +DTV_ISDBT_SB_SUBCHANNEL_ID + +u32 + +Sound broadcasting subchannel ID. Applies only for ISDB-Tsb +(i.e. DTV_ISDBT_SOUND_BROADCASTING == 1). See ISDB-T +for more details. + + + +DTV_ISDBT_SB_SEGMENT_COUNT + +u32 + +Sound broadcasting segment count. Applies only for ISDB-Tsb. See ISDB-T for more details. + + + +DTV_ISDBT_SB_SEGMENT_IDX + +u32 + +Sound broadcasting segment index. Applies only for ISDB-Tsb. See ISDB-T for more details. + + + +DTV_ISDBT_LAYER_ENABLED + +u32 + +Hierarchical decoding mode. Set bit 0 to enable layer A, bit 1 to +enable layer B, and bit 2 to enable layer C. All other bits should be +zero. See ISDB-T for more details. + + + +DTV_ISDBT_LAYERx_FEC + +u32 + +FEC setting for a specific layer. x is one +of A, B, or C. Use values from fe_code_rate_t. See ISDB-T for more details. + + + +DTV_ISDBT_LAYERx_MODULATION + +u32 + +Modulation setting for a specific layer. x +is one of A, B, or C. Use values from fe_modulation_t. See ISDB-T for more details. + + + +DTV_ISDBT_LAYERx_SEGMENT_COUNT + +u32 + +Number of segments for a specific layer. x +is one of A, B, or C. Values in range 0-13, or -1 for auto. See ISDB-T for more details. + + + +DTV_ISDBT_LAYERx_TIME_INTERLEAVING + +u32 + +Interleaving setting. x is one of A, B, or +C. Values 0-3, or -1 for auto. Meanings of the values are dependent on +the mode (FFT size). See ISDB-T for more details. + + + +DTV_ISDBS_TS_ID + +u32 + +??? + + +
+ + + +The applicability of each property to each frontend delivery mechanism is given in the following table. If you can fill in any gaps, please send patches. + + +DVB v5 API properties applicability + + + + + + + + + + +Name +DVB-C (A, C) +DVB-C (B) +DVB-T +DSS +DVB-S +DVB-S2 +DVB-H +ISDB-T +ISDB-S +ISDB-C +ATSC +ATSC-MH +DMB-TH +CMMB +DAB + + + + +DTV_API_VERSION +Y + + +DTV_FE_CAPABILITY_COUNT +Y + + +DTV_FE_CAPABILITY +Y + + +DTV_DELIVERY_SYSTEM +Y + + +DTV_TUNE +Y + + +DTV_CLEAR +Y + + +DTV_FREQUENCY +Y + + +DTV_MODULATION + + +Y +? +Y +Y +? + +? +? +Y +? +? +? +? + + +DTV_BANDWIDTH_HZ + + +Y +? +? +? +? +Y +? +? +? +? +? +? +? + + +DTV_INVERSION +Y +Y +Y +? +Y +? +? + +? +? +? +? +? +? +? + + +DTV_SYMBOL_RATE +Y +Y + +? +Y +Y +? + +? +? +? +? +? +? +? + + +DTV_INNER_FEC +Y +Y + +? +Y +Y +? + +? +? +? +? +? +? +? + + +DTV_DISEQC_MASTER + + + + +? +Y +Y + +? +? +? +? +? +? + + + +DTV_DISEQC_SLAVE_REPLY + + + +? +Y +Y + + +? + +? +? +? +? + + + +DTV_VOLTAGE + + + +? +Y +Y +? + +? + +? +? +? +? + + + +DTV_TONE + + + +? +Y +Y +? + +? + +? +? +? +? + + + +DTV_PILOT +? +? +? +? +? +? +? + +? +? +? +? +? +? +? + + +DTV_ROLLOFF +? +? +? +? +? +? +? + +? +? +? +? +? +? +? + + +DTV_CODE_RATE_HP + + +Y +? + + +? + +? +? +? +? +? +? +? + + +DTV_CODE_RATE_LP + + +Y +? + + +? + +? +? +? +? +? +? +? + + +DTV_GUARD_INTERVAL + + +Y +? + + +? +Y +? +? +? +? +? +? +? + + +DTV_TRANSMISSION_MODE + + +Y +? + + +? +Y +? +? +? +? +? +? +? + + +DTV_HIERARCHY + + +Y +? + + +? + +? +? +? +? +? +? +? + + +DTV_ISDBT_PARTIAL_RECEPTION + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_SOUND_BROADCASTING + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_SB_SUBCHANNEL_ID + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_SB_SEGMENT_IDX + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_SB_SEGMENT_COUNT + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_LAYERx_FEC + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_LAYERx_MODULATION + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_LAYERx_SEGMENT_COUNT + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_LAYERx_TIME_INTERLEAVING + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBT_LAYER_ENABLED + + + + + + + +Y +? +? +? +? +? +? +? + + +DTV_ISDBS_TS_ID + + + + + + + +? +Y +? +? +? +? +? +? + + + +
+ +
+ +
+ +
+Frontend structures (v3) + +A number of data structures are defined in linux/dvb/frontend.h. +These are used by the v3 API only. More details on the use of each +type are given in the relevant function documentation. + +
+frontend information + +Information about the frontend can be queried with + FE_GET_INFO. + + + struct dvb_frontend_info { + char name[128]; + fe_type_t type; + uint32_t frequency_min; + uint32_t frequency_max; + uint32_t frequency_stepsize; + uint32_t frequency_tolerance; + uint32_t symbol_rate_min; + uint32_t symbol_rate_max; + uint32_t symbol_rate_tolerance; /⋆ ppm ⋆/ + uint32_t notifier_delay; /⋆ ms ⋆/ + fe_caps_t caps; + }; + +
+ +
+diseqc master command + +A message sent from the frontend to DiSEqC capable equipment. + + struct dvb_diseqc_master_cmd { + uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ + uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ + }; + +
+
+diseqc slave reply + +A reply to the frontend from DiSEqC 2.0 capable equipment. + + struct dvb_diseqc_slave_reply { + uint8_t msg [4]; /⋆ { framing, data [3] } ⋆/ + uint8_t msg_len; /⋆ valid values are 0...4, 0 means no msg ⋆/ + int timeout; /⋆ return from ioctl after timeout ms with ⋆/ + }; /⋆ errorcode when no message was received ⋆/ + +
+ +
+frontend parameters + +Different frontend types use different sets of parameters in the +tuning process. For DVB-T, DVB-C and DVB-S frontends (supported by the +v3 API), all such parameters are combined into a single +structure: + + + struct dvb_frontend_parameters { + uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ + /⋆ intermediate frequency in kHz for QPSK ⋆/ + fe_spectral_inversion_t inversion; + union { + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; + struct dvb_vsb_parameters vsb; + } u; + }; + +For satellite QPSK frontends you have to use the QPSK Parameters member defined by + + struct dvb_qpsk_parameters { + uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ + fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ + }; + +for cable QAM frontend you use the QAM Parameters structure + + struct dvb_qam_parameters { + uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ + fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ + fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ + }; + +DVB-T frontends are supported by the OFDM Parameters structure + + + struct dvb_ofdm_parameters { + fe_bandwidth_t bandwidth; + fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ + fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ + fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ + fe_transmit_mode_t transmission_mode; + fe_guard_interval_t guard_interval; + fe_hierarchy_t hierarchy_information; + }; + +ATSC frontends are supported by the VSB Parameters structure + +struct dvb_vsb_parameters { + fe_modulation_t modulation; /* modulation type (see above) */ +}; + +In the case of QPSK frontends the frequency field specifies the intermediate +frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of +the LNB. The intermediate frequency has to be specified in units of kHz. For QAM, OFDM and VSB frontends the frequency specifies the absolute frequency and is given in +Hz. + +
+ +
+frontend events + + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; + +
+
+ +
+Frontend Function Calls (v3) +
FE_READ_STATUS DESCRIPTION Index: linux-2.6/Documentation/DocBook/dvb/intro.xml =================================================================== --- linux-2.6.orig/Documentation/DocBook/dvb/intro.xml 2010-02-17 13:54:28.000000000 +0000 +++ linux-2.6/Documentation/DocBook/dvb/intro.xml 2010-02-17 14:22:38.000000000 +0000 @@ -121,13 +121,14 @@ through currently six Unix-style character devices for video, audio, frontend, demux, CA and IP-over-DVB networking. The video and audio devices control the MPEG2 decoder hardware, the frontend device the -tuner and the DVB demodulator. The demux device gives you control over -the PES and section filters of the hardware. If the hardware does not -support filtering these filters can be implemented in software. Finally, -the CA device controls all the conditional access capabilities of the -hardware. It can depend on the individual security requirements of the -platform, if and how many of the CA functions are made available to the -application through this device. +tuner, the DVB demodulator and (if present) the SEC. The demux device +gives you control over the PES and section filters of the hardware. If +the hardware does not support filtering these filters can be +implemented in software. Finally, the CA device controls all the +conditional access capabilities of the hardware. It can depend on the +individual security requirements of the platform, if and how many of +the CA functions are made available to the application through this +device. All devices can be found in the /dev tree under /dev/dvb. The individual devices @@ -184,8 +185,8 @@ additional include file linux/dvb/version.h exists, which defines the constant DVB_API_VERSION. This document -describes DVB_API_VERSION 3. - +describes DVB_API_VERSION 3, and +partially DVB_API_VERSION 5.
Index: linux-2.6/Documentation/DocBook/dvb/dvbapi.xml =================================================================== --- linux-2.6.orig/Documentation/DocBook/dvb/dvbapi.xml 2010-02-21 20:54:40.000000000 +0000 +++ linux-2.6/Documentation/DocBook/dvb/dvbapi.xml 2010-02-21 20:56:07.000000000 +0000 @@ -19,17 +19,32 @@
mchehab@redhat.com
 Ported document to Docbook XML. + +Hugo +Mills +
hugo@carfax.org.uk
 +Updates to v5 API. + 2002 2003 2009 + 2010 Convergence GmbH + 2.1 + 2010-02-21 + hrm + + Significant updates to document and explain the v5 API. + + + 2.0.2 2009-10-25 mcc Index: linux-2.6/Documentation/DocBook/dvb/dvbproperty.xml =================================================================== --- linux-2.6.orig/Documentation/DocBook/dvb/dvbproperty.xml 2010-02-21 21:13:11.000000000 +0000 +++ linux-2.6/Documentation/DocBook/dvb/dvbproperty.xml 2010-02-21 21:41:05.000000000 +0000 @@ -1,8 +1,6 @@ -
-FE_GET_PROPERTY/FE_SET_PROPERTY -
- ISDB-T frontend +ISDB-T + This section describes shortly what are the possible parameters in the Linux DVB-API called "S2API" and now DVB API 5 in order to tune an ISDB-T/ISDB-Tsb demodulator: @@ -315,4 +313,3 @@
-