0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 The High level CI API
0004 =====================
0005
0006 .. note::
0007
0008 This documentation is outdated.
0009
0010 This document describes the high level CI API as in accordance to the
0011 Linux DVB API.
0012
0013
0014 With the High Level CI approach any new card with almost any random
0015 architecture can be implemented with this style, the definitions
0016 inside the switch statement can be easily adapted for any card, thereby
0017 eliminating the need for any additional ioctls.
0018
0019 The disadvantage is that the driver/hardware has to manage the rest. For
0020 the application programmer it would be as simple as sending/receiving an
0021 array to/from the CI ioctls as defined in the Linux DVB API. No changes
0022 have been made in the API to accommodate this feature.
0023
0024
0025 Why the need for another CI interface?
0026 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0027
0028 This is one of the most commonly asked question. Well a nice question.
0029 Strictly speaking this is not a new interface.
0030
0031 The CI interface is defined in the DVB API in ca.h as:
0032
0033 .. code-block:: c
0034
0035 typedef struct ca_slot_info {
0036 int num; /* slot number */
0037
0038 int type; /* CA interface this slot supports */
0039 #define CA_CI 1 /* CI high level interface */
0040 #define CA_CI_LINK 2 /* CI link layer level interface */
0041 #define CA_CI_PHYS 4 /* CI physical layer level interface */
0042 #define CA_DESCR 8 /* built-in descrambler */
0043 #define CA_SC 128 /* simple smart card interface */
0044
0045 unsigned int flags;
0046 #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
0047 #define CA_CI_MODULE_READY 2
0048 } ca_slot_info_t;
0049
0050 This CI interface follows the CI high level interface, which is not
0051 implemented by most applications. Hence this area is revisited.
0052
0053 This CI interface is quite different in the case that it tries to
0054 accommodate all other CI based devices, that fall into the other categories.
0055
0056 This means that this CI interface handles the EN50221 style tags in the
0057 Application layer only and no session management is taken care of by the
0058 application. The driver/hardware will take care of all that.
0059
0060 This interface is purely an EN50221 interface exchanging APDU's. This
0061 means that no session management, link layer or a transport layer do
0062 exist in this case in the application to driver communication. It is
0063 as simple as that. The driver/hardware has to take care of that.
0064
0065 With this High Level CI interface, the interface can be defined with the
0066 regular ioctls.
0067
0068 All these ioctls are also valid for the High level CI interface
0069
0070 #define CA_RESET _IO('o', 128)
0071 #define CA_GET_CAP _IOR('o', 129, ca_caps_t)
0072 #define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t)
0073 #define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
0074 #define CA_GET_MSG _IOR('o', 132, ca_msg_t)
0075 #define CA_SEND_MSG _IOW('o', 133, ca_msg_t)
0076 #define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
0077
0078
0079 On querying the device, the device yields information thus:
0080
0081 .. code-block:: none
0082
0083 CA_GET_SLOT_INFO
0084 ----------------------------
0085 Command = [info]
0086 APP: Number=[1]
0087 APP: Type=[1]
0088 APP: flags=[1]
0089 APP: CI High level interface
0090 APP: CA/CI Module Present
0091
0092 CA_GET_CAP
0093 ----------------------------
0094 Command = [caps]
0095 APP: Slots=[1]
0096 APP: Type=[1]
0097 APP: Descrambler keys=[16]
0098 APP: Type=[1]
0099
0100 CA_SEND_MSG
0101 ----------------------------
0102 Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
0103 Found CA descriptor @ program level
0104
0105 (20) ES type=[2] ES pid=[201] ES length =[0 (0x0)]
0106 (25) ES type=[4] ES pid=[301] ES length =[0 (0x0)]
0107 ca_message length is 25 (0x19) bytes
0108 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]
0109
0110
0111 Not all ioctl's are implemented in the driver from the API, the other
0112 features of the hardware that cannot be implemented by the API are achieved
0113 using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
0114 used to exchange the data to maintain compatibility with other hardware.
0115
0116 .. code-block:: c
0117
0118 /* a message to/from a CI-CAM */
0119 typedef struct ca_msg {
0120 unsigned int index;
0121 unsigned int type;
0122 unsigned int length;
0123 unsigned char msg[256];
0124 } ca_msg_t;
0125
0126
0127 The flow of data can be described thus,
0128
0129 .. code-block:: none
0130
0131 App (User)
0132 -----
0133 parse
0134 |
0135 |
0136 v
0137 en50221 APDU (package)
0138 --------------------------------------
0139 | | | High Level CI driver
0140 | | |
0141 | v |
0142 | en50221 APDU (unpackage) |
0143 | | |
0144 | | |
0145 | v |
0146 | sanity checks |
0147 | | |
0148 | | |
0149 | v |
0150 | do (H/W dep) |
0151 --------------------------------------
0152 | Hardware
0153 |
0154 v
0155
0156 The High Level CI interface uses the EN50221 DVB standard, following a
0157 standard ensures futureproofness.
