From 315d27aacf1801b009e8f7ec9f92adba6243aec2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 1 Jun 2015 08:56:49 -0300 Subject: [PATCH] [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 --- Documentation/DocBook/media/Makefile | 2 +- Documentation/DocBook/media/dvb/dvbapi.xml | 2 +- Documentation/DocBook/media/dvb/net.xml | 374 ++++++++++++++++++----------- Documentation/DocBook/media_api.tmpl | 20 +- 4 files changed, 245 insertions(+), 153 deletions(-) diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index dbc9a56..ae9d5a0 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -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/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 (/^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/media.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml index dc8cb55..858fd7d 100644 --- a/Documentation/DocBook/media/dvb/dvbapi.xml +++ b/Documentation/DocBook/media/dvb/dvbapi.xml @@ -108,7 +108,7 @@ Added ISDB-T test originally written by Patrick Boettcher &sub-ca; - + &sub-net; diff --git a/Documentation/DocBook/media/dvb/net.xml b/Documentation/DocBook/media/dvb/net.xml index d4ef217..aeac41c 100644 --- a/Documentation/DocBook/media/dvb/net.xml +++ b/Documentation/DocBook/media/dvb/net.xml @@ -1,156 +1,238 @@ DVB Network API -The DVB net device enables feeding of MPE (multi protocol encapsulation) packets -received via DVB into the Linux network protocol stack, e.g. for internet via satellite -applications. It can be accessed through /dev/dvb/adapter0/net0. Data types and -and ioctl definitions can be accessed by including linux/dvb/net.h in your -application. - -
-DVB Net Data Types - -
-struct dvb_net_if - -struct dvb_net_if { - __u16 pid; - __u16 if_num; - __u8 feedtype; -#define DVB_NET_FEEDTYPE_MPE 0 /⋆ multi protocol encapsulation ⋆/ -#define DVB_NET_FEEDTYPE_ULE 1 /⋆ ultra lightweight encapsulation ⋆/ -}; - -
+The DVB net device controls the mapping of data packages that are + part of a transport stream to be mapped into a virtual network interface, + visible through the standard Linux network protocol stack. +Currently, two encapsulations are supported: + + + Multi Protocol Encapsulation (MPE) + + Ultra Lightweight Encapsulation (ULE) + + +In order to create the Linux virtual network interfaces, an application + needs to tell to the Kernel what are the PIDs and the encapsulation types + that are present on the transport stream. This is done through + /dev/dvb/adapter?/net? device node. + The data will be available via virtual dvb?_? + network interfaces, and will be controled/routed via the standard + ip tools (like ip, route, netstat, ifconfig, etc). + Data types and and ioctl definitions are defined via + linux/dvb/net.h header. -
DVB net Function Calls -To be written… - - -
NET_ADD_IF -DESCRIPTION - - -This ioctl is undocumented. Documentation is welcome. - - -SYNOPSIS - - -int ioctl(fd, int request = NET_ADD_IF, - struct dvb_net_if *if); - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals NET_ADD_IF for this command. - - -struct dvb_net_if *if - - -Undocumented. - - + + + + + ioctl NET_ADD_IF + &manvol; + + + + NET_ADD_IF + Creates a new network interface for a given Packet ID. + + + + + + int ioctl + int fd + int request + struct dvb_net_if *net_if + + + + + + Arguments + + + fd + + &fe_fd; + + + + request + + FE_SET_TONE + + + + net_if + + pointer to &dvb-net-if; + + + + + + + Description + +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. +The &dvb-net-if;::ifnum field will be filled with the number of the + created interface. + &return-value-dvb; -
+ + + +struct <structname>dvb_net_if</structname> description + + + struct <structname>dvb_net_if</structname> + + &cs-def; + + + ID + Description + + + + + pid + Packet ID (PID) of the MPEG-TS that contains + data + + ifnum + number of the DVB interface. + + feedtype + Encapsulation type of the feed. It can be: + DVB_NET_FEEDTYPE_MPE for MPE encoding + or + DVB_NET_FEEDTYPE_ULE for ULE encoding. + + + + +
+ + + + + + ioctl NET_REMOVE_IF + &manvol; + + + + NET_REMOVE_IF + Removes a network interface. + + + + + + int ioctl + int fd + int request + int ifnum + + + + + + Arguments + + + fd + + &fe_fd; + + + + request + + FE_SET_TONE + + + + net_if + + number of the interface to be removed + + + + + + + Description + +The NET_REMOVE_IF ioctl deletes an interface previously created + via &NET-ADD-IF;. -
NET_REMOVE_IF -DESCRIPTION - - -This ioctl is undocumented. Documentation is welcome. - - -SYNOPSIS - - -int ioctl(fd, int request = NET_REMOVE_IF); - - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals NET_REMOVE_IF for this command. - - &return-value-dvb; -
+ + + + + + + ioctl NET_GET_IF + &manvol; + + + + NET_GET_IF + Read the configuration data of an interface created via + &NET-ADD-IF;. + + + + + + int ioctl + int fd + int request + struct dvb_net_if *net_if + + + + + + Arguments + + + fd + + &fe_fd; + + + + request + + FE_SET_TONE + + + + net_if + + pointer to &dvb-net-if; + + + + + + + Description + +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 errno with EINVAL + error code. -
NET_GET_IF -DESCRIPTION - - -This ioctl is undocumented. Documentation is welcome. - - -SYNOPSIS - - -int ioctl(fd, int request = NET_GET_IF, - struct dvb_net_if *if); - - -PARAMETERS - - -int fd - -File descriptor returned by a previous call to open(). - - -int request - -Equals NET_GET_IF for this command. - - -struct dvb_net_if *if - - -Undocumented. - - &return-value-dvb; -
+ +
diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl index 1e19451..43eda245 100644 --- a/Documentation/DocBook/media_api.tmpl +++ b/Documentation/DocBook/media_api.tmpl @@ -95,12 +95,22 @@ For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: Linux Media Mailing List (LMML).. -&sub-v4l2; -&sub-dvbapi; -&sub-remote_controllers; -&sub-media-controller; + +&sub-v4l2; + + +&sub-dvbapi; + + +&sub-remote_controllers; + + +&sub-media-controller; + -&sub-gen-errors; + +&sub-gen-errors; + &sub-fdl-appendix; -- 2.7.4