1.. SPDX-License-Identifier: GPL-2.0 2 3The High level CI API 4===================== 5 6.. note:: 7 8 This documentation is outdated. 9 10This document describes the high level CI API as in accordance to the 11Linux DVB API. 12 13 14With the High Level CI approach any new card with almost any random 15architecture can be implemented with this style, the definitions 16inside the switch statement can be easily adapted for any card, thereby 17eliminating the need for any additional ioctls. 18 19The disadvantage is that the driver/hardware has to manage the rest. For 20the application programmer it would be as simple as sending/receiving an 21array to/from the CI ioctls as defined in the Linux DVB API. No changes 22have been made in the API to accommodate this feature. 23 24 25Why the need for another CI interface? 26~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 27 28This is one of the most commonly asked question. Well a nice question. 29Strictly speaking this is not a new interface. 30 31The 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 50This CI interface follows the CI high level interface, which is not 51implemented by most applications. Hence this area is revisited. 52 53This CI interface is quite different in the case that it tries to 54accommodate all other CI based devices, that fall into the other categories. 55 56This means that this CI interface handles the EN50221 style tags in the 57Application layer only and no session management is taken care of by the 58application. The driver/hardware will take care of all that. 59 60This interface is purely an EN50221 interface exchanging APDU's. This 61means that no session management, link layer or a transport layer do 62exist in this case in the application to driver communication. It is 63as simple as that. The driver/hardware has to take care of that. 64 65With this High Level CI interface, the interface can be defined with the 66regular ioctls. 67 68All 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 79On 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 111Not all ioctl's are implemented in the driver from the API, the other 112features of the hardware that cannot be implemented by the API are achieved 113using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is 114used 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 127The 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 156The High Level CI interface uses the EN50221 DVB standard, following a 157standard ensures futureproofness. 158