158 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3The High level CI API4=====================5 6.. note::7 8 This documentation is outdated.9 10This document describes the high level CI API as in accordance to the11Linux DVB API.12 13 14With the High Level CI approach any new card with almost any random15architecture can be implemented with this style, the definitions16inside the switch statement can be easily adapted for any card, thereby17eliminating the need for any additional ioctls.18 19The disadvantage is that the driver/hardware has to manage the rest. For20the application programmer it would be as simple as sending/receiving an21array to/from the CI ioctls as defined in the Linux DVB API. No changes22have 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:: c34 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 248 } ca_slot_info_t;49 50This CI interface follows the CI high level interface, which is not51implemented by most applications. Hence this area is revisited.52 53This CI interface is quite different in the case that it tries to54accommodate all other CI based devices, that fall into the other categories.55 56This means that this CI interface handles the EN50221 style tags in the57Application layer only and no session management is taken care of by the58application. The driver/hardware will take care of all that.59 60This interface is purely an EN50221 interface exchanging APDU's. This61means that no session management, link layer or a transport layer do62exist in this case in the application to driver communication. It is63as 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 the66regular ioctls.67 68All these ioctls are also valid for the High level CI interface69 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:: none82 83 CA_GET_SLOT_INFO84 ----------------------------85 Command = [info]86 APP: Number=[1]87 APP: Type=[1]88 APP: flags=[1]89 APP: CI High level interface90 APP: CA/CI Module Present91 92 CA_GET_CAP93 ----------------------------94 Command = [caps]95 APP: Slots=[1]96 APP: Type=[1]97 APP: Descrambler keys=[16]98 APP: Type=[1]99 100 CA_SEND_MSG101 ----------------------------102 Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]103 Found CA descriptor @ program level104 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) bytes108 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 other112features of the hardware that cannot be implemented by the API are achieved113using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is114used to exchange the data to maintain compatibility with other hardware.115 116.. code-block:: c117 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:: none130 131 App (User)132 -----133 parse134 |135 |136 v137 en50221 APDU (package)138 --------------------------------------139 | | | High Level CI driver140 | | |141 | v |142 | en50221 APDU (unpackage) |143 | | |144 | | |145 | v |146 | sanity checks |147 | | |148 | | |149 | v |150 | do (H/W dep) |151 --------------------------------------152 | Hardware153 |154 v155 156The High Level CI interface uses the EN50221 DVB standard, following a157standard ensures futureproofness.158