About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / dvb / ci.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

1	* For the user
2	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3	NOTE: This document describes the usage of the high level CI API as
4	in accordance to the Linux DVB API. This is a not a documentation for the,
5	existing low level CI API.
6	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7	
8	To utilize the High Level CI capabilities,
9	
10	(1*) This point is valid only for the Twinhan/clones
11	  For the Twinhan/Twinhan clones, the dst_ca module handles the CI
12	  hardware handling.This module is loaded automatically if a CI
13	  (Common Interface, that holds the CAM (Conditional Access Module)
14	  is detected.
15	
16	(2) one requires a userspace application, ca_zap. This small userland
17	  application is in charge of sending the descrambling related information
18	  to the CAM.
19	
20	This application requires the following to function properly as of now.
21	
22		(a) Tune to a valid channel, with szap.
23		  eg: $ szap -c channels.conf -r "TMC" -x
24	
25		(b) a channels.conf containing a valid PMT PID
26		  eg: TMC:11996:h:0:27500:278:512:650:321
27	
28		  here 278 is a valid PMT PID. the rest of the values are the
29		  same ones that szap uses.
30	
31		(c) after running a szap, you have to run ca_zap, for the
32		  descrambler to function,
33		  eg: $ ca_zap channels.conf "TMC"
34	
35		(d) Hopefully enjoy your favourite subscribed channel as you do with
36		  a FTA card.
37	
38	(3) Currently ca_zap, and dst_test, both are meant for demonstration
39	  purposes only, they can become full fledged applications if necessary.
40	
41	
42	* Cards that fall in this category
43	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44	At present the cards that fall in this category are the Twinhan and its
45	clones, these cards are available as VVMER, Tomato, Hercules, Orange and
46	so on.
47	
48	* CI modules that are supported
49	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
50	The CI module support is largely dependent upon the firmware on the cards
51	Some cards do support almost all of the available CI modules. There is
52	nothing much that can be done in order to make additional CI modules
53	working with these cards.
54	
55	Modules that have been tested by this driver at present are
56	
57	(1) Irdeto 1 and 2 from SCM
58	(2) Viaccess from SCM
59	(3) Dragoncam
60	
61	* The High level CI API
62	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63	
64	* For the programmer
65	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66	With the High Level CI approach any new card with almost any random
67	architecture can be implemented with this style, the definitions
68	inside the switch statement can be easily adapted for any card, thereby
69	eliminating the need for any additional ioctls.
70	
71	The disadvantage is that the driver/hardware has to manage the rest. For
72	the application programmer it would be as simple as sending/receiving an
73	array to/from the CI ioctls as defined in the Linux DVB API. No changes
74	have been made in the API to accommodate this feature.
75	
76	
77	* Why the need for another CI interface ?
78	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79	This is one of the most commonly asked question. Well a nice question.
80	Strictly speaking this is not a new interface.
81	
82	The CI interface is defined in the DVB API in ca.h as
83	
84	typedef struct ca_slot_info {
85		int num;               /* slot number */
86	
87		int type;              /* CA interface this slot supports */
88	#define CA_CI            1     /* CI high level interface */
89	#define CA_CI_LINK       2     /* CI link layer level interface */
90	#define CA_CI_PHYS       4     /* CI physical layer level interface */
91	#define CA_DESCR         8     /* built-in descrambler */
92	#define CA_SC          128     /* simple smart card interface */
93	
94		unsigned int flags;
95	#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
96	#define CA_CI_MODULE_READY   2
97	} ca_slot_info_t;
98	
99	
100	
101	This CI interface follows the CI high level interface, which is not
102	implemented by most applications. Hence this area is revisited.
103	
104	This CI interface is quite different in the case that it tries to
105	accommodate all other CI based devices, that fall into the other categories.
106	
107	This means that this CI interface handles the EN50221 style tags in the
108	Application layer only and no session management is taken care of by the
109	application. The driver/hardware will take care of all that.
110	
111	This interface is purely an EN50221 interface exchanging APDU's. This
112	means that no session management, link layer or a transport layer do
113	exist in this case in the application to driver communication. It is
114	as simple as that. The driver/hardware has to take care of that.
115	
116	
117	With this High Level CI interface, the interface can be defined with the
118	regular ioctls.
119	
120	All these ioctls are also valid for the High level CI interface
121	
122	#define CA_RESET          _IO('o', 128)
123	#define CA_GET_CAP        _IOR('o', 129, ca_caps_t)
124	#define CA_GET_SLOT_INFO  _IOR('o', 130, ca_slot_info_t)
125	#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
126	#define CA_GET_MSG        _IOR('o', 132, ca_msg_t)
127	#define CA_SEND_MSG       _IOW('o', 133, ca_msg_t)
128	#define CA_SET_DESCR      _IOW('o', 134, ca_descr_t)
129	#define CA_SET_PID        _IOW('o', 135, ca_pid_t)
130	
131	
132	On querying the device, the device yields information thus
133	
134	CA_GET_SLOT_INFO
135	----------------------------
136	Command = [info]
137	APP: Number=[1]
138	APP: Type=[1]
139	APP: flags=[1]
140	APP: CI High level interface
141	APP: CA/CI Module Present
142	
143	CA_GET_CAP
144	----------------------------
145	Command = [caps]
146	APP: Slots=[1]
147	APP: Type=[1]
148	APP: Descrambler keys=[16]
149	APP: Type=[1]
150	
151	CA_SEND_MSG
152	----------------------------
153	Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
154	Found CA descriptor @ program level
155	
156	(20) ES type=[2] ES pid=[201]  ES length =[0 (0x0)]
157	(25) ES type=[4] ES pid=[301]  ES length =[0 (0x0)]
158	ca_message length is 25 (0x19) bytes
159	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]
160	
161	
162	Not all ioctl's are implemented in the driver from the API, the other
163	features of the hardware that cannot be implemented by the API are achieved
164	using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
165	used to exchange the data to maintain compatibility with other hardware.
166	
167	
168	/* a message to/from a CI-CAM */
169	typedef struct ca_msg {
170		unsigned int index;
171		unsigned int type;
172		unsigned int length;
173		unsigned char msg[256];
174	} ca_msg_t;
175	
176	
177	The flow of data can be described thus,
178	
179	
180	
181	
182	
183		App (User)
184		-----
185		parse
186		  |
187		  |
188		  v
189		en50221 APDU (package)
190	   --------------------------------------
191	   |	  |				| High Level CI driver
192	   |	  |				|
193	   |	  v				|
194	   |	en50221 APDU (unpackage)	|
195	   |	  |				|
196	   |	  |				|
197	   |	  v				|
198	   |	sanity checks			|
199	   |	  |				|
200	   |	  |				|
201	   |	  v				|
202	   |	do (H/W dep)			|
203	   --------------------------------------
204		  |    Hardware
205		  |
206		  v
207	
208	
209	
210	
211	The High Level CI interface uses the EN50221 DVB standard, following a
212	standard ensures futureproofness.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.