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