Documentation/linux_tv/media/dvb/net.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _net:
   4
   5 ###############
   6 DVB Network API
   7 ###############
   8 The DVB net device controls the mapping of data packages that are part
   9 of a transport stream to be mapped into a virtual network interface,
  10 visible through the standard Linux network protocol stack.
  11
  12 Currently, two encapsulations are supported:
  13
  14 -  `Multi Protocol Encapsulation (MPE) <http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation>`__
  15
  16 -  `Ultra Lightweight Encapsulation (ULE) <http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation>`__
  17
  18 In order to create the Linux virtual network interfaces, an application
  19 needs to tell to the Kernel what are the PIDs and the encapsulation
  20 types that are present on the transport stream. This is done through
  21 ``/dev/dvb/adapter?/net?`` device node. The data will be available via
  22 virtual ``dvb?_?`` network interfaces, and will be controlled/routed via
  23 the standard ip tools (like ip, route, netstat, ifconfig, etc).
  24
  25 Data types and and ioctl definitions are defined via ``linux/dvb/net.h``
  26 header.
  27
  28
  29 .. _net_fcalls:
  30
  31 ######################
  32 DVB net Function Calls
  33 ######################
  34
  35 .. _NET_ADD_IF:
  36
  37 ****************
  38 ioctl NET_ADD_IF
  39 ****************
  40
  41 *man NET_ADD_IF(2)*
  42
  43 Creates a new network interface for a given Packet ID.
  44
  45
  46 Synopsis
  47 ========
  48
  49 .. cpp:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
  50
  51 Arguments
  52 =========
  53
  54 ``fd``
  55     File descriptor returned by :ref:`open() <frontend_f_open>`.
  56
  57 ``request``
  58     FE_SET_TONE
  59
  60 ``net_if``
  61     pointer to struct :ref:`dvb_net_if <dvb-net-if>`
  62
  63
  64 Description
  65 ===========
  66
  67 The NET_ADD_IF ioctl system call selects the Packet ID (PID) that
  68 contains a TCP/IP traffic, the type of encapsulation to be used (MPE or
  69 ULE) and the interface number for the new interface to be created. When
  70 the system call successfully returns, a new virtual network interface is
  71 created.
  72
  73 The struct :ref:`dvb_net_if <dvb-net-if>`::ifnum field will be
  74 filled with the number of the created interface.
  75
  76 RETURN VALUE
  77
  78 On success 0 is returned, on error -1 and the ``errno`` variable is set
  79 appropriately. The generic error codes are described at the
  80 :ref:`Generic Error Codes <gen-errors>` chapter.
  81
  82
  83 .. _dvb-net-if-t:
  84
  85 struct dvb_net_if description
  86 =============================
  87
  88
  89 .. _dvb-net-if:
  90
  91 .. flat-table:: struct dvb_net_if
  92     :header-rows:  1
  93     :stub-columns: 0
  94
  95
  96     -  .. row 1
  97
  98        -  ID
  99
 100        -  Description
 101
 102     -  .. row 2
 103
 104        -  pid
 105
 106        -  Packet ID (PID) of the MPEG-TS that contains data
 107
 108     -  .. row 3
 109
 110        -  ifnum
 111
 112        -  number of the DVB interface.
 113
 114     -  .. row 4
 115
 116        -  feedtype
 117
 118        -  Encapsulation type of the feed. It can be:
 119           ``DVB_NET_FEEDTYPE_MPE`` for MPE encoding or
 120           ``DVB_NET_FEEDTYPE_ULE`` for ULE encoding.
 121
 122
 123
 124 .. _NET_REMOVE_IF:
 125
 126 *******************
 127 ioctl NET_REMOVE_IF
 128 *******************
 129
 130 *man NET_REMOVE_IF(2)*
 131
 132 Removes a network interface.
 133
 134
 135 Synopsis
 136 ========
 137
 138 .. cpp:function:: int ioctl( int fd, int request, int ifnum )
 139
 140 Arguments
 141 =========
 142
 143 ``fd``
 144     File descriptor returned by :ref:`open() <frontend_f_open>`.
 145
 146 ``request``
 147     FE_SET_TONE
 148
 149 ``net_if``
 150     number of the interface to be removed
 151
 152
 153 Description
 154 ===========
 155
 156 The NET_REMOVE_IF ioctl deletes an interface previously created via
 157 :ref:`NET_ADD_IF <net>`.
 158
 159 RETURN VALUE
 160
 161 On success 0 is returned, on error -1 and the ``errno`` variable is set
 162 appropriately. The generic error codes are described at the
 163 :ref:`Generic Error Codes <gen-errors>` chapter.
 164
 165
 166 .. _NET_GET_IF:
 167
 168 ****************
 169 ioctl NET_GET_IF
 170 ****************
 171
 172 *man NET_GET_IF(2)*
 173
 174 Read the configuration data of an interface created via
 175 :ref:`NET_ADD_IF <net>`.
 176
 177
 178 Synopsis
 179 ========
 180
 181 .. cpp:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
 182
 183 Arguments
 184 =========
 185
 186 ``fd``
 187     File descriptor returned by :ref:`open() <frontend_f_open>`.
 188
 189 ``request``
 190     FE_SET_TONE
 191
 192 ``net_if``
 193     pointer to struct :ref:`dvb_net_if <dvb-net-if>`
 194
 195
 196 Description
 197 ===========
 198
 199 The NET_GET_IF ioctl uses the interface number given by the struct
 200 :ref:`dvb_net_if <dvb-net-if>`::ifnum field and fills the content of
 201 struct :ref:`dvb_net_if <dvb-net-if>` with the packet ID and
 202 encapsulation type used on such interface. If the interface was not
 203 created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill
 204 the ``errno`` with ``EINVAL`` error code.
 205
 206 RETURN VALUE
 207
 208 On success 0 is returned, on error -1 and the ``errno`` variable is set
 209 appropriately. The generic error codes are described at the
 210 :ref:`Generic Error Codes <gen-errors>` chapter.
 211
 212
 213 .. ------------------------------------------------------------------------------
 214 .. This file was automatically converted from DocBook-XML with the dbxml
 215 .. library (https://github.com/return42/sphkerneldoc). The origin XML comes
 216 .. from the linux kernel, refer to:
 217 ..
 218 .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
 219 .. ------------------------------------------------------------------------------