Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.
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 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, 33 eg: $ ca_zap channels.conf "TMC" 34 35 (d) Hopefully enjoy your favourite subscribed channel as you do with 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 its 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 dependent 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 68 inside the switch statement can be easily adapted for any card, thereby 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 74 have been made in the API to accommodate this feature. 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 105 accommodate all other CI based devices, that fall into the other categories. 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.