Documentation/DocBook/media/dvb/dvbproperty.xml

   1 <section id="FE_GET_SET_PROPERTY">
   2 <title>FE_GET_PROPERTY/FE_SET_PROPERTY</title>
   3
   4 <programlisting>
   5 /* Reserved fields should be set to 0 */
   6 struct dtv_property {
   7         __u32 cmd;
   8         union {
   9                 __u32 data;
  10                 struct {
  11                         __u8 data[32];
  12                         __u32 len;
  13                         __u32 reserved1[3];
  14                         void *reserved2;
  15                 } buffer;
  16         } u;
  17         int result;
  18 } __attribute__ ((packed));
  19
  20 /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
  21 #define DTV_IOCTL_MAX_MSGS 64
  22
  23 struct dtv_properties {
  24         __u32 num;
  25         struct dtv_property *props;
  26 };
  27 </programlisting>
  28
  29 <section id="FE_GET_PROPERTY">
  30 <title>FE_GET_PROPERTY</title>
  31 <para>DESCRIPTION
  32 </para>
  33 <informaltable><tgroup cols="1"><tbody><row><entry
  34  align="char">
  35 <para>This ioctl call returns one or more frontend properties. This call only
  36  requires read-only access to the device.</para>
  37 </entry>
  38  </row></tbody></tgroup></informaltable>
  39 <para>SYNOPSIS
  40 </para>
  41 <informaltable><tgroup cols="1"><tbody><row><entry
  42  align="char">
  43 <para>int ioctl(int fd, int request = <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>,
  44  dtv_properties &#x22C6;props);</para>
  45 </entry>
  46  </row></tbody></tgroup></informaltable>
  47 <para>PARAMETERS
  48 </para>
  49 <informaltable><tgroup cols="2"><tbody><row><entry align="char">
  50 <para>int fd</para>
  51 </entry><entry
  52  align="char">
  53 <para>File descriptor returned by a previous call to open().</para>
  54 </entry>
  55  </row><row><entry
  56  align="char">
  57 <para>int num</para>
  58 </entry><entry
  59  align="char">
  60 <para>Equals <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link> for this command.</para>
  61 </entry>
  62  </row><row><entry
  63  align="char">
  64 <para>struct dtv_property *props</para>
  65 </entry><entry
  66  align="char">
  67 <para>Points to the location where the front-end property commands are stored.</para>
  68 </entry>
  69  </row></tbody></tgroup></informaltable>
  70 <para>ERRORS</para>
  71 <informaltable><tgroup cols="2"><tbody><row>
  72   <entry align="char"><para>EINVAL</para></entry>
  73   <entry align="char"><para>Invalid parameter(s) received or number of parameters out of the range.</para></entry>
  74  </row><row>
  75   <entry align="char"><para>ENOMEM</para></entry>
  76   <entry align="char"><para>Out of memory.</para></entry>
  77  </row><row>
  78   <entry align="char"><para>EFAULT</para></entry>
  79   <entry align="char"><para>Failure while copying data from/to userspace.</para></entry>
  80  </row><row>
  81   <entry align="char"><para>EOPNOTSUPP</para></entry>
  82   <entry align="char"><para>Property type not supported.</para></entry>
  83  </row></tbody></tgroup></informaltable>
  84 </section>
  85
  86 <section id="FE_SET_PROPERTY">
  87 <title>FE_SET_PROPERTY</title>
  88 <para>DESCRIPTION
  89 </para>
  90 <informaltable><tgroup cols="1"><tbody><row><entry
  91  align="char">
  92 <para>This ioctl call sets one or more frontend properties. This call only
  93  requires read-only access to the device.</para>
  94 </entry>
  95  </row></tbody></tgroup></informaltable>
  96 <para>SYNOPSIS
  97 </para>
  98 <informaltable><tgroup cols="1"><tbody><row><entry
  99  align="char">
 100 <para>int ioctl(int fd, int request = <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
 101  dtv_properties &#x22C6;props);</para>
 102 </entry>
 103  </row></tbody></tgroup></informaltable>
 104 <para>PARAMETERS
 105 </para>
 106 <informaltable><tgroup cols="2"><tbody><row><entry align="char">
 107 <para>int fd</para>
 108 </entry><entry
 109  align="char">
 110 <para>File descriptor returned by a previous call to open().</para>
 111 </entry>
 112  </row><row><entry
 113  align="char">
 114 <para>int num</para>
 115 </entry><entry
 116  align="char">
 117 <para>Equals <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link> for this command.</para>
 118 </entry>
 119  </row><row><entry
 120  align="char">
 121 <para>struct dtv_property *props</para>
 122 </entry><entry
 123  align="char">
 124 <para>Points to the location where the front-end property commands are stored.</para>
 125 </entry>
 126  </row></tbody></tgroup></informaltable>
 127 <para>ERRORS
 128 </para>
 129 <informaltable><tgroup cols="2"><tbody><row>
 130   <entry align="char"><para>EINVAL</para></entry>
 131   <entry align="char"><para>Invalid parameter(s) received or number of parameters out of the range.</para></entry>
 132  </row><row>
 133   <entry align="char"><para>ENOMEM</para></entry>
 134   <entry align="char"><para>Out of memory.</para></entry>
 135  </row><row>
 136   <entry align="char"><para>EFAULT</para></entry>
 137   <entry align="char"><para>Failure while copying data from/to userspace.</para></entry>
 138  </row><row>
 139   <entry align="char"><para>EOPNOTSUPP</para></entry>
 140   <entry align="char"><para>Property type not supported.</para></entry>
 141  </row></tbody></tgroup></informaltable>
 142 </section>
 143
 144 <section>
 145         <title>Property types</title>
 146 <para>
 147 On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>/<link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
 148 the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to
 149 get/set up to 64 properties. The actual meaning of each property is described on the next sections.
 150 </para>
 151
 152 <para>The available frontend property types are:</para>
 153
 154 <para><link linkend="DTV-UNDEFINED">DTV_UNDEFINED</link></para>
 155 <para><link linkend="DTV-TUNE">DTV_TUNE</link></para>
 156 <para><link linkend="DTV-CLEAR">DTV_CLEAR</link></para>
 157 <para><link linkend="DTV-FREQUENCY">DTV_FREQUENCY</link></para>
 158 <para><link linkend="DTV-MODULATION">DTV_MODULATION</link></para>
 159 <para><link linkend="DTV-BANDWIDTH-HZ">DTV_BANDWIDTH_HZ</link></para>
 160 <para><link linkend="DTV-INVERSION">DTV_INVERSION</link></para>
 161 <para><link linkend="DTV-DISEQC-MASTER">DTV_DISEQC_MASTER</link></para>
 162 <para><link linkend="DTV-SYMBOL-RATE">DTV_SYMBOL_RATE</link></para>
 163 <para><link linkend="DTV-INNER-FEC">DTV_INNER_FEC</link></para>
 164 <para><link linkend="DTV-VOLTAGE">DTV_VOLTAGE</link></para>
 165 <para><link linkend="DTV-TONE">DTV_TONE</link></para>
 166 <para><link linkend="DTV-PILOT">DTV_PILOT</link></para>
 167 <para><link linkend="DTV-ROLLOFF">DTV_ROLLOFF</link></para>
 168 <para><link linkend="DTV-DISEQC-SLAVE-REPLY">DTV_DISEQC_SLAVE_REPLY</link></para>
 169 <para><link linkend="DTV-FE-CAPABILITY-COUNT">DTV_FE_CAPABILITY_COUNT</link></para>
 170 <para><link linkend="DTV-FE-CAPABILITY">DTV_FE_CAPABILITY</link></para>
 171 <para><link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link></para>
 172 <para><link linkend="DTV-ISDBT-PARTIAL-RECEPTION">DTV_ISDBT_PARTIAL_RECEPTION</link></para>
 173 <para><link linkend="DTV-ISDBT-SOUND-BROADCASTING">DTV_ISDBT_SOUND_BROADCASTING</link></para>
 174 <para><link linkend="DTV-ISDBT-SB-SUBCHANNEL-ID">DTV_ISDBT_SB_SUBCHANNEL_ID</link></para>
 175 <para><link linkend="DTV-ISDBT-SB-SEGMENT-IDX">DTV_ISDBT_SB_SEGMENT_IDX</link></para>
 176 <para><link linkend="DTV-ISDBT-SB-SEGMENT-COUNT">DTV_ISDBT_SB_SEGMENT_COUNT</link></para>
 177 <para><link linkend="DTV-ISDBT-LAYER-FEC">DTV_ISDBT_LAYERA_FEC</link></para>
 178 <para><link linkend="DTV-ISDBT-LAYER-MODULATION">DTV_ISDBT_LAYERA_MODULATION</link></para>
 179 <para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT">DTV_ISDBT_LAYERA_SEGMENT_COUNT</link></para>
 180 <para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING">DTV_ISDBT_LAYERA_TIME_INTERLEAVING</link></para>
 181 <para><link linkend="DTV-ISDBT-LAYER-FEC">DTV_ISDBT_LAYERB_FEC</link></para>
 182 <para><link linkend="DTV-ISDBT-LAYER-MODULATION">DTV_ISDBT_LAYERB_MODULATION</link></para>
 183 <para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT">DTV_ISDBT_LAYERB_SEGMENT_COUNT</link></para>
 184 <para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING">DTV_ISDBT_LAYERB_TIME_INTERLEAVING</link></para>
 185 <para><link linkend="DTV-ISDBT-LAYER-FEC">DTV_ISDBT_LAYERC_FEC</link></para>
 186 <para><link linkend="DTV-ISDBT-LAYER-MODULATION">DTV_ISDBT_LAYERC_MODULATION</link></para>
 187 <para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT">DTV_ISDBT_LAYERC_SEGMENT_COUNT</link></para>
 188 <para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING">DTV_ISDBT_LAYERC_TIME_INTERLEAVING</link></para>
 189 <para><link linkend="DTV-API-VERSION">DTV_API_VERSION</link></para>
 190 <para><link linkend="DTV-CODE-RATE-HP">DTV_CODE_RATE_HP</link></para>
 191 <para><link linkend="DTV-CODE-RATE-LP">DTV_CODE_RATE_LP</link></para>
 192 <para><link linkend="DTV-GUARD-INTERVAL">DTV_GUARD_INTERVAL</link></para>
 193 <para><link linkend="DTV-TRANSMISSION-MODE">DTV_TRANSMISSION_MODE</link></para>
 194 <para><link linkend="DTV-HIERARCHY">DTV_HIERARCHY</link></para>
 195 <para><link linkend="DTV-ISDBT-LAYER-ENABLED">DTV_ISDBT_LAYER_ENABLED</link></para>
 196 <para><link linkend="DTV-ISDBS-TS-ID">DTV_ISDBS_TS_ID</link></para>
 197 <para><link linkend="DTV-DVBT2-PLP-ID">DTV_DVBT2_PLP_ID</link></para>
 198 </section>
 199
 200 <section id="fe_property_common">
 201         <title>Parameters that are common to all Digital TV standards</title>
 202         <section id="DTV-UNDEFINED">
 203         <title><constant>DTV_UNDEFINED</constant></title>
 204         <para>Used internally. A GET/SET operation for it won't change or return anything.</para>
 205         </section>
 206         <section id="DTV-TUNE">
 207         <title><constant>DTV_TUNE</constant></title>
 208         <para>Interpret the cache of data, build either a traditional frontend tunerequest so we can pass validation in the <constant>FE_SET_FRONTEND</constant> ioctl.</para>
 209         </section>
 210         <section id="DTV-CLEAR">
 211         <title><constant>DTV_CLEAR</constant></title>
 212         <para>Reset a cache of data specific to the frontend here. This does not effect hardware.</para>
 213         </section>
 214         <section id="DTV-MODULATION">
 215         <title><constant>DTV_MODULATION</constant></title>
 216 <para>Specifies the frontend modulation type for cable and satellite types. The modulation can be one of the types bellow:</para>
 217 <programlisting>
 218  typedef enum fe_modulation {
 219         QPSK,
 220         QAM_16,
 221         QAM_32,
 222         QAM_64,
 223         QAM_128,
 224         QAM_256,
 225         QAM_AUTO,
 226         VSB_8,
 227         VSB_16,
 228         PSK_8,
 229         APSK_16,
 230         APSK_32,
 231         DQPSK,
 232  } fe_modulation_t;
 233 </programlisting>
 234         </section>
 235         <section id="DTV-INVERSION">
 236         <title><constant>DTV_INVERSION</constant></title>
 237         <para>The Inversion field can take one of these values:
 238         </para>
 239         <programlisting>
 240         typedef enum fe_spectral_inversion {
 241                 INVERSION_OFF,
 242                 INVERSION_ON,
 243                 INVERSION_AUTO
 244         } fe_spectral_inversion_t;
 245         </programlisting>
 246         <para>It indicates if spectral inversion should be presumed or not. In the automatic setting
 247         (<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
 248         itself.
 249         </para>
 250         </section>
 251         <section id="DTV-DISEQC-MASTER">
 252         <title><constant>DTV_DISEQC_MASTER</constant></title>
 253         <para>Currently not implemented.</para>
 254         </section>
 255         <section id="DTV-SYMBOL-RATE">
 256         <title><constant>DTV_SYMBOL_RATE</constant></title>
 257         <para>Digital TV symbol rate, in bauds (symbols/second). Used on cable standards.</para>
 258         </section>
 259         <section id="DTV-INNER-FEC">
 260         <title><constant>DTV_INNER_FEC</constant></title>
 261         <para>Used cable/satellite transmissions. The acceptable values are:
 262         </para>
 263         <programlisting>
 264 typedef enum fe_code_rate {
 265         FEC_NONE = 0,
 266         FEC_1_2,
 267         FEC_2_3,
 268         FEC_3_4,
 269         FEC_4_5,
 270         FEC_5_6,
 271         FEC_6_7,
 272         FEC_7_8,
 273         FEC_8_9,
 274         FEC_AUTO,
 275         FEC_3_5,
 276         FEC_9_10,
 277 } fe_code_rate_t;
 278         </programlisting>
 279         <para>which correspond to error correction rates of 1/2, 2/3, etc.,
 280         no error correction or auto detection.</para>
 281         </section>
 282         <section id="DTV-VOLTAGE">
 283         <title><constant>DTV_VOLTAGE</constant></title>
 284         <para>The voltage is usually used with non-DiSEqC capable LNBs to switch
 285         the polarzation (horizontal/vertical). When using DiSEqC epuipment this
 286         voltage has to be switched consistently to the DiSEqC commands as
 287         described in the DiSEqC spec.</para>
 288         <programlisting>
 289                 typedef enum fe_sec_voltage {
 290                 SEC_VOLTAGE_13,
 291                 SEC_VOLTAGE_18
 292                 } fe_sec_voltage_t;
 293         </programlisting>
 294         </section>
 295         <section id="DTV-TONE">
 296         <title><constant>DTV_TONE</constant></title>
 297         <para>Currently not used.</para>
 298         </section>
 299         <section id="DTV-PILOT">
 300         <title><constant>DTV_PILOT</constant></title>
 301         <para>Sets DVB-S2 pilot</para>
 302         <section id="fe-pilot-t">
 303                 <title>fe_pilot type</title>
 304                 <programlisting>
 305 typedef enum fe_pilot {
 306         PILOT_ON,
 307         PILOT_OFF,
 308         PILOT_AUTO,
 309 } fe_pilot_t;
 310                 </programlisting>
 311                 </section>
 312         </section>
 313         <section id="DTV-ROLLOFF">
 314         <title><constant>DTV_ROLLOFF</constant></title>
 315                 <para>Sets DVB-S2 rolloff</para>
 316
 317         <section id="fe-rolloff-t">
 318                 <title>fe_rolloff type</title>
 319                 <programlisting>
 320 typedef enum fe_rolloff {
 321         ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */
 322         ROLLOFF_20,
 323         ROLLOFF_25,
 324         ROLLOFF_AUTO,
 325 } fe_rolloff_t;
 326                 </programlisting>
 327                 </section>
 328         </section>
 329         <section id="DTV-DISEQC-SLAVE-REPLY">
 330         <title><constant>DTV_DISEQC_SLAVE_REPLY</constant></title>
 331         <para>Currently not implemented.</para>
 332         </section>
 333         <section id="DTV-FE-CAPABILITY-COUNT">
 334         <title><constant>DTV_FE_CAPABILITY_COUNT</constant></title>
 335         <para>Currently not implemented.</para>
 336         </section>
 337         <section id="DTV-FE-CAPABILITY">
 338         <title><constant>DTV_FE_CAPABILITY</constant></title>
 339         <para>Currently not implemented.</para>
 340         </section>
 341         <section id="DTV-API-VERSION">
 342         <title><constant>DTV_API_VERSION</constant></title>
 343         <para>Returns the major/minor version of the DVB API</para>
 344         </section>
 345         <section id="DTV-CODE-RATE-HP">
 346         <title><constant>DTV_CODE_RATE_HP</constant></title>
 347         <para>Used on terrestrial transmissions. The acceptable values are:
 348         </para>
 349         <programlisting>
 350 typedef enum fe_code_rate {
 351         FEC_NONE = 0,
 352         FEC_1_2,
 353         FEC_2_3,
 354         FEC_3_4,
 355         FEC_4_5,
 356         FEC_5_6,
 357         FEC_6_7,
 358         FEC_7_8,
 359         FEC_8_9,
 360         FEC_AUTO,
 361         FEC_3_5,
 362         FEC_9_10,
 363 } fe_code_rate_t;
 364         </programlisting>
 365         </section>
 366         <section id="DTV-CODE-RATE-LP">
 367         <title><constant>DTV_CODE_RATE_LP</constant></title>
 368         <para>Used on terrestrial transmissions. The acceptable values are:
 369         </para>
 370         <programlisting>
 371 typedef enum fe_code_rate {
 372         FEC_NONE = 0,
 373         FEC_1_2,
 374         FEC_2_3,
 375         FEC_3_4,
 376         FEC_4_5,
 377         FEC_5_6,
 378         FEC_6_7,
 379         FEC_7_8,
 380         FEC_8_9,
 381         FEC_AUTO,
 382         FEC_3_5,
 383         FEC_9_10,
 384 } fe_code_rate_t;
 385         </programlisting>
 386         </section>
 387         <section id="DTV-HIERARCHY">
 388         <title><constant>DTV_HIERARCHY</constant></title>
 389         <para>Frontend hierarchy</para>
 390         <programlisting>
 391 typedef enum fe_hierarchy {
 392          HIERARCHY_NONE,
 393          HIERARCHY_1,
 394          HIERARCHY_2,
 395          HIERARCHY_4,
 396          HIERARCHY_AUTO
 397  } fe_hierarchy_t;
 398         </programlisting>
 399         </section>
 400         <section id="DTV-ISDBS-TS-ID">
 401         <title><constant>DTV_ISDBS_TS_ID</constant></title>
 402         <para>Currently unused.</para>
 403         </section>
 404         <section id="DTV-FREQUENCY">
 405                 <title><constant>DTV_FREQUENCY</constant></title>
 406
 407                 <para>Central frequency of the channel, in HZ.</para>
 408
 409                 <para>Notes:</para>
 410                 <para>1)For ISDB-T, the channels are usually transmitted with an offset of 143kHz.
 411                         E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of
 412                         the channel which is 6MHz.</para>
 413
 414                 <para>2)As in ISDB-Tsb the channel consists of only one or three segments the
 415                         frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
 416                         central frequency of the channel is expected.</para>
 417         </section>
 418
 419         <section id="DTV-BANDWIDTH-HZ">
 420                 <title><constant>DTV_BANDWIDTH_HZ</constant></title>
 421
 422                 <para>Bandwidth for the channel, in HZ.</para>
 423
 424                 <para>Possible values:
 425                         <constant>1712000</constant>,
 426                         <constant>5000000</constant>,
 427                         <constant>6000000</constant>,
 428                         <constant>7000000</constant>,
 429                         <constant>8000000</constant>,
 430                         <constant>10000000</constant>.
 431                 </para>
 432
 433                 <para>Notes:</para>
 434
 435                 <para>1) For ISDB-T it should be always 6000000Hz (6MHz)</para>
 436                 <para>2) For ISDB-Tsb it can vary depending on the number of connected segments</para>
 437                 <para>3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth
 438                          for DVB-C depends on the symbol rate</para>
 439                 <para>4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
 440                         other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
 441                         DTV_ISDBT_SB_SEGMENT_COUNT).</para>
 442                 <para>5) DVB-T supports 6, 7 and 8MHz.</para>
 443                 <para>6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.</para>
 444         </section>
 445
 446         <section id="DTV-DELIVERY-SYSTEM">
 447                 <title><constant>DTV_DELIVERY_SYSTEM</constant></title>
 448
 449                 <para>Specifies the type of Delivery system</para>
 450
 451                 <para>Possible values: </para>
 452 <programlisting>
 453 typedef enum fe_delivery_system {
 454         SYS_UNDEFINED,
 455         SYS_DVBC_ANNEX_AC,
 456         SYS_DVBC_ANNEX_B,
 457         SYS_DVBT,
 458         SYS_DSS,
 459         SYS_DVBS,
 460         SYS_DVBS2,
 461         SYS_DVBH,
 462         SYS_ISDBT,
 463         SYS_ISDBS,
 464         SYS_ISDBC,
 465         SYS_ATSC,
 466         SYS_ATSCMH,
 467         SYS_DMBTH,
 468         SYS_CMMB,
 469         SYS_DAB,
 470         SYS_DVBT2,
 471 } fe_delivery_system_t;
 472 </programlisting>
 473
 474         </section>
 475
 476         <section id="DTV-TRANSMISSION-MODE">
 477                 <title><constant>DTV_TRANSMISSION_MODE</constant></title>
 478
 479                 <para>Specifies the number of carriers used by the standard</para>
 480
 481                 <para>Possible values are:</para>
 482 <programlisting>
 483 typedef enum fe_transmit_mode {
 484         TRANSMISSION_MODE_2K,
 485         TRANSMISSION_MODE_8K,
 486         TRANSMISSION_MODE_AUTO,
 487         TRANSMISSION_MODE_4K,
 488         TRANSMISSION_MODE_1K,
 489         TRANSMISSION_MODE_16K,
 490         TRANSMISSION_MODE_32K,
 491 } fe_transmit_mode_t;
 492 </programlisting>
 493
 494                 <para>Notes:</para>
 495                 <para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
 496                         'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
 497
 498                 <para>2) If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the
 499                         hardware will try to find the correct FFT-size (if capable) and will
 500                         use TMCC to fill in the missing parameters.</para>
 501                 <para>3) DVB-T specifies 2K and 8K as valid sizes.</para>
 502                 <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para>
 503         </section>
 504
 505         <section id="DTV-GUARD-INTERVAL">
 506                 <title><constant>DTV_GUARD_INTERVAL</constant></title>
 507
 508                 <para>Possible values are:</para>
 509 <programlisting>
 510 typedef enum fe_guard_interval {
 511         GUARD_INTERVAL_1_32,
 512         GUARD_INTERVAL_1_16,
 513         GUARD_INTERVAL_1_8,
 514         GUARD_INTERVAL_1_4,
 515         GUARD_INTERVAL_AUTO,
 516         GUARD_INTERVAL_1_128,
 517         GUARD_INTERVAL_19_128,
 518         GUARD_INTERVAL_19_256,
 519 } fe_guard_interval_t;
 520 </programlisting>
 521
 522                 <para>Notes:</para>
 523                 <para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will
 524                         try to find the correct guard interval (if capable) and will use TMCC to fill
 525                         in the missing parameters.</para>
 526                 <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para>
 527         </section>
 528 </section>
 529
 530 <section id="isdbt">
 531         <title>ISDB-T frontend</title>
 532         <para>This section describes shortly what are the possible parameters in the Linux
 533                 DVB-API called "S2API" and now DVB API 5 in order to tune an ISDB-T/ISDB-Tsb
 534                 demodulator:</para>
 535
 536         <para>This ISDB-T/ISDB-Tsb API extension should reflect all information
 537                 needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible
 538                 that some very sophisticated devices won't need certain parameters to
 539                 tune.</para>
 540
 541         <para>The information given here should help application writers to know how
 542                 to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para>
 543
 544         <para>The details given here about ISDB-T and ISDB-Tsb are just enough to
 545                 basically show the dependencies between the needed parameter values,
 546                 but surely some information is left out. For more detailed information
 547                 see the following documents:</para>
 548
 549         <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial
 550                 Television Broadcasting" and</para>
 551         <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial
 552                 Television Broadcasting".</para>
 553
 554         <para>In order to read this document one has to have some knowledge the
 555                 channel structure in ISDB-T and ISDB-Tsb. I.e. it has to be known to
 556                 the reader that an ISDB-T channel consists of 13 segments, that it can
 557                 have up to 3 layer sharing those segments, and things like that.</para>
 558
 559         <para>Parameters used by ISDB-T and ISDB-Tsb.</para>
 560
 561         <section id="isdbt-new-parms">
 562                 <title>ISDB-T only parameters</title>
 563
 564                 <section id="DTV-ISDBT-PARTIAL-RECEPTION">
 565                         <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title>
 566
 567                         <para>If <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether
 568                                 the channel is in partial reception mode or not.</para>
 569
 570                         <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and
 571                                 <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para>
 572
 573                         <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'
 574                                 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel
 575                                 is consisting of one segment and layer or three segments and two layers.</para>
 576
 577                         <para>Possible values: 0, 1, -1 (AUTO)</para>
 578                 </section>
 579
 580                 <section id="DTV-ISDBT-SOUND-BROADCASTING">
 581                         <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title>
 582
 583                         <para>This field represents whether the other DTV_ISDBT_*-parameters are
 584                                 referring to an ISDB-T and an ISDB-Tsb channel. (See also
 585                                 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para>
 586
 587                         <para>Possible values: 0, 1, -1 (AUTO)</para>
 588                 </section>
 589
 590                 <section id="DTV-ISDBT-SB-SUBCHANNEL-ID">
 591                         <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title>
 592
 593                         <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
 594
 595                         <para>(Note of the author: This might not be the correct description of the
 596                                 <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical
 597                                 background needed to program a device)</para>
 598
 599                         <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
 600                                 set of connected ISDB-Tsb channels. In this set of channels every
 601                                 channel can be received independently. The number of connected
 602                                 ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum
 603                                 bandwidth available.</para>
 604
 605                         <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
 606                                 broadcaster has several possibilities to put those channels in the
 607                                 air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8
 608                                 segments from position 1-8 to 5-13 or anything in between.</para>
 609
 610                         <para>The underlying layer of segments are subchannels: each segment is
 611                                 consisting of several subchannels with a predefined IDs. A sub-channel
 612                                 is used to help the demodulator to synchronize on the channel.</para>
 613
 614                         <para>An ISDB-T channel is always centered over all sub-channels. As for
 615                                 the example above, in ISDB-Tsb it is no longer as simple as that.</para>
 616
 617                         <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the
 618                                 sub-channel ID of the segment to be demodulated.</para>
 619
 620                         <para>Possible values: 0 .. 41, -1 (AUTO)</para>
 621                 </section>
 622
 623                 <section id="DTV-ISDBT-SB-SEGMENT-IDX">
 624
 625                         <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title>
 626
 627                         <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
 628
 629                         <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be
 630                                 demodulated for an ISDB-Tsb channel where several of them are
 631                                 transmitted in the connected manner.</para>
 632
 633                         <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para>
 634
 635                         <para>Note: This value cannot be determined by an automatic channel search.</para>
 636                 </section>
 637
 638                 <section id="DTV-ISDBT-SB-SEGMENT-COUNT">
 639                         <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title>
 640
 641                         <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
 642
 643                         <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb
 644                                 channels.</para>
 645
 646                         <para>Possible values: 1 .. 13</para>
 647
 648                         <para>Note: This value cannot be determined by an automatic channel search.</para>
 649                 </section>
 650
 651                 <section id="isdb-hierq-layers">
 652                         <title>Hierarchical layers</title>
 653
 654                         <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
 655                                 ISDB-T hierarchical layers can be decoded simultaneously. For that
 656                                 reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para>
 657
 658                         <para>ISDB-T has 3 hierarchical layers which each can use a part of the
 659                                 available segments. The total number of segments over all layers has
 660                                 to 13 in ISDB-T.</para>
 661
 662                         <section id="DTV-ISDBT-LAYER-ENABLED">
 663                                 <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title>
 664
 665                                 <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling
 666                                         layers in the decoding process. Setting all bits of
 667                                         <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be
 668                                         demodulated. This is the default.</para>
 669
 670                                 <para>If the channel is in the partial reception mode
 671                                         (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded
 672                                         independently of the other 12 segments. In that mode layer A has to
 673                                         have a <constant>SEGMENT_COUNT</constant> of 1.</para>
 674
 675                                 <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb
 676                                         according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled
 677                                         accordingly.</para>
 678
 679                                 <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para>
 680
 681                                 <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para>
 682                                 <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para>
 683                                 <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para>
 684                                 <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para>
 685                         </section>
 686
 687                         <section id="DTV-ISDBT-LAYER-FEC">
 688                                 <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title>
 689
 690                                 <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>
 691                         </section>
 692
 693                         <section id="DTV-ISDBT-LAYER-MODULATION">
 694                                 <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title>
 695
 696                                 <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para>
 697
 698                                 <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant>
 699                                         and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para>
 700                         </section>
 701
 702                         <section id="DTV-ISDBT-LAYER-SEGMENT-COUNT">
 703                                 <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title>
 704
 705                                 <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para>
 706
 707                                 <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and
 708                                         <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para>
 709
 710                                 <informaltable id="isdbt-layer_seg-cnt-table">
 711                                         <tgroup cols="6">
 712
 713                                                 <tbody>
 714                                                         <row>
 715                                                                 <entry>PR</entry>
 716                                                                 <entry>SB</entry>
 717                                                                 <entry>Layer A width</entry>
 718                                                                 <entry>Layer B width</entry>
 719                                                                 <entry>Layer C width</entry>
 720                                                                 <entry>total width</entry>
 721                                                         </row>
 722
 723                                                         <row>
 724                                                                 <entry>0</entry>
 725                                                                 <entry>0</entry>
 726                                                                 <entry>1 .. 13</entry>
 727                                                                 <entry>1 .. 13</entry>
 728                                                                 <entry>1 .. 13</entry>
 729                                                                 <entry>13</entry>
 730                                                         </row>
 731
 732                                                         <row>
 733                                                                 <entry>1</entry>
 734                                                                 <entry>0</entry>
 735                                                                 <entry>1</entry>
 736                                                                 <entry>1 .. 13</entry>
 737                                                                 <entry>1 .. 13</entry>
 738                                                                 <entry>13</entry>
 739                                                         </row>
 740
 741                                                         <row>
 742                                                                 <entry>0</entry>
 743                                                                 <entry>1</entry>
 744                                                                 <entry>1</entry>
 745                                                                 <entry>0</entry>
 746                                                                 <entry>0</entry>
 747                                                                 <entry>1</entry>
 748                                                         </row>
 749
 750                                                         <row>
 751                                                                 <entry>1</entry>
 752                                                                 <entry>1</entry>
 753                                                                 <entry>1</entry>
 754                                                                 <entry>2</entry>
 755                                                                 <entry>0</entry>
 756                                                                 <entry>13</entry>
 757                                                         </row>
 758                                                 </tbody>
 759
 760                                         </tgroup>
 761                                 </informaltable>
 762
 763                         </section>
 764
 765                         <section id="DTV-ISDBT-LAYER-TIME-INTERLEAVING">
 766                                 <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title>
 767
 768                                 <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para>
 769
 770                                 <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values
 771                                         here are referring to what can be found in the TMCC-structure -
 772                                         independent of the mode.</para>
 773                         </section>
 774                 </section>
 775         </section>
 776         <section id="dvbt2-params">
 777                 <title>DVB-T2 parameters</title>
 778
 779                 <para>This section covers parameters that apply only to the DVB-T2 delivery method. DVB-T2
 780                         support is currently in the early stages development so expect this section to grow
 781                         and become more detailed with time.</para>
 782
 783                 <section id="DTV-DVBT2-PLP-ID">
 784                         <title><constant>DTV_DVBT2_PLP_ID</constant></title>
 785
 786                         <para>DVB-T2 supports Physical Layer Pipes (PLP) to allow transmission of
 787                                 many data types via a single multiplex. The API will soon support this
 788                                 at which point this section will be expanded.</para>
 789                 </section>
 790         </section>
 791 </section>
 792 </section>