| 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. |