Skip to content

L
linux
Commit 0ed08b49 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files
Options

DocBook/dvb: Improve description of the DVB API v5 

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 5a0deeed
Show whitespace changes
Inline Side-by-side
Showing with 315 additions and 68 deletions
Documentation/DocBook/dvb/dvbapi.xml
View file @ 0ed08b49
...@@ -34,6 +34,14 @@ ...@@ -34,6 +34,14 @@
<revhistory> <revhistory>
<!-- Put document revisions here, newest first. --> <!-- Put document revisions here, newest first. -->
<revision>
<revnumber>2.0.4</revnumber>
<date>2011-05-06</date>
<authorinitials>mcc</authorinitials>
<revremark>
Add more information about DVB APIv5, better describing the frontend GET/SET props ioctl's.
</revremark>
</revision>
<revision> <revision>
<revnumber>2.0.3</revnumber> <revnumber>2.0.3</revnumber>
<date>2010-07-03</date> <date>2010-07-03</date>
......
Documentation/DocBook/dvb/dvbproperty.xml
View file @ 0ed08b49
<section id="FE_GET_PROPERTY"> <section id="FE_GET_SET_PROPERTY">
<title>FE_GET_PROPERTY/FE_SET_PROPERTY</title> <title>FE_GET_PROPERTY/FE_SET_PROPERTY</title>
<section id="isdbt"> <programlisting>
<title>ISDB-T frontend</title> /* Reserved fields should be set to 0 */
<para>This section describes shortly what are the possible parameters in the Linux struct dtv_property {
DVB-API called "S2API" and now DVB API 5 in order to tune an ISDB-T/ISDB-Tsb __u32 cmd;
demodulator:</para> union {
__u32 data;
<para>This ISDB-T/ISDB-Tsb API extension should reflect all information struct {
needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible __u8 data[32];
that some very sophisticated devices won't need certain parameters to __u32 len;
tune.</para> __u32 reserved1[3];
void *reserved2;
<para>The information given here should help application writers to know how } buffer;
to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para> } u;
int result;
<para>The details given here about ISDB-T and ISDB-Tsb are just enough to } __attribute__ ((packed));
basically show the dependencies between the needed parameter values,
but surely some information is left out. For more detailed information /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
see the following documents:</para> #define DTV_IOCTL_MAX_MSGS 64
struct dtv_properties {
__u32 num;
struct dtv_property *props;
};
</programlisting>
<para>ARIB STD-B31 - "Transmission System for Digital Terrestrial <section id="FE_GET_PROPERTY">
Television Broadcasting" and</para> <title>FE_GET_PROPERTY</title>
<para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial <para>DESCRIPTION
Television Broadcasting".</para> </para>
<informaltable><tgroup cols="1"><tbody><row><entry
<para>In order to read this document one has to have some knowledge the align="char">
channel structure in ISDB-T and ISDB-Tsb. I.e. it has to be known to <para>This ioctl call returns one or more frontend properties. This call only
the reader that an ISDB-T channel consists of 13 segments, that it can requires read-only access to the device.</para>
have up to 3 layer sharing those segments, and things like that.</para> </entry>
</row></tbody></tgroup></informaltable>
<para>Parameters used by ISDB-T and ISDB-Tsb.</para> <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 &#x22C6;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="isdbt-parms"> <section id="FE_SET_PROPERTY">
<title>Parameters that are common with DVB-T and ATSC</title> <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 &#x22C6;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 id="isdbt-freq"> <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 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> <title><constant>DTV_FREQUENCY</constant></title>
<para>Central frequency of the channel.</para> <para>Central frequency of the channel, in HZ.</para>
<para>For ISDB-T the channels are usually transmitted with an offset of 143kHz. E.g. a <para>Notes:</para>
valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of <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> the channel which is 6MHz.</para>
<para>As in ISDB-Tsb the channel consists of only one or three segments the <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 frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
central frequency of the channel is expected.</para> central frequency of the channel is expected.</para>
</section> </section>
<section id="isdbt-bw"> <section id="DTV_BANDWIDTH_HZ">
<title><constant>DTV_BANDWIDTH_HZ</constant> (optional)</title> <title><constant>DTV_BANDWIDTH_HZ</constant></title>
<para>Possible values:</para> <para>Bandwidth for the channel, in HZ.</para>
<para>For ISDB-T it should be always 6000000Hz (6MHz)</para> <para>Possible values:
<para>For ISDB-Tsb it can vary depending on the number of connected segments</para> <constant>6000000</constant>,
<constant>7000000</constant>,
<constant>8000000</constant>.
</para>
<para>Note: Hardware specific values might be given here, but standard <para>Notes:</para>
applications should not bother to set a value to this field as
standard demods are ignoring it anyway.</para>
<para>Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from <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, other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
DTV_ISDBT_SB_SEGMENT_COUNT).</para> DTV_ISDBT_SB_SEGMENT_COUNT).</para>
</section> </section>
<section id="isdbt-delivery-sys"> <section id="DTV_DELIVERY_SYSTEM">
<title><constant>DTV_DELIVERY_SYSTEM</constant></title> <title><constant>DTV_DELIVERY_SYSTEM</constant></title>
<para>Possible values: <constant>SYS_ISDBT</constant></para> <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,
} fe_delivery_system_t;
</programlisting>
</section> </section>
<section id="isdbt-tx-mode"> <section id="DTV_TRANSMISSION_MODE">
<title><constant>DTV_TRANSMISSION_MODE</constant></title> <title><constant>DTV_TRANSMISSION_MODE</constant></title>
<para>ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called <para>Specifies the number of carriers used by the standard</para>
'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
<para>Possible values: <constant>TRANSMISSION_MODE_2K</constant>, <constant>TRANSMISSION_MODE_8K</constant>, <para>Possible values are:</para>
<constant>TRANSMISSION_MODE_AUTO</constant>, <constant>TRANSMISSION_MODE_4K</constant></para> <programlisting>
typedef enum fe_transmit_mode {
TRANSMISSION_MODE_2K,
TRANSMISSION_MODE_8K,
TRANSMISSION_MODE_AUTO,
TRANSMISSION_MODE_4K
} 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>If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the <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 hardware will try to find the correct FFT-size (if capable) and will
use TMCC to fill in the missing parameters.</para> use TMCC to fill in the missing parameters.</para>
<para><constant>TRANSMISSION_MODE_4K</constant> is added at the same time as the other new parameters.</para>
</section> </section>
<section id="isdbt-guard-interval"> <section id="DTV_GUARD_INTERVAL">
<title><constant>DTV_GUARD_INTERVAL</constant></title> <title><constant>DTV_GUARD_INTERVAL</constant></title>
<para>Possible values: <constant>GUARD_INTERVAL_1_32</constant>, <constant>GUARD_INTERVAL_1_16</constant>, <constant>GUARD_INTERVAL_1_8</constant>, <para>Possible values are:</para>
<constant>GUARD_INTERVAL_1_4</constant>, <constant>GUARD_INTERVAL_AUTO</constant></para> <programlisting>
typedef enum fe_guard_interval {
<para>If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will GUARD_INTERVAL_1_32,
GUARD_INTERVAL_1_16,
GUARD_INTERVAL_1_8,
GUARD_INTERVAL_1_4,
GUARD_INTERVAL_AUTO
} 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 try to find the correct guard interval (if capable) and will use TMCC to fill
in the missing parameters.</para> in the missing parameters.</para>
</section> </section>
</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"> <section id="isdbt-new-parms">
<title>ISDB-T only parameters</title> <title>ISDB-T only parameters</title>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7