blob: 2ecd834585e64140fcaa064c27142a9b7fd23950 [file] [log] [blame]
Johannes Stezenbach50b215a2005-05-16 21:54:41 -07001* For the user
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3NOTE: This document describes the usage of the high level CI API as
4in accordance to the Linux DVB API. This is a not a documentation for the,
5existing low level CI API.
6~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7
8To utilize the High Level CI capabilities,
9
10(1*) This point is valid only for the Twinhan/clones
11 For the Twinhan/Twinhan clones, the dst_ca module handles the CI
12 hardware handling.This module is loaded automatically if a CI
13 (Common Interface, that holds the CAM (Conditional Access Module)
14 is detected.
15
16(2) one requires a userspace application, ca_zap. This small userland
17 application is in charge of sending the descrambling related information
18 to the CAM.
19
20This application requires the following to function properly as of now.
21
22 (a) Tune to a valid channel, with szap.
23 eg: $ szap -c channels.conf -r "TMC" -x
24
25 (b) a channels.conf containing a valid PMT PID
Johannes Stezenbach50b215a2005-05-16 21:54:41 -070026 eg: TMC:11996:h:0:27500:278:512:650:321
27
28 here 278 is a valid PMT PID. the rest of the values are the
29 same ones that szap uses.
30
31 (c) after running a szap, you have to run ca_zap, for the
32 descrambler to function,
Manu Abraham9dea8852005-09-09 13:03:03 -070033 eg: $ ca_zap channels.conf "TMC"
Johannes Stezenbach50b215a2005-05-16 21:54:41 -070034
Matt LaPlante2fe0ae72006-10-03 22:50:39 +020035 (d) Hopefully enjoy your favourite subscribed channel as you do with
Johannes Stezenbach50b215a2005-05-16 21:54:41 -070036 a FTA card.
37
38(3) Currently ca_zap, and dst_test, both are meant for demonstration
39 purposes only, they can become full fledged applications if necessary.
40
41
42* Cards that fall in this category
43~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44At present the cards that fall in this category are the Twinhan and it's
45clones, these cards are available as VVMER, Tomato, Hercules, Orange and
46so on.
47
48* CI modules that are supported
49~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50The CI module support is largely dependant upon the firmware on the cards
51Some cards do support almost all of the available CI modules. There is
52nothing much that can be done in order to make additional CI modules
53working with these cards.
54
55Modules that have been tested by this driver at present are
56
57(1) Irdeto 1 and 2 from SCM
58(2) Viaccess from SCM
59(3) Dragoncam
60
61* The High level CI API
62~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63
64* For the programmer
65~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66With the High Level CI approach any new card with almost any random
67architecture can be implemented with this style, the definitions
Matt LaPlante2fe0ae72006-10-03 22:50:39 +020068inside the switch statement can be easily adapted for any card, thereby
Johannes Stezenbach50b215a2005-05-16 21:54:41 -070069eliminating the need for any additional ioctls.
70
71The disadvantage is that the driver/hardware has to manage the rest. For
72the application programmer it would be as simple as sending/receiving an
73array to/from the CI ioctls as defined in the Linux DVB API. No changes
Matt LaPlante4ae0edc2006-11-30 04:58:40 +010074have been made in the API to accommodate this feature.
Johannes Stezenbach50b215a2005-05-16 21:54:41 -070075
76
77* Why the need for another CI interface ?
78~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79This is one of the most commonly asked question. Well a nice question.
80Strictly speaking this is not a new interface.
81
82The CI interface is defined in the DVB API in ca.h as
83
84typedef struct ca_slot_info {
85 int num; /* slot number */
86
87 int type; /* CA interface this slot supports */
88#define CA_CI 1 /* CI high level interface */
89#define CA_CI_LINK 2 /* CI link layer level interface */
90#define CA_CI_PHYS 4 /* CI physical layer level interface */
91#define CA_DESCR 8 /* built-in descrambler */
92#define CA_SC 128 /* simple smart card interface */
93
94 unsigned int flags;
95#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
96#define CA_CI_MODULE_READY 2
97} ca_slot_info_t;
98
99
100
101This CI interface follows the CI high level interface, which is not
102implemented by most applications. Hence this area is revisited.
103
104This CI interface is quite different in the case that it tries to
Matt LaPlante4ae0edc2006-11-30 04:58:40 +0100105accommodate all other CI based devices, that fall into the other categories.
Johannes Stezenbach50b215a2005-05-16 21:54:41 -0700106
107This means that this CI interface handles the EN50221 style tags in the
108Application layer only and no session management is taken care of by the
109application. The driver/hardware will take care of all that.
110
111This interface is purely an EN50221 interface exchanging APDU's. This
112means that no session management, link layer or a transport layer do
113exist in this case in the application to driver communication. It is
114as simple as that. The driver/hardware has to take care of that.
115
116
117With this High Level CI interface, the interface can be defined with the
118regular ioctls.
119
120All these ioctls are also valid for the High level CI interface
121
122#define CA_RESET _IO('o', 128)
123#define CA_GET_CAP _IOR('o', 129, ca_caps_t)
124#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t)
125#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
126#define CA_GET_MSG _IOR('o', 132, ca_msg_t)
127#define CA_SEND_MSG _IOW('o', 133, ca_msg_t)
128#define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
129#define CA_SET_PID _IOW('o', 135, ca_pid_t)
130
131
132On querying the device, the device yields information thus
133
134CA_GET_SLOT_INFO
135----------------------------
136Command = [info]
137APP: Number=[1]
138APP: Type=[1]
139APP: flags=[1]
140APP: CI High level interface
141APP: CA/CI Module Present
142
143CA_GET_CAP
144----------------------------
145Command = [caps]
146APP: Slots=[1]
147APP: Type=[1]
148APP: Descrambler keys=[16]
149APP: Type=[1]
150
151CA_SEND_MSG
152----------------------------
153Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
154Found CA descriptor @ program level
155
156(20) ES type=[2] ES pid=[201] ES length =[0 (0x0)]
157(25) ES type=[4] ES pid=[301] ES length =[0 (0x0)]
158ca_message length is 25 (0x19) bytes
159EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00]
160
161
162Not all ioctl's are implemented in the driver from the API, the other
163features of the hardware that cannot be implemented by the API are achieved
164using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
165used to exchange the data to maintain compatibility with other hardware.
166
167
168/* a message to/from a CI-CAM */
169typedef struct ca_msg {
170 unsigned int index;
171 unsigned int type;
172 unsigned int length;
173 unsigned char msg[256];
174} ca_msg_t;
175
176
177The flow of data can be described thus,
178
179
180
181
182
183 App (User)
184 -----
185 parse
186 |
187 |
188 v
189 en50221 APDU (package)
190 --------------------------------------
191 | | | High Level CI driver
192 | | |
193 | v |
194 | en50221 APDU (unpackage) |
195 | | |
196 | | |
197 | v |
198 | sanity checks |
199 | | |
200 | | |
201 | v |
202 | do (H/W dep) |
203 --------------------------------------
204 | Hardware
205 |
206 v
207
208
209
210
211The High Level CI interface uses the EN50221 DVB standard, following a
212standard ensures futureproofness.