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