From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: 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 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-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="UugvWAfsgieZRqgk" Content-Disposition: inline In-Reply-To: <1266538767.3248.14.camel@palomino.walls.org> Sender: linux-media-owner@vger.kernel.org List-ID: --UugvWAfsgieZRqgk Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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. OK, here's a first stab at cleaning up, and adding as much information as I know about for frontend devices. I've tried to separate out the v5 API and put that first, then the v3 API. I know little about the non-DVB specifications, so the summary table and documentation is rather incomplete in that area. The ISDB-T documentation I've left in its original place and state for now (with a modified title), because I don't know much about the technology. That section does need the attentions of a good copy editor though, and should probably go in an appendix. I'll have a go at that in the next revision. It's also not clear to me whether I should make ISDB-Tsb a separate column in the properties summary table or not, as there are properties which are ISDB-Tsb only. I've put up a copy of the HTML docs generated after this patch, at: http://carfax.org.uk/kdoc/media/pt02.html Hugo. 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 @@
-
-- === Hugo Mills: hugo@... carfax.org.uk | darksatanic.net | lug.org.uk === PGP key: 515C238D from wwwkeys.eu.pgp.net or http://www.carfax.org.uk --- echo "killall cat" > ~/curiosity.sh --- --UugvWAfsgieZRqgk Content-Type: application/pgp-signature; name="signature.asc" Content-Description: Digital signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) iD8DBQFLgarLIKyzvlFcI40RAkt9AJ9tb70YGa+G4iT8LRYgPzQ9v3M4XwCgm+oL V7UnZtlLmdW1qJQp4tekEco= =m2LQ -----END PGP SIGNATURE----- --UugvWAfsgieZRqgk--