[RFC] DVB API v5 Documentation (was: Re: Documentation questions)

Message ID	20100221215107.GA2247@selene (mailing list archive)
State	RFC
Headers	show 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 <patchwork-media@patchwork.kernel.org>; Sun, 21 Feb 2010 21:57:41 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753694Ab0BUV5c (ORCPT <rfc822;patchwork-media@patchwork.kernel.org>); 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 <rfc822;linux-media@vger.kernel.org>); 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 <hugo@carfax.org.uk>) 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 <hugo@carfax.org.uk>) 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 <hugo@carfax.org.uk> To: Andy Walls <awalls@radix.net> 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> 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: <linux-media.vger.kernel.org> 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 <emphasis role="tt">linux/dvb/frontend.h</emphasis> in your application.</para> -<para>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 -<ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para> +<para>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 <ulink +url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para> <para>Note that the DVB API may also be used for MPEG decoder-only PCI cards, in which case there exists no frontend device.</para> +<para>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.</para> + <section id="frontend_types"> -<title>Frontend Data Types</title> +<title>Frontend Enumeration Types</title> + +<para>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.</para> <section id="frontend_type"> <title>frontend type</title> @@ -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; </programlisting> </section> -<section id="frontend_info"> -<title>frontend information</title> - -<para>Information about the frontend ca be queried with - <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para> - -<programlisting> - 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; - }; -</programlisting> -</section> - -<section id="frontend_diseqc"> -<title>diseqc master command</title> - -<para>A message sent from the frontend to DiSEqC capable equipment.</para> -<programlisting> - struct dvb_diseqc_master_cmd { - uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ - uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ - }; -</programlisting> -</section> -<section role="subsection"> -<title>diseqc slave reply</title> - -<para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para> -<programlisting> - 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 ⋆/ -</programlisting> -</section> - <section id="frontend_diseqc_slave_reply"> <title>diseqc slave reply</title> <para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation @@ -125,7 +98,8 @@ <programlisting> typedef enum fe_sec_voltage { SEC_VOLTAGE_13, - SEC_VOLTAGE_18 + SEC_VOLTAGE_18, + SEC_VOLTAGE_OFF } fe_sec_voltage_t; </programlisting> </section> @@ -164,8 +138,9 @@ <section id="frontend_status"> <title>frontend status</title> -<para>Several functions of the frontend device use the fe_status data type defined -by</para> +<para>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.</para> <programlisting> 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 ⋆/ </programlisting> -<para>to indicate the current state and/or state changes of the frontend hardware. -</para> - </section> -<section id="frontend_params"> -<title>frontend parameters</title> -<para>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:</para> -<programlisting> - 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; - }; -</programlisting> -<para>For satellite QPSK frontends you have to use the <constant>QPSKParameters</constant> member defined by</para> -<programlisting> - 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) ⋆/ - }; -</programlisting> -<para>for cable QAM frontend you use the <constant>QAMParameters</constant> structure</para> -<programlisting> - 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) ⋆/ - }; -</programlisting> -<para>DVB-T frontends are supported by the <constant>OFDMParamters</constant> structure -</para> -<programlisting> - 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; - }; -</programlisting> -<para>In the case of QPSK frontends the <constant>Frequency</constant> 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. -</para> -<para>The Inversion field can take one of these values: -</para> +<section id="frontend_inversion"> +<title>inversion setting</title> +<para>Defines the spectral inversion. Used in tuning operations. It +indicates if spectral inversion should be presumed or not. In the +automatic setting (<constant>INVERSION_AUTO</constant>) the hardware +will try to figure out the correct setting by itself. </para> <programlisting> typedef enum fe_spectral_inversion { INVERSION_OFF, @@ -242,11 +167,11 @@ INVERSION_AUTO } fe_spectral_inversion_t; </programlisting> -<para>It indicates if spectral inversion should be presumed or not. In the automatic setting -(<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by -itself. -</para> -<para>The possible values for the <constant>FEC_inner</constant> field are +</section> + +<section id="frontend_fec"> +<title>forward error correction</title> +<para>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. </para> <programlisting> 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; </programlisting> -<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto -detection. -</para> -<para>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature -modulation mode which can be one of the following: -</para> +</section> + +<section id="frontend_qam"> +<title>quadrature modulation mode</title> +<para>For cable and terrestrial frontends (QAM and OFDM) one also has +to specify the quadrature modulation mode which can be one of the +following: </para> <programlisting> 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; </programlisting> -<para>Finally, there are several more parameters for OFDM: -</para> +</section> + +<section id="frontend_transmission_mode"> +<title>transmission mode</title> <programlisting> typedef enum fe_transmit_mode { TRANSMISSION_MODE_2K, TRANSMISSION_MODE_8K, - TRANSMISSION_MODE_AUTO + TRANSMISSION_MODE_AUTO, + TRANSMISSION_MODE_4K, } fe_transmit_mode_t; </programlisting> +</section> + +<section id="frontend_bandwidth"> +<title>bandwidth</title> <programlisting> typedef enum fe_bandwidth { BANDWIDTH_8_MHZ, @@ -296,6 +237,10 @@ BANDWIDTH_AUTO } fe_bandwidth_t; </programlisting> +</section> + +<section id="frontend_guard_interval"> +<title>guard interval</title> <programlisting> typedef enum fe_guard_interval { GUARD_INTERVAL_1_32, @@ -305,6 +250,10 @@ GUARD_INTERVAL_AUTO } fe_guard_interval_t; </programlisting> +</section> + +<section id="frontend_hierarchy"> +<title>hierarchy</title> <programlisting> typedef enum fe_hierarchy { HIERARCHY_NONE, @@ -314,49 +263,169 @@ HIERARCHY_AUTO } fe_hierarchy_t; </programlisting> +</section> +<section id="frontend_pilot"> +<title>pilot</title> +<programlisting> +typedef enum fe_pilot { + PILOT_ON, + PILOT_OFF, + PILOT_AUTO, +} fe_pilot_t; +</programlisting> </section> -<section id="frontend_events"> -<title>frontend events</title> - <programlisting> - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; +<section id="frontend_rolloff"> +<title>rolloff</title> +<programlisting> +typedef enum fe_rolloff { + ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */ + ROLLOFF_20, + ROLLOFF_25, + ROLLOFF_AUTO, +} fe_rolloff_t; +</programlisting> +</section> + +<section id="frontend_delivery_system"> +<title>delivery system</title> +<programlisting> +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; </programlisting> - </section> </section> +</section> -<section id="frontend_fcalls"> -<title>Frontend Function Calls</title> +<section id="frontend_v5_fcalls"> +<title>Frontend Function Calls (v5)</title> +<section id="frontend_v5_using"> +<title>Using the version 5 API</title> + +<para>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:</para> +<itemizedlist> +<listitem> +<para>open() a frontend device node (either in read-only or read-write mode)</para> +</listitem> +<listitem> +<para>close() an open frontend device</para> +</listitem> +<listitem> +<para>get a list of parameters from the device, using the FE_GET_PROPERTY ioctl</para> +</listitem> +<listitem> +<para>set a list of parameters on the device, using the FE_SET_PROPERTY ioctl</para> +</listitem> +</itemizedlist> + +<para>The two ioctls from the v5 API manipulate the internal state of +the device using a <link +linkend="frontend_dtv_properties">sequence</link> of simple tag/data +instructions. Almost all of these <link linkend="v5_properties">tagged +instructions</link> 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.</para> + +<para>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.</para> + +</section> + +<section id="frontend_dtv_properties"> +<title>Properties structure</title> +<para>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.</para> +<programlisting> +struct dtv_properties { + __u32 num; + struct dtv_property *props; +}; +</programlisting> +</section> -<section id="frontend_f_open"> +<section id="frontend_dtv_property"> +<title>Single property structure</title> +<para>This structure contains a <link linkend="v5_properties">property +tag</link> (<code>cmd</code>), and a data value +(<code>u.data</code>). At present, all of the data values used in the +v5 API are 32 bit numbers, and so <code>u.buffer</code> is +unused.</para> +<programlisting> +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)); +</programlisting> +</section> + +<section id="frontend_v5_frontend_f_open"> <title>open()</title> <para>DESCRIPTION</para> <informaltable><tgroup cols="1"><tbody><row> <entry align="char"> -<para>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 <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para> -<para>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.) -</para> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> + +<para>This system call opens a named frontend device +(/dev/dvb/adapter0/frontend0) for subsequent use.</para> + +<para>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).</para> + +<para>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.</para> + +</entry> +</row> +</tbody> +</tgroup> +</informaltable> <para>SYNOPSIS</para> <informaltable><tgroup cols="1"><tbody><row><entry @@ -397,13 +466,7 @@ align="char"> </entry><entry align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> +<para>O_NONBLOCK open in non-blocking mode (blocking mode is the default)</para> </entry> </row></tbody></tgroup></informaltable> <para>ERRORS @@ -479,6 +542,1153 @@ </row></tbody></tgroup></informaltable> </section> +<section id="FE_GET_PROPERTY2"> +<title>FE_GET_PROPERTY</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry align="char"> + +<para>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 <link linkend="v5_properties">table</link> below. +Currently, all properties are a single 32-bit value, and are thus +returned in the <code>dtv_property.u.data</code> element of the +property.</para> + +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = <link + linkend="FE_GET_PROPERTY2">FE_GET_PROPERTY</link>, <link + linkend="frontend_dtv_properties">dtv_properties</link> + ⋆properties);</para> +</entry> +</row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> + +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals <link linkend="FE_GET_PROPERTY2">FE_GET_PROPERTY</link> for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct <link linkend="frontend_dtv_properties">dtv_properties</link> *properties</para> +</entry><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>properties points to invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="FE_SET_PROPERTY"> +<title>FE_SET_PROPERTY</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> + +<para>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 <code>dtv_property.u.data</code> element of the property. +Writing to the DTV_TUNE, DTV_CLEAR, DTV_VOLTAGE and DTV_TONE +properties has side-effects (documented separately, below).</para> + +</entry> +</row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>, + <link linkend="frontend_dtv_properties">dtv_properties</link> ⋆properties);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> + +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link> for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct <link linkend="frontend_dtv_properties">dtv_properties</link> *properties</para> +</entry><entry + align="char"> +<para>Pointer to the dtv_properties structure containing a list of +properties to set.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>properties points to invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="v5_properties"> +<title>List of properties</title> +<para>The valid properties for the v5 API are listed below. Unless otherwise specified, properties are both readable and writable.</para> +<table> +<title>Semantics of v5 API properties.</title> +<tgroup cols="3"><thead> +<row><entry align="char"> +Name +</entry><entry> +Size/type +</entry><entry> +Description +</entry></row> +</thead> +<tbody> + +<row><entry align="char"> +DTV_API_VERSION +</entry><entry> +u32 +</entry><entry> +Read-only. Return the API version. Major version is encoded in bits 8-15, minor version in bits 0-7. +</entry></row> + +<row><entry align="char"> +DTV_FE_CAPABILITY_COUNT +</entry><entry> +</entry><entry> +Not implemented. +</entry></row> + +<row><entry align="char"> +DTV_FE_CAPABILITY +</entry><entry> +</entry><entry> +Not implemented. +</entry></row> + +<row><entry align="char"> +DTV_DELIVERY_SYSTEM +</entry><entry> +u32 +</entry><entry> +Read the type of delivery system. Values are defined in <link linkend="frontend_delivery_system">fe_delivery_system_t</link>. It is not clear what the effect of writing this property is. +</entry></row> + +<row><entry align="char"> +DTV_TUNE +</entry><entry> +No value +</entry><entry> +Write-only. Set this property to force the frontend device to retune +to its current settings. +</entry></row> + +<row><entry align="char"> +DTV_CLEAR +</entry><entry> +No value +</entry><entry> +Write-only. Set this property to clear the driver's settings and return +them to a default state. +</entry></row> + +<row><entry align="char"> +DTV_FREQUENCY +</entry><entry> +u32 +</entry><entry> +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. +</entry></row> + +<row><entry align="char"> +DTV_MODULATION +</entry><entry> +u32 +</entry><entry> +Quadrature modulation type. Use values from <link linkend="frontend_qam">fe_modulation_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_BANDWIDTH_HZ +</entry><entry> +u32 +</entry><entry> +The bandwidth of the service, in Hz (note: not an enumerated type) +</entry></row> + +<row><entry align="char"> +DTV_INVERSION +</entry><entry> +u32 +</entry><entry> +The spectral inversion setting. Use values from <link linkend="frontend_spectral_inversion">fe_spectral_inversion_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_SYMBOL_RATE +</entry><entry> +u32 +</entry><entry> +The symbol rate setting, in symbols per second. +</entry></row> + +<row><entry align="char"> +DTV_INNER_FEC +</entry><entry> +u32 +</entry><entry> +The Inner FEC setting. Use values from <link linkend="frontend_fec">fe_code_rate_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_DISEQC_MASTER +</entry><entry> +u32 +</entry><entry> +??? +</entry></row> + +<row><entry align="char"> +DTV_DISEQC_SLAVE_REPLY +</entry><entry> +u32 +</entry><entry> +??? +</entry></row> + +<row><entry align="char"> +DTV_VOLTAGE +</entry><entry> +u32 +</entry><entry> +Set higher voltage (18V instead of 13V) for long cable runs. Setting +this parameter takes effect immediately. Use values from <link +linkend="frontend_sec_voltage">fe_sec_voltage_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_TONE +</entry><entry> +u32 +</entry><entry> +Enable/disable the constant 22kHz tone for DiSEqC control. Use values +from <link linkend="frontend_tone_mode">fe_sec_tone_mode_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_PILOT +</entry><entry> +u32 +</entry><entry> +??? Use values from <link linkend="frontend_pilot">fe_pilot_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_ROLLOFF +</entry><entry> +u32 +</entry><entry> +Set rolloff value. Use values from <link linkend="frontend_rolloff">fe_rolloff_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_CODE_RATE_HP +</entry><entry> +u32 +</entry><entry> +Code rate for high priority streams. Use values from <link linkend="frontend_fec">fe_code_rate_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_CODE_RATE_LP +</entry><entry> +u32 +</entry><entry> +Code rate for low priority streams. Use values from <link linkend="frontend_fec">fe_code_rate_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_GUARD_INTERVAL +</entry><entry> +u32 +</entry><entry> +Guard interval setting. Use values from <link linkend="frontend_guard_interval">fe_guard_interval_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_TRANSMISSION_MODE +</entry><entry> +u32 +</entry><entry> +Transmission mode setting. Use values from <link linkend="frontend_transmission_mode">fe_transmit_mode_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_HIERARCHY +</entry><entry> +u32 +</entry><entry> +Hierarchy setting. Use values from <link linkend="frontend_hierarchy">fe_hierarchy_t</link>. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_PARTIAL_RECEPTION +</entry><entry> +u32 +</entry><entry> +Defines whether the channel is in partial reception mode: 0 (false), 1 (true) or -1 (auto). See <link linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_SOUND_BROADCASTING +</entry><entry> +u32 +</entry><entry> +Defines whether the channel is ISDB-T or ISDB-Tsb (sound broadcasting). 0 (false), 1 (true) or -1 (auto). See <link linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_SB_SUBCHANNEL_ID +</entry><entry> +u32 +</entry><entry> +Sound broadcasting subchannel ID. Applies only for ISDB-Tsb +(i.e. DTV_ISDBT_SOUND_BROADCASTING == 1). See <link linkend="isdbt">ISDB-T</link> +for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_SB_SEGMENT_COUNT +</entry><entry> +u32 +</entry><entry> +Sound broadcasting segment count. Applies only for ISDB-Tsb. See <link +linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_SB_SEGMENT_IDX +</entry><entry> +u32 +</entry><entry> +Sound broadcasting segment index. Applies only for ISDB-Tsb. See <link +linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_LAYER_ENABLED +</entry><entry> +u32 +</entry><entry> +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 <link linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_LAYER<replaceable>x</replaceable>_FEC +</entry><entry> +u32 +</entry><entry> +FEC setting for a specific layer. <replaceable>x</replaceable> is one +of A, B, or C. Use values from <link +linkend="frontend_fec">fe_code_rate_t</link>. See <link +linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_LAYER<replaceable>x</replaceable>_MODULATION +</entry><entry> +u32 +</entry><entry> +Modulation setting for a specific layer. <replaceable>x</replaceable> +is one of A, B, or C. Use values from <link +linkend="frontend_modulation">fe_modulation_t</link>. See <link +linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_LAYER<replaceable>x</replaceable>_SEGMENT_COUNT +</entry><entry> +u32 +</entry><entry> +Number of segments for a specific layer. <replaceable>x</replaceable> +is one of A, B, or C. Values in range 0-13, or -1 for auto. See <link +linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBT_LAYER<replaceable>x</replaceable>_TIME_INTERLEAVING +</entry><entry> +u32 +</entry><entry> +Interleaving setting. <replaceable>x</replaceable> 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 <link linkend="isdbt">ISDB-T</link> for more details. +</entry></row> + +<row><entry align="char"> +DTV_ISDBS_TS_ID +</entry><entry> +u32 +</entry><entry> +??? +</entry></row> + +</tbody></tgroup></table> + + + +<para>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.</para> + +<table> +<title>DVB v5 API properties applicability</title> +<tgroup cols="19" align="center" colsep="1" rowsep="1"> +<colspec colname="name" align="left"/><colspec colname="units"/> +<colspec colname="dvb-c-ac"/><colspec colname="dvb-c-b"/><colspec colname="dvb-t"/> +<colspec colname="dss"/><colspec colname="dvb-s"/><colspec colname="dvb-s2"/> +<colspec colname="dvb-h"/> +<colspec colname="isdb-t"/><colspec colname="isdb-s"/><colspec colname="isdb-c"/> +<colspec colname="atsc"/><colspec colname="atsc-mh"/> +<colspec colname="dmb-th"/><colspec colname="cmmb"/><colspec colname="dab"/> +<thead> +<row> +<entry>Name</entry> +<entry>DVB-C (A, C)</entry> +<entry>DVB-C (B)</entry> +<entry>DVB-T</entry> +<entry>DSS</entry> +<entry>DVB-S</entry> +<entry>DVB-S2</entry> +<entry>DVB-H</entry> +<entry>ISDB-T</entry> +<entry>ISDB-S</entry> +<entry>ISDB-C</entry> +<entry>ATSC</entry> +<entry>ATSC-MH</entry> +<entry>DMB-TH</entry> +<entry>CMMB</entry> +<entry>DAB</entry> +</row> +</thead> +<tbody> +<row> +<entry>DTV_API_VERSION</entry> +<entry namest="dvb-c-ac" nameend="dab">Y</entry> +</row> +<row> +<entry>DTV_FE_CAPABILITY_COUNT</entry> +<entry namest="dvb-c-ac" nameend="dab">Y</entry> +</row> +<row> +<entry>DTV_FE_CAPABILITY</entry> +<entry namest="dvb-c-ac" nameend="dab">Y</entry> +</row> +<row> +<entry>DTV_DELIVERY_SYSTEM</entry> +<entry namest="dvb-c-ac" nameend="dab">Y</entry> +</row> +<row> +<entry>DTV_TUNE</entry> +<entry namest="dvb-c-ac" nameend="dab">Y</entry> +</row> +<row> +<entry>DTV_CLEAR</entry> +<entry namest="dvb-c-ac" nameend="dab">Y</entry> +</row> +<row> +<entry>DTV_FREQUENCY</entry> +<entry namest="dvb-c-ac" nameend="dab">Y</entry> +</row> +<row> +<entry>DTV_MODULATION</entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_BANDWIDTH_HZ</entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_INVERSION</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry>?</entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_SYMBOL_RATE</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_INNER_FEC</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_DISEQC_MASTER</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry></entry> +</row> +<row> +<entry>DTV_DISEQC_SLAVE_REPLY</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry></entry> +</row> +<row> +<entry>DTV_VOLTAGE</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry></entry> +</row> +<row> +<entry>DTV_TONE</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry></entry> +</row> +<row> +<entry>DTV_PILOT</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ROLLOFF</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_CODE_RATE_HP</entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_CODE_RATE_LP</entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_GUARD_INTERVAL</entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_TRANSMISSION_MODE</entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_HIERARCHY</entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry></entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_PARTIAL_RECEPTION</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_SOUND_BROADCASTING</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_SB_SUBCHANNEL_ID</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_SB_SEGMENT_IDX</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_SB_SEGMENT_COUNT</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_LAYER<replaceable>x</replaceable>_FEC</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_LAYER<replaceable>x</replaceable>_MODULATION</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_LAYER<replaceable>x</replaceable>_SEGMENT_COUNT</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_LAYER<replaceable>x</replaceable>_TIME_INTERLEAVING</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBT_LAYER_ENABLED</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +<row> +<entry>DTV_ISDBS_TS_ID</entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry></entry> +<entry>?</entry> +<entry>Y</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +<entry>?</entry> +</row> +</tbody> +</tgroup> +</table> + +</section> + +</section> + +<section id="frontend_structures"> +<title>Frontend structures (v3)</title> + +<para>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 <link +linkend="frontend_fcalls">function documentation</link>.</para> + +<section id="frontend_info"> +<title>frontend information</title> + +<para>Information about the frontend can be queried with + <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para> + +<programlisting> + 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; + }; +</programlisting> +</section> + +<section id="frontend_diseqc"> +<title>diseqc master command</title> + +<para>A message sent from the frontend to DiSEqC capable equipment.</para> +<programlisting> + struct dvb_diseqc_master_cmd { + uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ + uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ + }; +</programlisting> +</section> +<section role="subsection"> +<title>diseqc slave reply</title> + +<para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para> +<programlisting> + 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 ⋆/ +</programlisting> +</section> + +<section id="frontend_params"> +<title>frontend parameters</title> + +<para>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:</para> + +<programlisting> + 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; + }; +</programlisting> +<para>For satellite QPSK frontends you have to use the <constant>QPSK Parameters</constant> member defined by</para> +<programlisting> + 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) ⋆/ + }; +</programlisting> +<para>for cable QAM frontend you use the <constant>QAM Parameters</constant> structure</para> +<programlisting> + 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) ⋆/ + }; +</programlisting> +<para>DVB-T frontends are supported by the <constant>OFDM Parameters</constant> structure +</para> +<programlisting> + 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; + }; +</programlisting> +<para>ATSC frontends are supported by the <constant>VSB Parameters</constant> structure</para> +<programlisting> +struct dvb_vsb_parameters { + fe_modulation_t modulation; /* modulation type (see above) */ +}; +</programlisting> +<para>In the case of QPSK frontends the <constant>frequency</constant> 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. +</para> +</section> + +<section id="frontend_events"> +<title>frontend events</title> + <programlisting> + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; +</programlisting> + </section> +</section> + +<section id="frontend_fcalls"> +<title>Frontend Function Calls (v3)</title> + <section id="FE_READ_STATUS"> <title>FE_READ_STATUS</title> <para>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.</para> +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.</para> <para>All devices can be found in the <emphasis role="tt">/dev</emphasis> tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices @@ -184,8 +185,8 @@ additional include file <emphasis role="tt">linux/dvb/version.h</emphasis> exists, which defines the constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document -describes <emphasis role="tt">DVB_API_VERSION 3</emphasis>. -</para> +describes <emphasis role="tt">DVB_API_VERSION 3</emphasis>, and +partially <emphasis role="tt">DVB_API_VERSION 5</emphasis>. </para> </section> 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 @@ <affiliation><address><email>mchehab@redhat.com</email></address></affiliation> <contrib>Ported document to Docbook XML.</contrib> </author> +<author> +<firstname>Hugo</firstname> +<surname>Mills</surname> +<affiliation><address><email>hugo@carfax.org.uk</email></address></affiliation> +<contrib>Updates to v5 API.</contrib> +</author> </authorgroup> <copyright> <year>2002</year> <year>2003</year> <year>2009</year> + <year>2010</year> <holder>Convergence GmbH</holder> </copyright> <revhistory>  <revision> + <revnumber>2.1</revnumber> + <date>2010-02-21</date> + <authorinitials>hrm</authorinitials> + <revremark> + Significant updates to document and explain the v5 API. + </revremark> +</revision> +<revision> <revnumber>2.0.2</revnumber> <date>2009-10-25</date> <authorinitials>mcc</authorinitials> 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 @@ -<section id="FE_GET_PROPERTY"> -<title>FE_GET_PROPERTY/FE_SET_PROPERTY</title> - <section id="isdbt"> - <title>ISDB-T frontend</title> +<title>ISDB-T</title> + <para>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:</para> @@ -315,4 +313,3 @@ </section> </section> </section> -</section>

[RFC] DVB API v5 Documentation (was: Re: Documentation questions)

Commit Message

Patch