Documentation/media/dvb-drivers/ci.rst - arm/linux - Git at Google


            
            Digital TV Conditional Access Interface (CI API)

            
            ================================================


            .. note::


               This documentation is outdated.


            This document describes the usage of the high level CI API as

            
            in accordance to the Linux DVB API. This is a not a documentation for the,

            
            existing low level CI API.


            .. note::


               For the Twinhan/Twinhan clones, the dst_ca module handles the CI

            
               hardware handling.This module is loaded automatically if a CI

            
               (Common Interface, that holds the CAM (Conditional Access Module)

            
               is detected.


            ca_zap

            
            ~~~~~~


            An userspace application, like ``ca_zap`` is required to handle encrypted

            
            MPEG-TS streams.


            The ``ca_zap`` userland application is in charge of sending the

            
            descrambling related information to the Conditional Access Module (CAM).


            This application requires the following to function properly as of now.


            a) Tune to a valid channel, with szap.


              eg: $ szap -c channels.conf -r "TMC" -x


            b) a channels.conf containing a valid PMT PID


              eg: TMC:11996:h:0:27500:278:512:650:321


              here 278 is a valid PMT PID. the rest of the values are the

            
              same ones that szap uses.


            c) after running a szap, you have to run ca_zap, for the

            
               descrambler to function,


              eg: $ ca_zap channels.conf "TMC"


            d) Hopefully enjoy your favourite subscribed channel as you do with

            
               a FTA card.


            .. note::


              Currently ca_zap, and dst_test, both are meant for demonstration

            
              purposes only, they can become full fledged applications if necessary.


            Cards that fall in this category

            
            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


            At present the cards that fall in this category are the Twinhan and its

            
            clones, these cards are available as VVMER, Tomato, Hercules, Orange and

            
            so on.


            CI modules that are supported

            
            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


            The CI module support is largely dependent upon the firmware on the cards

            
            Some cards do support almost all of the available CI modules. There is

            
            nothing much that can be done in order to make additional CI modules

            
            working with these cards.


            Modules that have been tested by this driver at present are


            (1) Irdeto 1 and 2 from SCM

            
            (2) Viaccess from SCM

            
            (3) Dragoncam


            The High level CI API

            
            ~~~~~~~~~~~~~~~~~~~~~


            For the programmer

            
            ^^^^^^^^^^^^^^^^^^


            With the High Level CI approach any new card with almost any random

            
            architecture can be implemented with this style, the definitions

            
            inside the switch statement can be easily adapted for any card, thereby

            
            eliminating the need for any additional ioctls.


            The disadvantage is that the driver/hardware has to manage the rest. For

            
            the application programmer it would be as simple as sending/receiving an

            
            array to/from the CI ioctls as defined in the Linux DVB API. No changes

            
            have been made in the API to accommodate this feature.


            Why the need for another CI interface?

            
            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


            This is one of the most commonly asked question. Well a nice question.

            
            Strictly speaking this is not a new interface.


            The CI interface is defined in the DVB API in ca.h as:


            .. code-block:: c


            	typedef struct ca_slot_info {

            
            		int num;               /* slot number */


            		int type;              /* CA interface this slot supports */

            
            	#define CA_CI            1     /* CI high level interface */

            
            	#define CA_CI_LINK       2     /* CI link layer level interface */

            
            	#define CA_CI_PHYS       4     /* CI physical layer level interface */

            
            	#define CA_DESCR         8     /* built-in descrambler */

            
            	#define CA_SC          128     /* simple smart card interface */


            		unsigned int flags;

            
            	#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */

            
            	#define CA_CI_MODULE_READY   2

            
            	} ca_slot_info_t;


            This CI interface follows the CI high level interface, which is not

            
            implemented by most applications. Hence this area is revisited.


            This CI interface is quite different in the case that it tries to

            
            accommodate all other CI based devices, that fall into the other categories.


            This means that this CI interface handles the EN50221 style tags in the

            
            Application layer only and no session management is taken care of by the

            
            application. The driver/hardware will take care of all that.


            This interface is purely an EN50221 interface exchanging APDU's. This

            
            means that no session management, link layer or a transport layer do

            
            exist in this case in the application to driver communication. It is

            
            as simple as that. The driver/hardware has to take care of that.


            With this High Level CI interface, the interface can be defined with the

            
            regular ioctls.


            All these ioctls are also valid for the High level CI interface


            #define CA_RESET          _IO('o', 128)

            
            #define CA_GET_CAP        _IOR('o', 129, ca_caps_t)

            
            #define CA_GET_SLOT_INFO  _IOR('o', 130, ca_slot_info_t)

            
            #define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)

            
            #define CA_GET_MSG        _IOR('o', 132, ca_msg_t)

            
            #define CA_SEND_MSG       _IOW('o', 133, ca_msg_t)

            
            #define CA_SET_DESCR      _IOW('o', 134, ca_descr_t)

            
            #define CA_SET_PID        _IOW('o', 135, ca_pid_t)


            On querying the device, the device yields information thus:


            .. code-block:: none


            	CA_GET_SLOT_INFO

            
            	----------------------------

            
            	Command = [info]

            
            	APP: Number=[1]

            
            	APP: Type=[1]

            
            	APP: flags=[1]

            
            	APP: CI High level interface

            
            	APP: CA/CI Module Present


            	CA_GET_CAP

            
            	----------------------------

            
            	Command = [caps]

            
            	APP: Slots=[1]

            
            	APP: Type=[1]

            
            	APP: Descrambler keys=[16]

            
            	APP: Type=[1]


            	CA_SEND_MSG

            
            	----------------------------

            
            	Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]

            
            	Found CA descriptor @ program level


            	(20) ES type=[2] ES pid=[201]  ES length =[0 (0x0)]

            
            	(25) ES type=[4] ES pid=[301]  ES length =[0 (0x0)]

            
            	ca_message length is 25 (0x19) bytes

            
            	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]


            Not all ioctl's are implemented in the driver from the API, the other

            
            features of the hardware that cannot be implemented by the API are achieved

            
            using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is

            
            used to exchange the data to maintain compatibility with other hardware.


            .. code-block:: c


            	/* a message to/from a CI-CAM */

            
            	typedef struct ca_msg {

            
            		unsigned int index;

            
            		unsigned int type;

            
            		unsigned int length;

            
            		unsigned char msg[256];

            
            	} ca_msg_t;


            The flow of data can be described thus,


            .. code-block:: none


            	App (User)

            
            	-----

            
            	parse

            
            	  |

            
            	  |

            
            	  v

            
            	en50221 APDU (package)

            
               --------------------------------------

            
               |	  |				| High Level CI driver

            
               |	  |				|

            
               |	  v				|

            
               |	en50221 APDU (unpackage)	|

            
               |	  |				|

            
               |	  |				|

            
               |	  v				|

            
               |	sanity checks			|

            
               |	  |				|

            
               |	  |				|

            
               |	  v				|

            
               |	do (H/W dep)			|

            
               --------------------------------------

            
            	  |    Hardware

            
            	  |

            
            	  v


            The High Level CI interface uses the EN50221 DVB standard, following a

            
            standard ensures futureproofness.
	Digital TV Conditional Access Interface (CI API)
	================================================


	.. note::

	This documentation is outdated.

	This document describes the usage of the high level CI API as
	in accordance to the Linux DVB API. This is a not a documentation for the,
	existing low level CI API.

	.. note::

	For the Twinhan/Twinhan clones, the dst_ca module handles the CI
	hardware handling.This module is loaded automatically if a CI
	(Common Interface, that holds the CAM (Conditional Access Module)
	is detected.

	ca_zap
	~~~~~~

	An userspace application, like ``ca_zap`` is required to handle encrypted
	MPEG-TS streams.

	The ``ca_zap`` userland application is in charge of sending the
	descrambling related information to the Conditional Access Module (CAM).

	This application requires the following to function properly as of now.

	a) Tune to a valid channel, with szap.

	eg: $ szap -c channels.conf -r "TMC" -x

	b) a channels.conf containing a valid PMT PID

	eg: TMC:11996:h:0:27500:278:512:650:321

	here 278 is a valid PMT PID. the rest of the values are the
	same ones that szap uses.

	c) after running a szap, you have to run ca_zap, for the
	descrambler to function,

	eg: $ ca_zap channels.conf "TMC"

	d) Hopefully enjoy your favourite subscribed channel as you do with
	a FTA card.

	.. note::

	Currently ca_zap, and dst_test, both are meant for demonstration
	purposes only, they can become full fledged applications if necessary.


	Cards that fall in this category
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	At present the cards that fall in this category are the Twinhan and its
	clones, these cards are available as VVMER, Tomato, Hercules, Orange and
	so on.

	CI modules that are supported
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	The CI module support is largely dependent upon the firmware on the cards
	Some cards do support almost all of the available CI modules. There is
	nothing much that can be done in order to make additional CI modules
	working with these cards.

	Modules that have been tested by this driver at present are

	(1) Irdeto 1 and 2 from SCM
	(2) Viaccess from SCM
	(3) Dragoncam

	The High level CI API
	~~~~~~~~~~~~~~~~~~~~~

	For the programmer
	^^^^^^^^^^^^^^^^^^

	With the High Level CI approach any new card with almost any random
	architecture can be implemented with this style, the definitions
	inside the switch statement can be easily adapted for any card, thereby
	eliminating the need for any additional ioctls.

	The disadvantage is that the driver/hardware has to manage the rest. For
	the application programmer it would be as simple as sending/receiving an
	array to/from the CI ioctls as defined in the Linux DVB API. No changes
	have been made in the API to accommodate this feature.


	Why the need for another CI interface?
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	This is one of the most commonly asked question. Well a nice question.
	Strictly speaking this is not a new interface.

	The CI interface is defined in the DVB API in ca.h as:

	.. code-block:: c

	typedef struct ca_slot_info {
	int num; /* slot number */

	int type; /* CA interface this slot supports */
	#define CA_CI 1 /* CI high level interface */
	#define CA_CI_LINK 2 /* CI link layer level interface */
	#define CA_CI_PHYS 4 /* CI physical layer level interface */
	#define CA_DESCR 8 /* built-in descrambler */
	#define CA_SC 128 /* simple smart card interface */

	unsigned int flags;
	#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
	#define CA_CI_MODULE_READY 2
	} ca_slot_info_t;

	This CI interface follows the CI high level interface, which is not
	implemented by most applications. Hence this area is revisited.

	This CI interface is quite different in the case that it tries to
	accommodate all other CI based devices, that fall into the other categories.

	This means that this CI interface handles the EN50221 style tags in the
	Application layer only and no session management is taken care of by the
	application. The driver/hardware will take care of all that.

	This interface is purely an EN50221 interface exchanging APDU's. This
	means that no session management, link layer or a transport layer do
	exist in this case in the application to driver communication. It is
	as simple as that. The driver/hardware has to take care of that.

	With this High Level CI interface, the interface can be defined with the
	regular ioctls.

	All these ioctls are also valid for the High level CI interface

	#define CA_RESET _IO('o', 128)
	#define CA_GET_CAP _IOR('o', 129, ca_caps_t)
	#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t)
	#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t)
	#define CA_GET_MSG _IOR('o', 132, ca_msg_t)
	#define CA_SEND_MSG _IOW('o', 133, ca_msg_t)
	#define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
	#define CA_SET_PID _IOW('o', 135, ca_pid_t)


	On querying the device, the device yields information thus:

	.. code-block:: none

	CA_GET_SLOT_INFO
	----------------------------
	Command = [info]
	APP: Number=[1]
	APP: Type=[1]
	APP: flags=[1]
	APP: CI High level interface
	APP: CA/CI Module Present

	CA_GET_CAP
	----------------------------
	Command = [caps]
	APP: Slots=[1]
	APP: Type=[1]
	APP: Descrambler keys=[16]
	APP: Type=[1]

	CA_SEND_MSG
	----------------------------
	Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
	Found CA descriptor @ program level

	(20) ES type=[2] ES pid=[201] ES length =[0 (0x0)]
	(25) ES type=[4] ES pid=[301] ES length =[0 (0x0)]
	ca_message length is 25 (0x19) bytes
	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]


	Not all ioctl's are implemented in the driver from the API, the other
	features of the hardware that cannot be implemented by the API are achieved
	using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
	used to exchange the data to maintain compatibility with other hardware.

	.. code-block:: c

	/* a message to/from a CI-CAM */
	typedef struct ca_msg {
	unsigned int index;
	unsigned int type;
	unsigned int length;
	unsigned char msg[256];
	} ca_msg_t;


	The flow of data can be described thus,

	.. code-block:: none

	App (User)
	-----
	parse
	\|
	\|
	v
	en50221 APDU (package)
	--------------------------------------
	\| \| \| High Level CI driver
	\| \| \|
	\| v \|
	\| en50221 APDU (unpackage) \|
	\| \| \|
	\| \| \|
	\| v \|
	\| sanity checks \|
	\| \| \|
	\| \| \|
	\| v \|
	\| do (H/W dep) \|
	--------------------------------------
	\| Hardware
	\|
	v




	The High Level CI interface uses the EN50221 DVB standard, following a
	standard ensures futureproofness.