Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 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 |
Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 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, |
Manu Abraham | 9dea885 | 2005-09-09 13:03:03 -0700 | [diff] [blame] | 33 | eg: $ ca_zap channels.conf "TMC" |
Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 34 | |
Matt LaPlante | 2fe0ae7 | 2006-10-03 22:50:39 +0200 | [diff] [blame] | 35 | (d) Hopefully enjoy your favourite subscribed channel as you do with |
Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 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 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Francis Galiegue | a33f322 | 2010-04-23 00:08:02 +0200 | [diff] [blame] | 44 | At present the cards that fall in this category are the Twinhan and its |
Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 45 | clones, these cards are available as VVMER, Tomato, Hercules, Orange and |
| 46 | so on. |
| 47 | |
| 48 | * CI modules that are supported |
| 49 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Lucas De Marchi | 25985ed | 2011-03-30 22:57:33 -0300 | [diff] [blame] | 50 | The CI module support is largely dependent upon the firmware on the cards |
Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 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 |
Matt LaPlante | 2fe0ae7 | 2006-10-03 22:50:39 +0200 | [diff] [blame] | 68 | inside the switch statement can be easily adapted for any card, thereby |
Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 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 |
Matt LaPlante | 4ae0edc | 2006-11-30 04:58:40 +0100 | [diff] [blame] | 74 | have been made in the API to accommodate this feature. |
Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 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 |
Matt LaPlante | 4ae0edc | 2006-11-30 04:58:40 +0100 | [diff] [blame] | 105 | accommodate all other CI based devices, that fall into the other categories. |
Johannes Stezenbach | 50b215a | 2005-05-16 21:54:41 -0700 | [diff] [blame] | 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. |