<section id="FE_GET_SET_PROPERTY"> <title>FE_GET_PROPERTY/FE_SET_PROPERTY</title> <programlisting> /* Reserved fields should be set to 0 */ struct dtv_property { __u32 cmd; union { __u32 data; struct { __u8 data[32]; __u32 len; __u32 reserved1[3]; void *reserved2; } buffer; } u; int result; } __attribute__ ((packed)); /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */ #define DTV_IOCTL_MAX_MSGS 64 struct dtv_properties { __u32 num; struct dtv_property *props; }; </programlisting> <section id="FE_GET_PROPERTY"> <title>FE_GET_PROPERTY</title> <para>DESCRIPTION </para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call returns one or more frontend properties. This call only requires read-only access to the device.</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_PROPERTY">FE_GET_PROPERTY</link>, dtv_properties ⋆props);</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 num</para> </entry><entry align="char"> <para>Equals <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link> for this command.</para> </entry> </row><row><entry align="char"> <para>struct dtv_property *props</para> </entry><entry align="char"> <para>Points to the location where the front-end property commands are stored.</para> </entry> </row></tbody></tgroup></informaltable> <para>ERRORS</para> <informaltable><tgroup cols="2"><tbody><row> <entry align="char"><para>EINVAL</para></entry> <entry align="char"><para>Invalid parameter(s) received or number of parameters out of the range.</para></entry> </row><row> <entry align="char"><para>ENOMEM</para></entry> <entry align="char"><para>Out of memory.</para></entry> </row><row> <entry align="char"><para>EFAULT</para></entry> <entry align="char"><para>Failure while copying data from/to userspace.</para></entry> </row><row> <entry align="char"><para>EOPNOTSUPP</para></entry> <entry align="char"><para>Property type not supported.</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 one or more frontend properties. This call only requires read-only access to the device.</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>, dtv_properties ⋆props);</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 num</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 dtv_property *props</para> </entry><entry align="char"> <para>Points to the location where the front-end property commands are stored.</para> </entry> </row></tbody></tgroup></informaltable> <para>ERRORS </para> <informaltable><tgroup cols="2"><tbody><row> <entry align="char"><para>EINVAL</para></entry> <entry align="char"><para>Invalid parameter(s) received or number of parameters out of the range.</para></entry> </row><row> <entry align="char"><para>ENOMEM</para></entry> <entry align="char"><para>Out of memory.</para></entry> </row><row> <entry align="char"><para>EFAULT</para></entry> <entry align="char"><para>Failure while copying data from/to userspace.</para></entry> </row><row> <entry align="char"><para>EOPNOTSUPP</para></entry> <entry align="char"><para>Property type not supported.</para></entry> </row></tbody></tgroup></informaltable> </section> <section> <title>Property types</title> <para> On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>/<link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>, the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to get/set up to 64 properties. The actual meaning of each property is described on the next sections. </para> <para>The available frontend property types are:</para> <programlisting> #define DTV_UNDEFINED 0 #define DTV_TUNE 1 #define DTV_CLEAR 2 #define DTV_FREQUENCY 3 #define DTV_MODULATION 4 #define DTV_BANDWIDTH_HZ 5 #define DTV_INVERSION 6 #define DTV_DISEQC_MASTER 7 #define DTV_SYMBOL_RATE 8 #define DTV_INNER_FEC 9 #define DTV_VOLTAGE 10 #define DTV_TONE 11 #define DTV_PILOT 12 #define DTV_ROLLOFF 13 #define DTV_DISEQC_SLAVE_REPLY 14 #define DTV_FE_CAPABILITY_COUNT 15 #define DTV_FE_CAPABILITY 16 #define DTV_DELIVERY_SYSTEM 17 #define DTV_ISDBT_PARTIAL_RECEPTION 18 #define DTV_ISDBT_SOUND_BROADCASTING 19 #define DTV_ISDBT_SB_SUBCHANNEL_ID 20 #define DTV_ISDBT_SB_SEGMENT_IDX 21 #define DTV_ISDBT_SB_SEGMENT_COUNT 22 #define DTV_ISDBT_LAYERA_FEC 23 #define DTV_ISDBT_LAYERA_MODULATION 24 #define DTV_ISDBT_LAYERA_SEGMENT_COUNT 25 #define DTV_ISDBT_LAYERA_TIME_INTERLEAVING 26 #define DTV_ISDBT_LAYERB_FEC 27 #define DTV_ISDBT_LAYERB_MODULATION 28 #define DTV_ISDBT_LAYERB_SEGMENT_COUNT 29 #define DTV_ISDBT_LAYERB_TIME_INTERLEAVING 30 #define DTV_ISDBT_LAYERC_FEC 31 #define DTV_ISDBT_LAYERC_MODULATION 32 #define DTV_ISDBT_LAYERC_SEGMENT_COUNT 33 #define DTV_ISDBT_LAYERC_TIME_INTERLEAVING 34 #define DTV_API_VERSION 35 #define DTV_CODE_RATE_HP 36 #define DTV_CODE_RATE_LP 37 #define DTV_GUARD_INTERVAL 38 #define DTV_TRANSMISSION_MODE 39 #define DTV_HIERARCHY 40 #define DTV_ISDBT_LAYER_ENABLED 41 #define DTV_ISDBS_TS_ID 42 </programlisting> </section> <section id="fe_property_common"> <title>Parameters that are common to all Digital TV standards</title> <section id="DTV_FREQUENCY"> <title><constant>DTV_FREQUENCY</constant></title> <para>Central frequency of the channel, in HZ.</para> <para>Notes:</para> <para>1)For ISDB-T, the channels are usually transmitted with an offset of 143kHz. E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of the channel which is 6MHz.</para> <para>2)As in ISDB-Tsb the channel consists of only one or three segments the frequency step is 429kHz, 3*429 respectively. As for ISDB-T the central frequency of the channel is expected.</para> </section> <section id="DTV_BANDWIDTH_HZ"> <title><constant>DTV_BANDWIDTH_HZ</constant></title> <para>Bandwidth for the channel, in HZ.</para> <para>Possible values: <constant>1712000</constant>, <constant>5000000</constant>, <constant>6000000</constant>, <constant>7000000</constant>, <constant>8000000</constant>, <constant>10000000</constant>. </para> <para>Notes:</para> <para>1) For ISDB-T it should be always 6000000Hz (6MHz)</para> <para>2) For ISDB-Tsb it can vary depending on the number of connected segments</para> <para>3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth for DVB-C depends on the symbol rate</para> <para>4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from other parameters (DTV_ISDBT_SB_SEGMENT_IDX, DTV_ISDBT_SB_SEGMENT_COUNT).</para> <para>5) DVB-T supports 6, 7 and 8MHz.</para> <para>6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.</para> </section> <section id="DTV_DELIVERY_SYSTEM"> <title><constant>DTV_DELIVERY_SYSTEM</constant></title> <para>Specifies the type of Delivery system</para> <para>Possible values: </para> <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, SYS_DVBT2, } fe_delivery_system_t; </programlisting> </section> <section id="DTV_TRANSMISSION_MODE"> <title><constant>DTV_TRANSMISSION_MODE</constant></title> <para>Specifies the number of carriers used by the standard</para> <para>Possible values are:</para> <programlisting> typedef enum fe_transmit_mode { TRANSMISSION_MODE_2K, TRANSMISSION_MODE_8K, TRANSMISSION_MODE_AUTO, TRANSMISSION_MODE_4K, TRANSMISSION_MODE_1K, TRANSMISSION_MODE_16K, TRANSMISSION_MODE_32K, } fe_transmit_mode_t; </programlisting> <para>Notes:</para> <para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para> <para>2) If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the hardware will try to find the correct FFT-size (if capable) and will use TMCC to fill in the missing parameters.</para> <para>3) DVB-T specifies 2K and 8K as valid sizes.</para> <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para> </section> <section id="DTV_GUARD_INTERVAL"> <title><constant>DTV_GUARD_INTERVAL</constant></title> <para>Possible values are:</para> <programlisting> typedef enum fe_guard_interval { GUARD_INTERVAL_1_32, GUARD_INTERVAL_1_16, GUARD_INTERVAL_1_8, GUARD_INTERVAL_1_4, GUARD_INTERVAL_AUTO, GUARD_INTERVAL_1_128, GUARD_INTERVAL_19_128, GUARD_INTERVAL_19_256, } fe_guard_interval_t; </programlisting> <para>Notes:</para> <para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will try to find the correct guard interval (if capable) and will use TMCC to fill in the missing parameters.</para> <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para> </section> </section> <section id="isdbt"> <title>ISDB-T frontend</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> <para>This ISDB-T/ISDB-Tsb API extension should reflect all information needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some very sophisticated devices won't need certain parameters to tune.</para> <para>The information given here should help application writers to know how to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para> <para>The details given here about ISDB-T and ISDB-Tsb are just enough to basically show the dependencies between the needed parameter values, but surely some information is left out. For more detailed information see the following documents:</para> <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial Television Broadcasting" and</para> <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television Broadcasting".</para> <para>In order to read this document one has to have some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has to be known to the reader that an ISDB-T channel consists of 13 segments, that it can have up to 3 layer sharing those segments, and things like that.</para> <para>Parameters used by ISDB-T and ISDB-Tsb.</para> <section id="isdbt-new-parms"> <title>ISDB-T only parameters</title> <section id="isdbt-part-rec"> <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title> <para><constant>If DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether the channel is in partial reception mode or not.</para> <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para> <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1' <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel is consisting of one segment and layer or three segments and two layers.</para> <para>Possible values: 0, 1, -1 (AUTO)</para> </section> <section id="isdbt-sound-bcast"> <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title> <para>This field represents whether the other DTV_ISDBT_*-parameters are referring to an ISDB-T and an ISDB-Tsb channel. (See also <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para> <para>Possible values: 0, 1, -1 (AUTO)</para> </section> <section id="isdbt-sb-ch-id"> <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title> <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> <para>(Note of the author: This might not be the correct description of the <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical background needed to program a device)</para> <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a set of connected ISDB-Tsb channels. In this set of channels every channel can be received independently. The number of connected ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum bandwidth available.</para> <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The broadcaster has several possibilities to put those channels in the air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8 segments from position 1-8 to 5-13 or anything in between.</para> <para>The underlying layer of segments are subchannels: each segment is consisting of several subchannels with a predefined IDs. A sub-channel is used to help the demodulator to synchronize on the channel.</para> <para>An ISDB-T channel is always centered over all sub-channels. As for the example above, in ISDB-Tsb it is no longer as simple as that.</para> <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the sub-channel ID of the segment to be demodulated.</para> <para>Possible values: 0 .. 41, -1 (AUTO)</para> </section> <section id="isdbt-sb-seg-idx"> <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title> <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be demodulated for an ISDB-Tsb channel where several of them are transmitted in the connected manner.</para> <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para> <para>Note: This value cannot be determined by an automatic channel search.</para> </section> <section id="isdbt-sb-seg-cnt"> <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title> <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb channels.</para> <para>Possible values: 1 .. 13</para> <para>Note: This value cannot be determined by an automatic channel search.</para> </section> <section id="isdb-hierq-layers"> <title>Hierarchical layers</title> <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in ISDB-T hierarchical layers can be decoded simultaneously. For that reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para> <para>ISDB-T has 3 hierarchical layers which each can use a part of the available segments. The total number of segments over all layers has to 13 in ISDB-T.</para> <section id="isdbt-layer-ena"> <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title> <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling layers in the decoding process. Setting all bits of <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be demodulated. This is the default.</para> <para>If the channel is in the partial reception mode (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded independently of the other 12 segments. In that mode layer A has to have a <constant>SEGMENT_COUNT</constant> of 1.</para> <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled accordingly.</para> <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para> <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para> <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para> <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para> <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para> </section> <section id="isdbt-layer-fec"> <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title> <para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para> </section> <section id="isdbt-layer-mod"> <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title> <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para> <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant> and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para> </section> <section id="isdbt-layer-seg-cnt"> <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title> <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para> <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para> <informaltable id="isdbt-layer_seg-cnt-table"> <tgroup cols="6"> <tbody> <row> <entry>PR</entry> <entry>SB</entry> <entry>Layer A width</entry> <entry>Layer B width</entry> <entry>Layer C width</entry> <entry>total width</entry> </row> <row> <entry>0</entry> <entry>0</entry> <entry>1 .. 13</entry> <entry>1 .. 13</entry> <entry>1 .. 13</entry> <entry>13</entry> </row> <row> <entry>1</entry> <entry>0</entry> <entry>1</entry> <entry>1 .. 13</entry> <entry>1 .. 13</entry> <entry>13</entry> </row> <row> <entry>0</entry> <entry>1</entry> <entry>1</entry> <entry>0</entry> <entry>0</entry> <entry>1</entry> </row> <row> <entry>1</entry> <entry>1</entry> <entry>1</entry> <entry>2</entry> <entry>0</entry> <entry>13</entry> </row> </tbody> </tgroup> </informaltable> </section> <section id="isdbt_layer_t_interl"> <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title> <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para> <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values here are referring to what can be found in the TMCC-structure - independent of the mode.</para> </section> </section> </section> <section id="dvbt2-params"> <title>DVB-T2 parameters</title> <para>This section covers parameters that apply only to the DVB-T2 delivery method. DVB-T2 support is currently in the early stages development so expect this section to grow and become more detailed with time.</para> <section id="dvbt2-plp-id"> <title><constant>DTV_DVBT2_PLP_ID</constant></title> <para>DVB-T2 supports Physical Layer Pipes (PLP) to allow transmission of many data types via a single multiplex. The API will soon support this at which point this section will be expanded.</para> </section> </section> </section> </section>