tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
[media] DocBook: document DVB net API
The DVB network API was not documented. There are just some
placeholders there.
Replace it by a proper documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
+245
-153
+1
-1
Documentation/DocBook/media/Makefile
+1
-1
Documentation/DocBook/media/Makefile
···
91
91
$(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/ca.h) \
92
92
$(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/dmx.h) \
93
93
$(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/frontend.h) \
94
-
$(shell perl -ne 'print "$$1 " if (/^struct\s+([A-Z][^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/net.h) \
94
+
$(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/ && !/_old/)' $(srctree)/include/uapi/linux/dvb/net.h) \
95
95
$(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \
96
96
$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \
97
97
$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \
+1
-1
Documentation/DocBook/media/dvb/dvbapi.xml
+1
-1
Documentation/DocBook/media/dvb/dvbapi.xml
+228
-146
Documentation/DocBook/media/dvb/net.xml
+228
-146
Documentation/DocBook/media/dvb/net.xml
···
1
1
<title>DVB Network API</title>
2
-
<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets
3
-
received via DVB into the Linux network protocol stack, e.g. for internet via satellite
4
-
applications. It can be accessed through <emphasis role="bold">/dev/dvb/adapter0/net0</emphasis>. Data types and
5
-
and ioctl definitions can be accessed by including <emphasis role="bold">linux/dvb/net.h</emphasis> in your
6
-
application.
7
-
</para>
8
-
<section id="dvb_net_types">
9
-
<title>DVB Net Data Types</title>
2
+
<para>The DVB net device controls the mapping of data packages that are
3
+
part of a transport stream to be mapped into a virtual network interface,
4
+
visible through the standard Linux network protocol stack.</para>
5
+
<para>Currently, two encapsulations are supported:</para>
6
+
<itemizedlist>
7
+
<listitem><para><ulink url="http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation">
8
+
Multi Protocol Encapsulation (MPE)</ulink></para></listitem>
9
+
<listitem><para><ulink url="http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation">
10
+
Ultra Lightweight Encapsulation (ULE)</ulink></para></listitem>
11
+
</itemizedlist>
10
12
11
-
<section id="dvb-net-if">
12
-
<title>struct dvb_net_if</title>
13
-
<programlisting>
14
-
struct dvb_net_if {
15
-
__u16 pid;
16
-
__u16 if_num;
17
-
__u8 feedtype;
18
-
#define DVB_NET_FEEDTYPE_MPE 0 /⋆ multi protocol encapsulation ⋆/
19
-
#define DVB_NET_FEEDTYPE_ULE 1 /⋆ ultra lightweight encapsulation ⋆/
20
-
};
21
-
</programlisting>
22
-
</section>
13
+
<para>In order to create the Linux virtual network interfaces, an application
14
+
needs to tell to the Kernel what are the PIDs and the encapsulation types
15
+
that are present on the transport stream. This is done through
16
+
<emphasis role="bold">/dev/dvb/adapter?/net?</emphasis> device node.
17
+
The data will be available via virtual <constant>dvb?_?</constant>
18
+
network interfaces, and will be controled/routed via the standard
19
+
ip tools (like ip, route, netstat, ifconfig, etc).</para>
20
+
<para> Data types and and ioctl definitions are defined via
21
+
<emphasis role="bold">linux/dvb/net.h</emphasis> header.</para>
23
22
24
-
</section>
25
23
<section id="net_fcalls">
26
24
<title>DVB net Function Calls</title>
27
-
<para>To be written…
28
-
</para>
29
25
30
-
<section id="NET_ADD_IF"
31
-
role="subsection"><title>NET_ADD_IF</title>
32
-
<para>DESCRIPTION
33
-
</para>
34
-
<informaltable><tgroup cols="1"><tbody><row><entry
35
-
align="char">
36
-
<para>This ioctl is undocumented. Documentation is welcome.</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(fd, int request = NET_ADD_IF,
44
-
struct dvb_net_if *if);</para>
45
-
</entry>
46
-
</row></tbody></tgroup></informaltable>
47
-
<para>PARAMETERS
48
-
</para>
49
-
<informaltable><tgroup cols="2"><tbody><row><entry
50
-
align="char">
51
-
<para>int fd</para>
52
-
</entry><entry
53
-
align="char">
54
-
<para>File descriptor returned by a previous call to open().</para>
55
-
</entry>
56
-
</row><row><entry
57
-
align="char">
58
-
<para>int request</para>
59
-
</entry><entry
60
-
align="char">
61
-
<para>Equals NET_ADD_IF for this command.</para>
62
-
</entry>
63
-
</row><row><entry
64
-
align="char">
65
-
<para>struct dvb_net_if *if
66
-
</para>
67
-
</entry><entry
68
-
align="char">
69
-
<para>Undocumented.</para>
70
-
</entry>
71
-
</row></tbody></tgroup></informaltable>
72
-
&return-value-dvb;
73
-
</section>
74
26
75
-
<section id="NET_REMOVE_IF"
76
-
role="subsection"><title>NET_REMOVE_IF</title>
77
-
<para>DESCRIPTION
78
-
</para>
79
-
<informaltable><tgroup cols="1"><tbody><row><entry
80
-
align="char">
81
-
<para>This ioctl is undocumented. Documentation is welcome.</para>
82
-
</entry>
83
-
</row></tbody></tgroup></informaltable>
84
-
<para>SYNOPSIS
85
-
</para>
86
-
<informaltable><tgroup cols="1"><tbody><row><entry
87
-
align="char">
88
-
<para>int ioctl(fd, int request = NET_REMOVE_IF);
89
-
</para>
90
-
</entry>
91
-
</row></tbody></tgroup></informaltable>
92
-
<para>PARAMETERS
93
-
</para>
94
-
<informaltable><tgroup cols="2"><tbody><row><entry
95
-
align="char">
96
-
<para>int fd</para>
97
-
</entry><entry
98
-
align="char">
99
-
<para>File descriptor returned by a previous call to open().</para>
100
-
</entry>
101
-
</row><row><entry
102
-
align="char">
103
-
<para>int request</para>
104
-
</entry><entry
105
-
align="char">
106
-
<para>Equals NET_REMOVE_IF for this command.</para>
107
-
</entry>
108
-
</row></tbody></tgroup></informaltable>
109
-
&return-value-dvb;
110
-
</section>
27
+
<refentry id="NET_ADD_IF">
28
+
<refmeta>
29
+
<refentrytitle>ioctl NET_ADD_IF</refentrytitle>
30
+
&manvol;
31
+
</refmeta>
111
32
112
-
<section id="NET_GET_IF"
113
-
role="subsection"><title>NET_GET_IF</title>
114
-
<para>DESCRIPTION
115
-
</para>
116
-
<informaltable><tgroup cols="1"><tbody><row><entry
117
-
align="char">
118
-
<para>This ioctl is undocumented. Documentation is welcome.</para>
119
-
</entry>
120
-
</row></tbody></tgroup></informaltable>
121
-
<para>SYNOPSIS
122
-
</para>
123
-
<informaltable><tgroup cols="1"><tbody><row><entry
124
-
align="char">
125
-
<para>int ioctl(fd, int request = NET_GET_IF,
126
-
struct dvb_net_if *if);</para>
127
-
</entry>
128
-
</row></tbody></tgroup></informaltable>
129
-
<para>PARAMETERS
130
-
</para>
131
-
<informaltable><tgroup cols="2"><tbody><row><entry
132
-
align="char">
133
-
<para>int fd</para>
134
-
</entry><entry
135
-
align="char">
136
-
<para>File descriptor returned by a previous call to open().</para>
137
-
</entry>
138
-
</row><row><entry
139
-
align="char">
140
-
<para>int request</para>
141
-
</entry><entry
142
-
align="char">
143
-
<para>Equals NET_GET_IF for this command.</para>
144
-
</entry>
145
-
</row><row><entry
146
-
align="char">
147
-
<para>struct dvb_net_if *if
148
-
</para>
149
-
</entry><entry
150
-
align="char">
151
-
<para>Undocumented.</para>
152
-
</entry>
153
-
</row></tbody></tgroup></informaltable>
33
+
<refnamediv>
34
+
<refname>NET_ADD_IF</refname>
35
+
<refpurpose>Creates a new network interface for a given Packet ID.</refpurpose>
36
+
</refnamediv>
37
+
38
+
<refsynopsisdiv>
39
+
<funcsynopsis>
40
+
<funcprototype>
41
+
<funcdef>int <function>ioctl</function></funcdef>
42
+
<paramdef>int <parameter>fd</parameter></paramdef>
43
+
<paramdef>int <parameter>request</parameter></paramdef>
44
+
<paramdef>struct dvb_net_if *<parameter>net_if</parameter></paramdef>
45
+
</funcprototype>
46
+
</funcsynopsis>
47
+
</refsynopsisdiv>
48
+
49
+
<refsect1>
50
+
<title>Arguments</title>
51
+
<variablelist>
52
+
<varlistentry>
53
+
<term><parameter>fd</parameter></term>
54
+
<listitem>
55
+
<para>&fe_fd;</para>
56
+
</listitem>
57
+
</varlistentry>
58
+
<varlistentry>
59
+
<term><parameter>request</parameter></term>
60
+
<listitem>
61
+
<para>FE_SET_TONE</para>
62
+
</listitem>
63
+
</varlistentry>
64
+
<varlistentry>
65
+
<term><parameter>net_if</parameter></term>
66
+
<listitem>
67
+
<para>pointer to &dvb-net-if;</para>
68
+
</listitem>
69
+
</varlistentry>
70
+
</variablelist>
71
+
</refsect1>
72
+
73
+
<refsect1>
74
+
<title>Description</title>
75
+
76
+
<para>The NET_ADD_IF ioctl system call selects the Packet ID (PID) that
77
+
contains a TCP/IP traffic, the type of encapsulation to be used (MPE or ULE)
78
+
and the interface number for the new interface to be created. When the
79
+
system call successfully returns, a new virtual network interface is created.</para>
80
+
<para>The &dvb-net-if;::ifnum field will be filled with the number of the
81
+
created interface.</para>
82
+
154
83
&return-value-dvb;
155
-
</section>
84
+
</refsect1>
85
+
86
+
<refsect1 id="dvb-net-if-t">
87
+
<title>struct <structname>dvb_net_if</structname> description</title>
88
+
89
+
<table pgwide="1" frame="none" id="dvb-net-if">
90
+
<title>struct <structname>dvb_net_if</structname></title>
91
+
<tgroup cols="2">
92
+
&cs-def;
93
+
<thead>
94
+
<row>
95
+
<entry>ID</entry>
96
+
<entry>Description</entry>
97
+
</row>
98
+
</thead>
99
+
<tbody valign="top">
100
+
<row>
101
+
<entry align="char">pid</entry>
102
+
<entry align="char">Packet ID (PID) of the MPEG-TS that contains
103
+
data</entry>
104
+
</row><row>
105
+
<entry align="char">ifnum</entry>
106
+
<entry align="char">number of the DVB interface.</entry>
107
+
</row><row>
108
+
<entry align="char">feedtype</entry>
109
+
<entry align="char">Encapsulation type of the feed. It can be:
110
+
<constant>DVB_NET_FEEDTYPE_MPE</constant> for MPE encoding
111
+
or
112
+
<constant>DVB_NET_FEEDTYPE_ULE</constant> for ULE encoding.
113
+
</entry>
114
+
</row>
115
+
</tbody>
116
+
</tgroup>
117
+
</table>
118
+
</refsect1>
119
+
</refentry>
120
+
121
+
<refentry id="NET_REMOVE_IF">
122
+
<refmeta>
123
+
<refentrytitle>ioctl NET_REMOVE_IF</refentrytitle>
124
+
&manvol;
125
+
</refmeta>
126
+
127
+
<refnamediv>
128
+
<refname>NET_REMOVE_IF</refname>
129
+
<refpurpose>Removes a network interface.</refpurpose>
130
+
</refnamediv>
131
+
132
+
<refsynopsisdiv>
133
+
<funcsynopsis>
134
+
<funcprototype>
135
+
<funcdef>int <function>ioctl</function></funcdef>
136
+
<paramdef>int <parameter>fd</parameter></paramdef>
137
+
<paramdef>int <parameter>request</parameter></paramdef>
138
+
<paramdef>int <parameter>ifnum</parameter></paramdef>
139
+
</funcprototype>
140
+
</funcsynopsis>
141
+
</refsynopsisdiv>
142
+
143
+
<refsect1>
144
+
<title>Arguments</title>
145
+
<variablelist>
146
+
<varlistentry>
147
+
<term><parameter>fd</parameter></term>
148
+
<listitem>
149
+
<para>&fe_fd;</para>
150
+
</listitem>
151
+
</varlistentry>
152
+
<varlistentry>
153
+
<term><parameter>request</parameter></term>
154
+
<listitem>
155
+
<para>FE_SET_TONE</para>
156
+
</listitem>
157
+
</varlistentry>
158
+
<varlistentry>
159
+
<term><parameter>net_if</parameter></term>
160
+
<listitem>
161
+
<para>number of the interface to be removed</para>
162
+
</listitem>
163
+
</varlistentry>
164
+
</variablelist>
165
+
</refsect1>
166
+
167
+
<refsect1>
168
+
<title>Description</title>
169
+
170
+
<para>The NET_REMOVE_IF ioctl deletes an interface previously created
171
+
via &NET-ADD-IF;.</para>
172
+
173
+
&return-value-dvb;
174
+
</refsect1>
175
+
</refentry>
176
+
177
+
178
+
<refentry id="NET_GET_IF">
179
+
<refmeta>
180
+
<refentrytitle>ioctl NET_GET_IF</refentrytitle>
181
+
&manvol;
182
+
</refmeta>
183
+
184
+
<refnamediv>
185
+
<refname>NET_GET_IF</refname>
186
+
<refpurpose>Read the configuration data of an interface created via
187
+
&NET-ADD-IF;.</refpurpose>
188
+
</refnamediv>
189
+
190
+
<refsynopsisdiv>
191
+
<funcsynopsis>
192
+
<funcprototype>
193
+
<funcdef>int <function>ioctl</function></funcdef>
194
+
<paramdef>int <parameter>fd</parameter></paramdef>
195
+
<paramdef>int <parameter>request</parameter></paramdef>
196
+
<paramdef>struct dvb_net_if *<parameter>net_if</parameter></paramdef>
197
+
</funcprototype>
198
+
</funcsynopsis>
199
+
</refsynopsisdiv>
200
+
201
+
<refsect1>
202
+
<title>Arguments</title>
203
+
<variablelist>
204
+
<varlistentry>
205
+
<term><parameter>fd</parameter></term>
206
+
<listitem>
207
+
<para>&fe_fd;</para>
208
+
</listitem>
209
+
</varlistentry>
210
+
<varlistentry>
211
+
<term><parameter>request</parameter></term>
212
+
<listitem>
213
+
<para>FE_SET_TONE</para>
214
+
</listitem>
215
+
</varlistentry>
216
+
<varlistentry>
217
+
<term><parameter>net_if</parameter></term>
218
+
<listitem>
219
+
<para>pointer to &dvb-net-if;</para>
220
+
</listitem>
221
+
</varlistentry>
222
+
</variablelist>
223
+
</refsect1>
224
+
225
+
<refsect1>
226
+
<title>Description</title>
227
+
228
+
<para>The NET_GET_IF ioctl uses the interface number given by the
229
+
&dvb-net-if;::ifnum field and fills the content of &dvb-net-if; with
230
+
the packet ID and encapsulation type used on such interface. If the
231
+
interface was not created yet with &NET-ADD-IF;, it will return -1 and
232
+
fill the <constant>errno</constant> with <constant>EINVAL</constant>
233
+
error code.</para>
234
+
235
+
&return-value-dvb;
236
+
</refsect1>
237
+
</refentry>
156
238
</section>
+15
-5
Documentation/DocBook/media_api.tmpl
+15
-5
Documentation/DocBook/media_api.tmpl
···
95
95
<para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para>
96
96
</preface>
97
97
98
-
<part id="v4l2spec">&sub-v4l2;</part>
99
-
<part id="dvbapi">&sub-dvbapi;</part>
100
-
<part id="remotes">&sub-remote_controllers;</part>
101
-
<part id="media_common">&sub-media-controller;</part>
98
+
<part id="v4l2spec">
99
+
&sub-v4l2;
100
+
</part>
101
+
<part id="dvbapi">
102
+
&sub-dvbapi;
103
+
</part>
104
+
<part id="remotes">
105
+
&sub-remote_controllers;
106
+
</part>
107
+
<part id="media_common">
108
+
&sub-media-controller;
109
+
</part>
102
110
103
-
<chapter id="gen_errors">&sub-gen-errors;</chapter>
111
+
<chapter id="gen_errors">
112
+
&sub-gen-errors;
113
+
</chapter>
104
114
105
115
&sub-fdl-appendix;
106
116