Skip to content

L
linux
Commit 315d27aa authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files
Options

[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: default avatarMauro Carvalho Chehab <mchehab@osg.samsung.com>
parent 839aa56d
Show whitespace changes
Inline Side-by-side
Showing with 245 additions and 153 deletions
Documentation/DocBook/media/Makefile
View file @ 315d27aa
...@@ -91,7 +91,7 @@ STRUCTS = \ ...@@ -91,7 +91,7 @@ STRUCTS = \
$(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/ca.h) \ $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/ca.h) \
$(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/dmx.h) \ $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/dmx.h) \
$(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/frontend.h) \ $(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/frontend.h) \
$(shell perl -ne 'print "$$1 " if (/^struct\s+([A-Z][^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/net.h) \ $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/ && !/_old/)' $(srctree)/include/uapi/linux/dvb/net.h) \
$(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \ $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \
$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \
$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \
......
Documentation/DocBook/media/dvb/dvbapi.xml
View file @ 315d27aa
...@@ -108,7 +108,7 @@ Added ISDB-T test originally written by Patrick Boettcher ...@@ -108,7 +108,7 @@ Added ISDB-T test originally written by Patrick Boettcher
<chapter id="dvb_ca"> <chapter id="dvb_ca">
&sub-ca; &sub-ca;
</chapter> </chapter>
<chapter id="dvb_net"> <chapter id="net">
&sub-net; &sub-net;
</chapter> </chapter>
<chapter id="legacy_dvb_apis"> <chapter id="legacy_dvb_apis">
......
Documentation/DocBook/media/dvb/net.xml
View file @ 315d27aa
<title>DVB Network API</title> <title>DVB Network API</title>
<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets <para>The DVB net device controls the mapping of data packages that are
received via DVB into the Linux network protocol stack, e.g. for internet via satellite part of a transport stream to be mapped into a virtual network interface,
applications. It can be accessed through <emphasis role="bold">/dev/dvb/adapter0/net0</emphasis>. Data types and visible through the standard Linux network protocol stack.</para>
and ioctl definitions can be accessed by including <emphasis role="bold">linux/dvb/net.h</emphasis> in your <para>Currently, two encapsulations are supported:</para>
application. <itemizedlist>
</para> <listitem><para><ulink url="http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation">
<section id="dvb_net_types"> Multi Protocol Encapsulation (MPE)</ulink></para></listitem>
<title>DVB Net Data Types</title> <listitem><para><ulink url="http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation">
Ultra Lightweight Encapsulation (ULE)</ulink></para></listitem>
<section id="dvb-net-if"> </itemizedlist>
<title>struct dvb_net_if</title>
<programlisting> <para>In order to create the Linux virtual network interfaces, an application
struct dvb_net_if { needs to tell to the Kernel what are the PIDs and the encapsulation types
__u16 pid; that are present on the transport stream. This is done through
__u16 if_num; <emphasis role="bold">/dev/dvb/adapter?/net?</emphasis> device node.
__u8 feedtype; The data will be available via virtual <constant>dvb?_?</constant>
#define DVB_NET_FEEDTYPE_MPE 0 /&#x22C6; multi protocol encapsulation &#x22C6;/ network interfaces, and will be controled/routed via the standard
#define DVB_NET_FEEDTYPE_ULE 1 /&#x22C6; ultra lightweight encapsulation &#x22C6;/ ip tools (like ip, route, netstat, ifconfig, etc).</para>
}; <para> Data types and and ioctl definitions are defined via
</programlisting> <emphasis role="bold">linux/dvb/net.h</emphasis> header.</para>
</section>
</section>
<section id="net_fcalls"> <section id="net_fcalls">
<title>DVB net Function Calls</title> <title>DVB net Function Calls</title>
<para>To be written&#x2026;
</para>
<refentry id="NET_ADD_IF">
<section id="NET_ADD_IF" <refmeta>
role="subsection"><title>NET_ADD_IF</title> <refentrytitle>ioctl NET_ADD_IF</refentrytitle>
<para>DESCRIPTION &manvol;
</para> </refmeta>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char"> <refnamediv>
<para>This ioctl is undocumented. Documentation is welcome.</para> <refname>NET_ADD_IF</refname>
</entry> <refpurpose>Creates a new network interface for a given Packet ID.</refpurpose>
</row></tbody></tgroup></informaltable> </refnamediv>
<para>SYNOPSIS
</para> <refsynopsisdiv>
<informaltable><tgroup cols="1"><tbody><row><entry <funcsynopsis>
align="char"> <funcprototype>
<para>int ioctl(fd, int request = NET_ADD_IF, <funcdef>int <function>ioctl</function></funcdef>
struct dvb_net_if *if);</para> <paramdef>int <parameter>fd</parameter></paramdef>
</entry> <paramdef>int <parameter>request</parameter></paramdef>
</row></tbody></tgroup></informaltable> <paramdef>struct dvb_net_if *<parameter>net_if</parameter></paramdef>
<para>PARAMETERS </funcprototype>
</para> </funcsynopsis>
<informaltable><tgroup cols="2"><tbody><row><entry </refsynopsisdiv>
align="char">
<para>int fd</para> <refsect1>
</entry><entry <title>Arguments</title>
align="char"> <variablelist>
<para>File descriptor returned by a previous call to open().</para> <varlistentry>
</entry> <term><parameter>fd</parameter></term>
</row><row><entry <listitem>
align="char"> <para>&fe_fd;</para>
<para>int request</para> </listitem>
</entry><entry </varlistentry>
align="char"> <varlistentry>
<para>Equals NET_ADD_IF for this command.</para> <term><parameter>request</parameter></term>
</entry> <listitem>
</row><row><entry <para>FE_SET_TONE</para>
align="char"> </listitem>
<para>struct dvb_net_if *if </varlistentry>
</para> <varlistentry>
</entry><entry <term><parameter>net_if</parameter></term>
align="char"> <listitem>
<para>Undocumented.</para> <para>pointer to &dvb-net-if;</para>
</entry> </listitem>
</row></tbody></tgroup></informaltable> </varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>The NET_ADD_IF ioctl system call selects the Packet ID (PID) that
contains a TCP/IP traffic, the type of encapsulation to be used (MPE or ULE)
and the interface number for the new interface to be created. When the
system call successfully returns, a new virtual network interface is created.</para>
<para>The &dvb-net-if;::ifnum field will be filled with the number of the
created interface.</para>
&return-value-dvb; &return-value-dvb;
</section> </refsect1>
<refsect1 id="dvb-net-if-t">
<title>struct <structname>dvb_net_if</structname> description</title>
<table pgwide="1" frame="none" id="dvb-net-if">
<title>struct <structname>dvb_net_if</structname></title>
<tgroup cols="2">
&cs-def;
<thead>
<row>
<entry>ID</entry>
<entry>Description</entry>
</row>
</thead>
<tbody valign="top">
<row>
<entry align="char">pid</entry>
<entry align="char">Packet ID (PID) of the MPEG-TS that contains
data</entry>
</row><row>
<entry align="char">ifnum</entry>
<entry align="char">number of the DVB interface.</entry>
</row><row>
<entry align="char">feedtype</entry>
<entry align="char">Encapsulation type of the feed. It can be:
<constant>DVB_NET_FEEDTYPE_MPE</constant> for MPE encoding
or
<constant>DVB_NET_FEEDTYPE_ULE</constant> for ULE encoding.
</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
</refentry>
<refentry id="NET_REMOVE_IF">
<refmeta>
<refentrytitle>ioctl NET_REMOVE_IF</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>NET_REMOVE_IF</refname>
<refpurpose>Removes a network interface.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>int <parameter>ifnum</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fe_fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>FE_SET_TONE</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>net_if</parameter></term>
<listitem>
<para>number of the interface to be removed</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>The NET_REMOVE_IF ioctl deletes an interface previously created
via &NET-ADD-IF;.</para>
<section id="NET_REMOVE_IF"
role="subsection"><title>NET_REMOVE_IF</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl is undocumented. Documentation is welcome.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl(fd, int request = NET_REMOVE_IF);
</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 NET_REMOVE_IF for this command.</para>
</entry>
</row></tbody></tgroup></informaltable>
&return-value-dvb; &return-value-dvb;
</section> </refsect1>
</refentry>
<refentry id="NET_GET_IF">
<refmeta>
<refentrytitle>ioctl NET_GET_IF</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>NET_GET_IF</refname>
<refpurpose>Read the configuration data of an interface created via
&NET-ADD-IF;.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>struct dvb_net_if *<parameter>net_if</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>&fe_fd;</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>FE_SET_TONE</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>net_if</parameter></term>
<listitem>
<para>pointer to &dvb-net-if;</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>The NET_GET_IF ioctl uses the interface number given by the
&dvb-net-if;::ifnum field and fills the content of &dvb-net-if; with
the packet ID and encapsulation type used on such interface. If the
interface was not created yet with &NET-ADD-IF;, it will return -1 and
fill the <constant>errno</constant> with <constant>EINVAL</constant>
error code.</para>
<section id="NET_GET_IF"
role="subsection"><title>NET_GET_IF</title>
<para>DESCRIPTION
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>This ioctl is undocumented. Documentation is welcome.</para>
</entry>
</row></tbody></tgroup></informaltable>
<para>SYNOPSIS
</para>
<informaltable><tgroup cols="1"><tbody><row><entry
align="char">
<para>int ioctl(fd, int request = NET_GET_IF,
struct dvb_net_if *if);</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 NET_GET_IF for this command.</para>
</entry>
</row><row><entry
align="char">
<para>struct dvb_net_if *if
</para>
</entry><entry
align="char">
<para>Undocumented.</para>
</entry>
</row></tbody></tgroup></informaltable>
&return-value-dvb; &return-value-dvb;
</section> </refsect1>
</refentry>
</section> </section>
Documentation/DocBook/media_api.tmpl
View file @ 315d27aa
...@@ -95,12 +95,22 @@ ...@@ -95,12 +95,22 @@
<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> <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>
</preface> </preface>
<part id="v4l2spec">&sub-v4l2;</part> <part id="v4l2spec">
<part id="dvbapi">&sub-dvbapi;</part> &sub-v4l2;
<part id="remotes">&sub-remote_controllers;</part> </part>
<part id="media_common">&sub-media-controller;</part> <part id="dvbapi">
&sub-dvbapi;
</part>
<part id="remotes">
&sub-remote_controllers;
</part>
<part id="media_common">
&sub-media-controller;
</part>
<chapter id="gen_errors">&sub-gen-errors;</chapter> <chapter id="gen_errors">
&sub-gen-errors;
</chapter>
&sub-fdl-appendix; &sub-fdl-appendix;
......
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