| blob | ca77bb62fd8f91ac151edc4a7c9aee3be5e37f49 |
1 DVBAPI
2 ======
3 DVB API stands for Linux DVB Application Programming Interface, so in short it is a set of API calls which are used on
4 linux to handle DVB hardware. From the OSCam point of view the most interesting part is to be able to provide all data
5 necessary for channel decryption. The OSCam DVBAPI module was written to handle this work.
7 Architecture
8 ============
9 A DVBAPI module needs the following information to decrypt a channel:
10 - PMT table (information from TV receiver software about the requested channel for livetv/recording and the ECM PIDs)
11 - CAT table (needed to get information about EMM type and PIDs)
12 - Filtered ECM/EMM data
14 If OSCam is able to decrypt a service, information about the decrypted PIDs (audio, video, etc) and CW (keys)
15 is sent back to the TV receiver software from the CAM device.
17 History
18 =======
19 The first and "standard" use case is probably Enigma. OSCam creates a /tmp/camd.socket. Enigma sends the PMT data to
20 this socket and as a result OSCam opens the necessary DVB demux devices (e.g. /dev/dvb/adapter0/demux0) and filters
21 for ECM, CAT and EMM data. These data are then parsed by the OSCam dvbapi module and as a result the CA_SET_PID and
22 CA_SET_DESCR ioctl calls are made, leading to proper decryption. All this was working on the same hardware and the
23 same DVB devices were used. This kind of usage was mainly for linux STB.
25 Next step was generic PC support, by extending the dvbapi module to send PIDs and keys back to TV software (initially
26 via a special UDP socket, later via the same /tmp/camd.socket). The TV software was able to use this information in
27 software decryption (DeCSA).
29 At some point, the OpenPLi team created a new CaPMT interface, which was then implemented in OSCam (as pmt_mode=6).
30 It is described here: http://wiki.openpli.org/caPMT
31 The main feature was reverting the roles: OSCam now acts as a client and connects to /tmp/.listen.camd.socket created
32 by Enigma. This way multiple Software CAMs could be running and connecting to Enigma's .listen.camd.socket. Another
33 important improvement in this mode (also implemented in OSCam) was the ability to handle extra CA_PMT list managements.
34 This allows to use one socket connection to handle more than one channel at a time (previously clients had to manage
35 a single connection to /tmp/camd.socket per subscribed channel).
37 As the .listen.camd.socket mode makes less sense on generic PC platform (the OSCam is still server, while the client
38 could be any PC software used), the second feature which allows handling multiple channels on single socket connection
39 was extended to cover other modes (not only pmt_mode=6) in OSCam.
41 Network mode
42 ============
43 The last feature that was added was a network mode. The change was made to be able to connect to an OSCam instance
44 which is not running on the same machine where the TV receiver software (and a DVB hardware) runs.
46 Why not use dedicated protocols like newcamd/camd in such cases?
47 - To have ECM/EMM handling in OSCam, where it belongs. It is better maintained and fixes come in quicker.
48 - OSCam knows what readers it has, so it could do load balance/filtering/priorities etc.
50 As a result, instead of /tmp/camd.socket (which could be used only on the same machine) a listening_socket parameter
51 was added. So the unix domain socket switched to a fully-featured TCP socket which can be connected from any network
52 client.
54 As a result besides CA_SET_PID and CA_SET_DESCR new calls were passed to socket: DMX_SET_FILTER and DMX_STOP. The TV
55 receiver software has to filter the demux itself (according to the new calls above) and send results like ECM/EMM/CAT
56 data back to OSCam using the same connection. Because OSCam was only aware of PMT data on the socket, a new
57 DVBAPI_FILTER_DATA command (0xffff0000) was added to handle client data from filters.
59 This way, communication between the TV receiver software and OSCam could be finally done using only one single TCP
60 connection. Moreover, the demux is only accessed by a single TV receiver software process, which from the architecture's
61 point of view is definitely a better solution.
63 New protocol description (socket commands)
64 ===========================================
65 As there are more and more dvbapi clients, some problems start to appear. First of all there was some kind of mess
66 because OSCam's network mode doesn't take into account the endianness in first form of the network protocol. Second,
67 it was not consistant (e.g. PID was always send as little endian in DMX_STOP, while the rest depend on OSCam's host
68 architecture). Finally the standard API ioctl codes for CA_SET_PID, CA_SET_DESCR, DMX_SET_FILTER and DMX_STOP behave
69 differently. These codes are composed by a macro which takes into account the length of the associated structures and
70 on some hardware the first bits of the MSB was different. So the clients had to do some strange workarounds with
71 the MSB byte: fix 0x80 -> 0x40 and 0x20 -> 0x00 when needed
73 Finally, the first byte sent to client was an adapter index, which was not always needed in all commands. Now the
74 first 4-byte integer is unique operation code, so a client will know what is the request type and could read the rest
75 of data according to the following description (and field sizes).
77 To address all above problems and additionally make smooth transitions when updating the protocol in the future there
78 was added some kind of "handshake" for clients. All new implementations should use it. Currently the old and new
79 implementations should work fine, but in the future a network client which will not introduce itself (thus not providing
80 it's supported protocol version) may be dropped/ignored by OSCam.
82 All multibyte integers (if not specified otherwise) should be send using network byte order, so your client should use
83 ntoh() functions when receiving. OSCam is doing hton() before sending and vice versa.
85 Just right after a client connects to an OSCam network socket, it should send a greeting in format:
87 -= DVBAPI_CLIENT_INFO =-
88 -----------------------------------------------------------------------
89 type/size description
90 -----------------------------------------------------------------------
91 uint32_t operation code -> DVBAPI_CLIENT_INFO
92 uint16_t protocol version supported by client
93 uint8_t size of followed string (255 bytes max)
94 string name and version of the client (string length should be max 255 bytes)
96 The server will respond with a similar reply:
98 -= DVBAPI_SERVER_INFO =-
99 -----------------------------------------------------------------------
100 type/size description
101 -----------------------------------------------------------------------
102 uint32_t operation code -> DVBAPI_SERVER_INFO
103 uint16_t protocol version supported by OSCam
104 uint8_t size of followed string (255 bytes max)
105 string OSCam version and build (string length should be max 255 bytes)
107 Next, when a client wants to start a channel, it should send the PMT data (program map table). The PMT data structure
108 starts with constant AOT_CA_PMT (0x9F8032). The data format of the CA_PMT is described in chapter 8.4.3.4 (page 30) of
109 the EN 50221 PDF (european standard).
111 -------------------------------------------------------------------------------
113 Please note that OSCam is expecting a number of private descriptors injected
114 into the CA PMT data. They shall be located inside the program info loop. All
115 supported descriptors follow the structure defined in 2.6 of Rec. ITU H.222.0
116 and they are the following:
118 ---------------------------------------------------------------------
119 | descriptor_tag | Identification | Usage |
120 ---------------------------------------------------------------------
121 | 0x81 | enigma_namespace_descriptor | optional |
122 | 0x82 | demux_ca_mask_device_descriptor | deprecated |
123 | 0x83 | adapter_device_descriptor | mandatory |
124 | 0x84 | pmt_pid_descriptor | mandatory |
125 | 0x85 | service_type_mask_descriptor | optional |
126 | 0x86 | demux_device_descriptor | mandatory |
127 | 0x87 | ca_device_descriptor | mandatory |
128 ---------------------------------------------------------------------
130 Descriptors marked as "mandatory" shall be present in the CA PMT message, in
131 order OSCam to get all necessary information for the specified program. Below
132 is a detailed description for each of the supported descriptors with its
133 structure and usage.
135 -------------------------------------------------------------------------------
137 1. Enigma namespace descriptor
139 Provides additional information for the program specified, such as enigma
140 namespace (orbital position, frequency and polarization), transport stream id
141 and original network id. Although its presense in the CA PMT is optional, it
142 is advised to be included as OSCam utilizes these information in many aspects.
144 ---------------------------------------------------------------------
145 | Syntax | No. of bits | Mnemonic |
146 ---------------------------------------------------------------------
147 | enigma_namespace_descriptor(){ | | |
148 | descriptor_tag | 8 | uimsbf |
149 | descriptor_length | 8 | uimsbf |
150 | enigma_namespace | 32 | uimsbf |
151 | transport_stream_id | 16 | uimsbf |
152 | original_network_id | 16 | uimsbf |
153 | } | | |
154 ---------------------------------------------------------------------
156 decriptor_tag - The tag of the descriptor is equal to 0x81.
158 descriptor_length - The length of the descriptor is equal to 0x08.
160 ens - This is the enigma namespace as defined in OpenPLi, openATV and other
161 open enigma2 images. An example implementation can be found at:
162 https://github.com/OpenPLi/enigma2/blob/develop/lib/dvb/frontend.cpp#L476
164 transport_stream_id – The transport stream id as defined in various DVB SI
165 tables.
167 original_network_id - The original network id as defined in various DVB SI
168 tables.
170 -------------------------------------------------------------------------------
172 2. Demux and ca mask device descriptor
174 It was used to provide information about the demux device as well as the ca
175 device(s) carrying the specified program. It was created for the DM7025 set top
176 box and it is now considered deprecated. Many hosts use this descriptor in a
177 different way (carrying different information) than it was originaly designed
178 leading to confusion. OSCam will continue to support this descriptor as some
179 legacy hosts still use it. For newer hosts, the adapter_device_descriptor (tag
180 0x83), the demux_device_descriptor (tag 0x86) and the ca_device_descriptor (tag
181 0x87) shall be used for sending the necessary data to OSCam.
183 ---------------------------------------------------------------------
184 | Syntax | No. of bits | Mnemonic |
185 ---------------------------------------------------------------------
186 | demux_ca_mask_device_descriptor(){ | | |
187 | descriptor_tag | 8 | uimsbf |
188 | descriptor_length | 8 | uimsbf |
189 | ca_mask | 8 | uimsbf |
190 | demux_device | 8 | uimsbf |
191 | } | | |
192 ---------------------------------------------------------------------
194 decriptor_tag - The tag of the descriptor is equal to 0x82.
196 descriptor_length - The length of the descriptor is equal to 0x02.
198 ca_mask - It is a bit mask of the ca device(s) carrying the specified program.
199 Bit 0 corresonds to ca0, bit 1 corresponds to ca1 and so on.
201 demux_device - The demux device that carries the specified program. It is
202 limited to values between 0x00 and 0x08 in older enigma2 images.
204 -------------------------------------------------------------------------------
206 3. Adapter device descriptor
208 Provides information about the adapter device carrying the specified program.
210 ---------------------------------------------------------------------
211 | Syntax | No. of bits | Mnemonic |
212 ---------------------------------------------------------------------
213 | adapter_device_descriptor(){ | | |
214 | descriptor_tag | 8 | uimsbf |
215 | descriptor_length | 8 | uimsbf |
216 | adapter_device | 8 | uimsbf |
217 | } | | |
218 ---------------------------------------------------------------------
220 decriptor_tag - The tag of the descriptor is equal to 0x83.
222 descriptor_length - The length of the descriptor is equal to 0x01.
224 adapter_device - The adapter device that carries the specified program. It can
225 take values from 0x00 to 0xFF, thus a maximum number of different 256 adapters
226 are supported.
228 -------------------------------------------------------------------------------
230 4. PMT pid descriptor
232 Provides information about the PMT pid of the specified program.
234 ---------------------------------------------------------------------
235 | Syntax | No. of bits | Mnemonic |
236 ---------------------------------------------------------------------
237 | pmt_pid_descriptor(){ | | |
238 | descriptor_tag | 8 | uimsbf |
239 | descriptor_length | 8 | uimsbf |
240 | pmt_pid | 16 | uimsbf |
241 | } | | |
242 ---------------------------------------------------------------------
244 decriptor_tag - The tag of the descriptor is equal to 0x84.
246 descriptor_length - The length of the descriptor is equal to 0x02.
248 pmt_pid - The pid that carries the PMT table of the specified program.
250 -------------------------------------------------------------------------------
252 5. Service type mask descriptor
254 It provides information about the type (live tv, recording, streaming service,
255 or any combination) of the program specified. It's currently not unitilized in
256 OSCam and its usage in considered optional.
258 ---------------------------------------------------------------------
259 | Syntax | No. of bits | Mnemonic |
260 ---------------------------------------------------------------------
261 | service_type_mask_descriptor(){ | | |
262 | descriptor_tag | 8 | uimsbf |
263 | descriptor_length | 8 | uimsbf |
264 | service_type_mask | 32 | uimsbf |
265 | } | | |
266 ---------------------------------------------------------------------
268 decriptor_tag - The tag of the descriptor is equal to 0x85.
270 descriptor_length - The length of the descriptor is equal to 0x04.
272 service_type_mask - This is a bit mask of the different service types enabled
273 for the specified program. Service type values are defined in enigma2 and can
274 be found at https://github.com/OpenPLi/enigma2/blob/develop/lib/dvb/pmt.h#L135
276 -------------------------------------------------------------------------------
278 6. Demux device descriptor
280 It is used to provide information about the demux device carrying the specified
281 program. It is a replacement to the deprecated demux_ca_mask_device_descriptor
282 (tag 0x82), as it supports up to 256 different demux devices.
284 ---------------------------------------------------------------------
285 | Syntax | No. of bits | Mnemonic |
286 ---------------------------------------------------------------------
287 | demux_device_descriptor(){ | | |
288 | descriptor_tag | 8 | uimsbf |
289 | descriptor_length | 8 | uimsbf |
290 | demux_device | 8 | uimsbf |
291 | } | | |
292 ---------------------------------------------------------------------
294 decriptor_tag - The tag of the descriptor is equal to 0x86.
296 descriptor_length - The length of the descriptor is equal to 0x01.
298 demux_device - The demux device that carries the specified program. Its value
299 can be between 0x00 and 0xFF.
301 -------------------------------------------------------------------------------
303 7. Ca device descriptor
305 This descriptor provides OSCam with information about the ca device carrying
306 the specified program. It is created as a replacement to the deprecated
307 demux_ca_mask_device_descriptor (tag 0x82). It has the following syntax:
309 ---------------------------------------------------------------------
310 | Syntax | No. of bits | Mnemonic |
311 ---------------------------------------------------------------------
312 | ca_device_descriptor(){ | | |
313 | descriptor_tag | 8 | uimsbf |
314 | descriptor_length | 8 | uimsbf |
315 | ca_device | 8 | uimsbf |
316 | } | | |
317 ---------------------------------------------------------------------
319 decriptor_tag - The tag of the descriptor is equal to 0x87.
321 descriptor_length - The length of the descriptor is equal to 0x01.
323 ca_device - The ca device that carries the specified program. Its value can be
324 between 0x00 and 0xFF (256 different ca devices supported).
326 -------------------------------------------------------------------------------
328 After OSCam parses the PMT data, it starts filtering ECM PIDs. It sends the following request to the client:
330 -= DVBAPI_DMX_SET_FILTER =-
331 -----------------------------------------------------------------------
332 type/size description
333 -----------------------------------------------------------------------
334 uint32_t operation code -> DVBAPI_DMX_SET_FILTER
335 uint8_t adapter index
336 uint8_t demux index
337 uint8_t filter number
338 *** The following data are the fields from the dmx_sct_filter_params structure (added separately to avoid padding problems)
339 uint16_t pid
340 uint8_t[16] filter data (filter.filter)
341 uint8_t[16] filter mask (filter.mask)
342 uint8_t[16] filter mode (filter.mode)
343 uint32_t timeout
344 uint32_t flags
346 The client should then filter the data and pass it back to OSCam using the following frame:
348 -= DVBAPI_FILTER_DATA =-
349 -----------------------------------------------------------------------
350 type/size description
351 -----------------------------------------------------------------------
352 uint32_t operation code -> DVBAPI_FILTER_DATA
353 uint8_t demux index
354 uint8_t filter number
355 uint8_t[] filtered data from demux
357 When OSCam is able to decrypt a channel, it initially sends a list of PIDs associated with the descrambler index using
358 this packet:
360 -= DVBAPI_CA_SET_PID =-
361 -----------------------------------------------------------------------
362 type/size description
363 -----------------------------------------------------------------------
364 uint32_t operation code -> DVBAPI_CA_SET_PID
365 uint8_t adapter index
366 ca_pid_t 8-byte ca_pid_t structure (the pid and index fields are in network byte order)
368 And also sends the CW for decryption:
370 -= DVBAPI_CA_SET_DESCR =-
371 -----------------------------------------------------------------------
372 type/size description
373 -----------------------------------------------------------------------
374 uint32_t operation code -> DVBAPI_CA_SET_DESCR
375 uint8_t adapter index
376 ca_descr_t 16-byte ca_descr_t structure (the index and parity fields are in network byte order)
378 When OSCam wants to inform the client about stopping a filter, it sends the following packet:
380 -= DVBAPI_DMX_STOP =-
381 -----------------------------------------------------------------------
382 type/size description
383 -----------------------------------------------------------------------
384 uint32_t operation code -> DVBAPI_DMX_STOP
385 uint8_t adapter index
386 uint8_t demux index
387 uint8_t filter number
388 uint16_t PID to stop filtering
390 When the client closes connection, all associated channels are stopped in OSCam.
392 Alternatively when there is a need to stop channel decoding, while having the connection still open you can send a
393 special '3f' packed to OSCam. To stop decoding the specified demux, the following CA_PMT data should be sent to OSCam:
394 9F 80 3f 04 83 02 00 <demux index>
395 If <demux index> is 0xff, then it is parsed as a wildcard and all demuxers associated with the connection are stopped.
397 In protocol version 2 the new packet with ECM info data was introduced:
399 -= DVBAPI_ECM_INFO =-
400 -----------------------------------------------------------------------
401 type/size description
402 -----------------------------------------------------------------------
403 uint32_t operation code -> DVBAPI_ECM_INFO
404 uint8_t adapter index
405 uint16_t Service ID
406 uint16_t CAID
407 uint16_t PID
408 uint32_t Provider ID
409 uint32_t ECM time (ms)
410 uint8_t size of followed string (255 bytes max)
411 string cardsystem name (string length should be max 255 bytes)
412 uint8_t size of followed string (255 bytes max)
413 string reader name (string length should be max 255 bytes)
414 uint8_t size of followed string (255 bytes max)
415 string from - source name (string length should be max 255 bytes)
416 uint8_t size of followed string (255 bytes max)
417 string protocol name (string length should be max 255 bytes)
418 uint8_t hops (cccam & gbox; set to 0 otherwise)