Documentation/dvb/ci.txt

   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
  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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51 At present the cards that fall in this category are the Twinhan and it's
  52 clones, these cards are available as VVMER, Tomato, Hercules, Orange and
  53 so on.
  54
  55 * CI modules that are supported
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57 The CI module support is largely dependant upon the firmware on the cards
  58 Some cards do support almost all of the available CI modules. There is
  59 nothing much that can be done in order to make additional CI modules
  60 working with these cards.
  61
  62 Modules 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73 With the High Level CI approach any new card with almost any random
  74 architecture can be implemented with this style, the definitions
  75 insidethe switch statement can be easily adapted for any card, thereby
  76 eliminating the need for any additional ioctls.
  77
  78 The disadvantage is that the driver/hardware has to manage the rest. For
  79 the application programmer it would be as simple as sending/receiving an
  80 array to/from the CI ioctls as defined in the Linux DVB API. No changes
  81 have been made in the API to accomodate this feature.
  82
  83
  84 * Why the need for another CI interface ?
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86 This is one of the most commonly asked question. Well a nice question.
  87 Strictly speaking this is not a new interface.
  88
  89 The CI interface is defined in the DVB API in ca.h as
  90
  91 typedef 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
 108 This CI interface follows the CI high level interface, which is not
 109 implemented by most applications. Hence this area is revisited.
 110
 111 This CI interface is quite different in the case that it tries to
 112 accomodate all other CI based devices, that fall into the other categories
 113
 114 This means that this CI interface handles the EN50221 style tags in the
 115 Application layer only and no session management is taken care of by the
 116 application. The driver/hardware will take care of all that.
 117
 118 This interface is purely an EN50221 interface exchanging APDU's. This
 119 means that no session management, link layer or a transport layer do
 120 exist in this case in the application to driver communication. It is
 121 as simple as that. The driver/hardware has to take care of that.
 122
 123
 124 With this High Level CI interface, the interface can be defined with the
 125 regular ioctls.
 126
 127 All 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
 139 On querying the device, the device yields information thus
 140
 141 CA_GET_SLOT_INFO
 142 ----------------------------
 143 Command = [info]
 144 APP: Number=[1]
 145 APP: Type=[1]
 146 APP: flags=[1]
 147 APP: CI High level interface
 148 APP: CA/CI Module Present
 149
 150 CA_GET_CAP
 151 ----------------------------
 152 Command = [caps]
 153 APP: Slots=[1]
 154 APP: Type=[1]
 155 APP: Descrambler keys=[16]
 156 APP: Type=[1]
 157
 158 CA_SEND_MSG
 159 ----------------------------
 160 Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
 161 Found 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)]
 165 ca_message length is 25 (0x19) bytes
 166 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]
 167
 168
 169 Not all ioctl's are implemented in the driver from the API, the other
 170 features of the hardware that cannot be implemented by the API are achieved
 171 using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
 172 used to exchange the data to maintain compatibility with other hardware.
 173
 174
 175 /* a message to/from a CI-CAM */
 176 typedef 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
 184 The 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
 218 The High Level CI interface uses the EN50221 DVB standard, following a
 219 standard ensures futureproofness.