Commit | Line | Data |
---|---|---|
50b215a0 JS |
1 | * For the user |
2 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
3 | NOTE: This document describes the usage of the high level CI API as | |
4 | in accordance to the Linux DVB API. This is a not a documentation for the, | |
5 | existing low level CI API. | |
6 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
7 | ||
8 | To 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 | ||
20 | This 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 | |
50b215a0 JS |
26 | 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, | |
9dea8851 | 33 | eg: $ ca_zap channels.conf "TMC" |
50b215a0 | 34 | |
2fe0ae78 | 35 | (d) Hopefully enjoy your favourite subscribed channel as you do with |
50b215a0 JS |
36 | 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 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
44 | At present the cards that fall in this category are the Twinhan and it's | |
45 | clones, these cards are available as VVMER, Tomato, Hercules, Orange and | |
46 | so on. | |
47 | ||
48 | * CI modules that are supported | |
49 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
50 | The CI module support is largely dependant upon the firmware on the cards | |
51 | Some cards do support almost all of the available CI modules. There is | |
52 | nothing much that can be done in order to make additional CI modules | |
53 | working with these cards. | |
54 | ||
55 | Modules 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 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
66 | With the High Level CI approach any new card with almost any random | |
67 | architecture can be implemented with this style, the definitions | |
2fe0ae78 | 68 | inside the switch statement can be easily adapted for any card, thereby |
50b215a0 JS |
69 | eliminating the need for any additional ioctls. |
70 | ||
71 | The disadvantage is that the driver/hardware has to manage the rest. For | |
72 | the application programmer it would be as simple as sending/receiving an | |
73 | array to/from the CI ioctls as defined in the Linux DVB API. No changes | |
4ae0edc2 | 74 | have been made in the API to accommodate this feature. |
50b215a0 JS |
75 | |
76 | ||
77 | * Why the need for another CI interface ? | |
78 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
79 | This is one of the most commonly asked question. Well a nice question. | |
80 | Strictly speaking this is not a new interface. | |
81 | ||
82 | The CI interface is defined in the DVB API in ca.h as | |
83 | ||
84 | typedef 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 | ||
101 | This CI interface follows the CI high level interface, which is not | |
102 | implemented by most applications. Hence this area is revisited. | |
103 | ||
104 | This CI interface is quite different in the case that it tries to | |
4ae0edc2 | 105 | accommodate all other CI based devices, that fall into the other categories. |
50b215a0 JS |
106 | |
107 | This means that this CI interface handles the EN50221 style tags in the | |
108 | Application layer only and no session management is taken care of by the | |
109 | application. The driver/hardware will take care of all that. | |
110 | ||
111 | This interface is purely an EN50221 interface exchanging APDU's. This | |
112 | means that no session management, link layer or a transport layer do | |
113 | exist in this case in the application to driver communication. It is | |
114 | as simple as that. The driver/hardware has to take care of that. | |
115 | ||
116 | ||
117 | With this High Level CI interface, the interface can be defined with the | |
118 | regular ioctls. | |
119 | ||
120 | All 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 | ||
132 | On querying the device, the device yields information thus | |
133 | ||
134 | CA_GET_SLOT_INFO | |
135 | ---------------------------- | |
136 | Command = [info] | |
137 | APP: Number=[1] | |
138 | APP: Type=[1] | |
139 | APP: flags=[1] | |
140 | APP: CI High level interface | |
141 | APP: CA/CI Module Present | |
142 | ||
143 | CA_GET_CAP | |
144 | ---------------------------- | |
145 | Command = [caps] | |
146 | APP: Slots=[1] | |
147 | APP: Type=[1] | |
148 | APP: Descrambler keys=[16] | |
149 | APP: Type=[1] | |
150 | ||
151 | CA_SEND_MSG | |
152 | ---------------------------- | |
153 | Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1] | |
154 | Found 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)] | |
158 | ca_message length is 25 (0x19) bytes | |
159 | EN50221 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 | ||
162 | Not all ioctl's are implemented in the driver from the API, the other | |
163 | features of the hardware that cannot be implemented by the API are achieved | |
164 | using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is | |
165 | used to exchange the data to maintain compatibility with other hardware. | |
166 | ||
167 | ||
168 | /* a message to/from a CI-CAM */ | |
169 | typedef 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 | ||
177 | The 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 | ||
211 | The High Level CI interface uses the EN50221 DVB standard, following a | |
212 | standard ensures futureproofness. |