Documentation/userspace-api/media/dvb/ca_high_level.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 The High level CI API
   4 =====================
   5
   6 .. note::
   7
   8    This documentation is outdated.
   9
  10 This document describes the high level CI API as in accordance to the
  11 Linux DVB API.
  12
  13
  14 With the High Level CI approach any new card with almost any random
  15 architecture can be implemented with this style, the definitions
  16 inside the switch statement can be easily adapted for any card, thereby
  17 eliminating the need for any additional ioctls.
  18
  19 The disadvantage is that the driver/hardware has to manage the rest. For
  20 the application programmer it would be as simple as sending/receiving an
  21 array to/from the CI ioctls as defined in the Linux DVB API. No changes
  22 have been made in the API to accommodate this feature.
  23
  24
  25 Why the need for another CI interface?
  26 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  27
  28 This is one of the most commonly asked question. Well a nice question.
  29 Strictly speaking this is not a new interface.
  30
  31 The CI interface is defined in the DVB API in ca.h as:
  32
  33 .. code-block:: c
  34
  35         typedef struct ca_slot_info {
  36                 int num;               /* slot number */
  37
  38                 int type;              /* CA interface this slot supports */
  39         #define CA_CI            1     /* CI high level interface */
  40         #define CA_CI_LINK       2     /* CI link layer level interface */
  41         #define CA_CI_PHYS       4     /* CI physical layer level interface */
  42         #define CA_DESCR         8     /* built-in descrambler */
  43         #define CA_SC          128     /* simple smart card interface */
  44
  45                 unsigned int flags;
  46         #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
  47         #define CA_CI_MODULE_READY   2
  48         } ca_slot_info_t;
  49
  50 This CI interface follows the CI high level interface, which is not
  51 implemented by most applications. Hence this area is revisited.
  52
  53 This CI interface is quite different in the case that it tries to
  54 accommodate all other CI based devices, that fall into the other categories.
  55
  56 This means that this CI interface handles the EN50221 style tags in the
  57 Application layer only and no session management is taken care of by the
  58 application. The driver/hardware will take care of all that.
  59
  60 This interface is purely an EN50221 interface exchanging APDU's. This
  61 means that no session management, link layer or a transport layer do
  62 exist in this case in the application to driver communication. It is
  63 as simple as that. The driver/hardware has to take care of that.
  64
  65 With this High Level CI interface, the interface can be defined with the
  66 regular ioctls.
  67
  68 All these ioctls are also valid for the High level CI interface
  69
  70 #define CA_RESET          _IO('o', 128)
  71 #define CA_GET_CAP        _IOR('o', 129, ca_caps_t)
  72 #define CA_GET_SLOT_INFO  _IOR('o', 130, ca_slot_info_t)
  73 #define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
  74 #define CA_GET_MSG        _IOR('o', 132, ca_msg_t)
  75 #define CA_SEND_MSG       _IOW('o', 133, ca_msg_t)
  76 #define CA_SET_DESCR      _IOW('o', 134, ca_descr_t)
  77
  78
  79 On querying the device, the device yields information thus:
  80
  81 .. code-block:: none
  82
  83         CA_GET_SLOT_INFO
  84         ----------------------------
  85         Command = [info]
  86         APP: Number=[1]
  87         APP: Type=[1]
  88         APP: flags=[1]
  89         APP: CI High level interface
  90         APP: CA/CI Module Present
  91
  92         CA_GET_CAP
  93         ----------------------------
  94         Command = [caps]
  95         APP: Slots=[1]
  96         APP: Type=[1]
  97         APP: Descrambler keys=[16]
  98         APP: Type=[1]
  99
 100         CA_SEND_MSG
 101         ----------------------------
 102         Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
 103         Found CA descriptor @ program level
 104
 105         (20) ES type=[2] ES pid=[201]  ES length =[0 (0x0)]
 106         (25) ES type=[4] ES pid=[301]  ES length =[0 (0x0)]
 107         ca_message length is 25 (0x19) bytes
 108         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]
 109
 110
 111 Not all ioctl's are implemented in the driver from the API, the other
 112 features of the hardware that cannot be implemented by the API are achieved
 113 using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
 114 used to exchange the data to maintain compatibility with other hardware.
 115
 116 .. code-block:: c
 117
 118         /* a message to/from a CI-CAM */
 119         typedef struct ca_msg {
 120                 unsigned int index;
 121                 unsigned int type;
 122                 unsigned int length;
 123                 unsigned char msg[256];
 124         } ca_msg_t;
 125
 126
 127 The flow of data can be described thus,
 128
 129 .. code-block:: none
 130
 131         App (User)
 132         -----
 133         parse
 134           |
 135           |
 136           v
 137         en50221 APDU (package)
 138    --------------------------------------
 139    |      |                             | High Level CI driver
 140    |      |                             |
 141    |      v                             |
 142    |    en50221 APDU (unpackage)        |
 143    |      |                             |
 144    |      |                             |
 145    |      v                             |
 146    |    sanity checks                   |
 147    |      |                             |
 148    |      |                             |
 149    |      v                             |
 150    |    do (H/W dep)                    |
 151    --------------------------------------
 152           |    Hardware
 153           |
 154           v
 155
 156 The High Level CI interface uses the EN50221 DVB standard, following a
 157 standard ensures futureproofness.