source: trunk/README.dvbapi_protocol@ 10652

Last change on this file since 10652 was 10652, checked in by manio, 7 years ago

dvbapi: add support for ECMINFO in network mode (bump proto to v2)

File size: 11.6 KB
Line 
1DVBAPI
2======
3DVB API stands for Linux DVB Application Programming Interface, so in short it is a set of API calls which is used on
4linux to handle DVB hardware. From the OSCam point of view the most interesting part is to be able to provide all data
5necessary for channel decryption. The OSCam DVBAPI module was written to handle this work.
6
7Architecture
8============
9Basically to be able to decrypt a channel a DVBAPI module needs the following information:
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
13
14As a result if OSCam is able to decrypt a service, an information with the decrypted PIDs (audio, video, etc)
15and CW (keys) are sent back to the TV receiver software or a CAM device.
16
17History
18=======
19The first and "standard" use case is probably the Enigma. OSCam is creating a /tmp/camd.socket. Enigma is sending the
20PMT data to this socket and as a result OSCam is opening the necessary DVB demux devices (eg /dev/dvb/adapter0/demux0)
21and is filtering for ECM, CAT and EMM data. It is then parsed by the OSCam dvbapi module and as a result the CA_SET_PID
22and CA_SET_DESCR ioctl calls was done leading to proper decryption. It was all working on same hardware and the same DVB
23devices was used. This kind of usage was mainly for linux STB.
24
25Next step was the generic PC support. It was extending the dvbapi module to be able to send PIDs and keys back to
26TV software (firstly via specially created UDP socket, later via the same /tmp/camd.socket).
27The TV software was able to use this information in software decrypting (DeCSA).
28
29After some time the OpenPLi team created a new CaPMT interface, which was then implemented in OSCam (as pmt_mode=6).
30It is described here: http://wiki.openpli.org/caPMT
31The main feature was reverting the roles: the OSCam act as a client and connects to /tmp/.listen.camd.socket created by
32Enigma. This way multiple Software CAMs could be running and connecting to Enigma's .listen.camd.socket.
33The other important improvement in this mode (also implemented in OSCam) was the ability to handle extra CA_PMT list
34managements. This allows to use one socket connection to handle more then one channel at a time (before a client
35has to manage single connection to /tmp/camd.socket per subscribed channel).
36
37As the .listen.camd.socket mode makes less sense on generic PC platform (the OSCam is still server, while the client
38could be any PC software used), the second feature which allows handling multiple channels on single socket connection
39was extended to cover other modes (not only pmt_mode=6) in OSCam.
40
41Network mode
42============
43The last feature that was added was a network mode. The change was made to be able to connect to an OSCam which
44is not running on the same machine where the TV receiver software (and a DVB hardware) is running.
45
46Why not use a 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 comes in quicker.
48- OSCam known what readers it has so it could do a load balance/filtering/priorities etc.
49
50As a result, instead of /tmp/camd.socket (which could be used only on the same machine) a listening_socket parameter
51was added. So the unix domain socket switched to a full-featured TCP socket which can be connected from any network
52client.
53
54As a result besides CA_SET_PID and CA_SET_DESCR a new calls was passed to socket: DMX_SET_FILTER and DMX_STOP.
55The TV receiver software has to filter the demux itself (according to the above new calls) and send the results like
56ECM/EMM/CAT data back to OSCam using the same connection.
57Because the OSCam was only aware of PMT data on the socket, a new DVBAPI_FILTER_DATA command (0xffff0000) was added,
58to be able to handle client data from filters.
59
60This way all the communication between the TV receiver software and the OSCam could be finally done using one single
61TCP connection.
62Moreover: the demux is only accessed by single TV receiver software process, which, from the architecture point of view
63is definitely a better solution.
64
65New protocol description (sockets commands)
66===========================================
67As there are more and more dvbapi clients, some problems starts to appear. First of all there was some kind of
68mess because the OSCam network mode doesn't take into account the endianness in first form of network protocol.
69Secondly it was not consistant (eg PID was always send as little endian in DMX_STOP, while the rest depend on OSCam
70host architecture). Finally the standard API ioctl codes for: CA_SET_PID, CA_SET_DESCR, DMX_SET_FILTER and DMX_STOP
71differences. These codes are composed by a macro which takes into account the length of the associated structures and
72on some hardware the first bits of the MSB was different. So the clients had to do some strange workarounds with
73the MSB byte:
74 fix 0x80 -> 0x40 and 0x20 -> 0x00 when needed
75
76Finally, the first byte sent to client was an adapter index, which was not always needed in all commands.
77Now the first 4-byte integer is unique operation code, so a client will know what is the request type and could read
78the rest of data according to the following description (and field sizes).
79
80To address all above problems and additionally makes smooth transitions when updating the protocol in the future
81there was added some kind of "handshake" for clients. All new implementations should use it.
82Currently the old and new implementations should work fine, but in the future a network client which will not
83introduce itself (thus not providing it's supported protocol version) may be dropped/ignored by OSCam.
84
85All multibyte integers (if not specified otherwise) should be send using network byte order, so your client
86should use ntoh() functions when receiving - oscam is doing hton() before send) and vice versa.
87
88Just right after a client connects to an OSCam network socket, it should send a greeting in format:
89
90-= DVBAPI_CLIENT_INFO =-
91-----------------------------------------------------------------------
92type/size description
93-----------------------------------------------------------------------
94uint32_t operation code -> DVBAPI_CLIENT_INFO
95uint16_t protocol version supported by client
96uint8_t size of followed string (255 bytes max)
97string name and version of the client (string length should be max 255 bytes)
98
99The server will respond with similar reply:
100
101-= DVBAPI_SERVER_INFO =-
102-----------------------------------------------------------------------
103type/size description
104-----------------------------------------------------------------------
105uint32_t operation code -> DVBAPI_SERVER_INFO
106uint16_t protocol version supported by OSCam
107uint8_t size of followed string (255 bytes max)
108string OSCam version and build (string length should be max 255 bytes)
109
110Next, when a client want to start a channel it should send the PMT data (program map table).
111The PMT data structure starts with constant AOT_CA_PMT (0x9F8032).
112The data format of the CA_PMT is described in chapter 8.4.3.4 (page 30) of the EN 50221 PDF (european standard).
113
114Please note that OSCam is expecting the own descriptor injected in the data.
115Look into getDemuxOptions() OSCam function for the reference.
116
117
118After OSCam parses the PMT data, it is starting to filtering ECM PIDs, so it send the following request to the client:
119
120-= DVBAPI_DMX_SET_FILTER =-
121-----------------------------------------------------------------------
122type/size description
123-----------------------------------------------------------------------
124uint32_t operation code -> DVBAPI_DMX_SET_FILTER
125uint8_t adapter index
126uint8_t demux index
127uint8_t filter number
128*** The following data are the fields from the dmx_sct_filter_params structure (added separately to avoid padding problems)
129uint16_t pid
130uchar[16] filter data (filter.filter)
131uchar[16] filter mask (filter.mask)
132uchar[16] filter mode (filter.mode)
133uint32_t timeout
134uint32_t flags
135
136The client should then filter the data and pass it back to the OSCam using the following frame:
137
138-= DVBAPI_FILTER_DATA =-
139-----------------------------------------------------------------------
140type/size description
141-----------------------------------------------------------------------
142uint32_t operation code -> DVBAPI_FILTER_DATA
143uint8_t demux index
144uint8_t filter number
145uchar[] filtered data from demux
146
147When OSCam is able to decrypt a channel it firstly send the list of PIDs associated with the descrambler index using this packet:
148
149-= DVBAPI_CA_SET_PID =-
150-----------------------------------------------------------------------
151type/size description
152-----------------------------------------------------------------------
153uint32_t operation code -> DVBAPI_CA_SET_PID
154uint8_t adapter index
155ca_pid_t 8-byte ca_pid_t structure (the pid and index fields are in network byte order)
156
157And also send the CW for decryption:
158
159-= DVBAPI_CA_SET_DESCR =-
160-----------------------------------------------------------------------
161type/size description
162-----------------------------------------------------------------------
163uint32_t operation code -> DVBAPI_CA_SET_DESCR
164uint8_t adapter index
165ca_descr_t 16-byte ca_descr_t structure (the index and parity fields are in network byte order)
166
167When OSCam want to inform client about stopping a filter it send the following packet:
168
169-= DVBAPI_DMX_STOP =-
170-----------------------------------------------------------------------
171type/size description
172-----------------------------------------------------------------------
173uint32_t operation code -> DVBAPI_DMX_STOP
174uint8_t adapter index
175uint8_t demux index
176uint8_t filter number
177uint16_t PID to stop filtering
178
179When the client closes connection, all associated channels are stopped in the OSCam.
180
181Alternatively when there is a need to stop decoding channels, while having the connection still open you can send a special
182'3f' packed to OSCam. To stop decoding specified demux the following CA_PMT data should be sent to OSCam:
1839F 80 3f 04 83 02 00 <demux index>
184If <demux index> is 0xff, then it is parsed as a wildcard and all demuxers associated with the connection are stopped.
185
186
187In protocol version 2 the new packet with ECM info data was introduced:
188
189-= DVBAPI_ECM_INFO =-
190-----------------------------------------------------------------------
191type/size description
192-----------------------------------------------------------------------
193uint32_t operation code -> DVBAPI_ECM_INFO
194uint8_t adapter index
195uint16_t Service ID
196uint16_t CAID
197uint16_t PID
198uint32_t Provider ID
199uint32_t ECM time (ms)
200uint8_t size of followed string (255 bytes max)
201string reader name (string length should be max 255 bytes)
202uint8_t size of followed string (255 bytes max)
203string from - source name (string length should be max 255 bytes)
204uint8_t size of followed string (255 bytes max)
205string protocol name (string length should be max 255 bytes)
206uint8_t hops (cccam & gbox; set to 0 otherwise)
Note: See TracBrowser for help on using the repository browser.