Commit c1eaa6c4 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

[media] doc-rst: Convert ci.txt to a rst file

The old ci.txt file had a very peculiar format, with doesn't
match any markup language I know. Change it to be on ReST
format, for it to be parsed by Sphinx.

Also, as this is an old document, add a note about it.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 986fd9a9
* For the user Digital TV Conditional Access Interface (CI API)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ================================================
NOTE: This document describes the usage of the high level CI API as
.. 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, in accordance to the Linux DVB API. This is a not a documentation for the,
existing low level CI API. existing low level CI API.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To utilize the High Level CI capabilities, .. note::
(1*) This point is valid only for the Twinhan/clones
For the Twinhan/Twinhan clones, the dst_ca module handles the CI For the Twinhan/Twinhan clones, the dst_ca module handles the CI
hardware handling.This module is loaded automatically if a CI hardware handling.This module is loaded automatically if a CI
(Common Interface, that holds the CAM (Conditional Access Module) (Common Interface, that holds the CAM (Conditional Access Module)
is detected. is detected.
(2) one requires a userspace application, ca_zap. This small userland ca_zap
application is in charge of sending the descrambling related information ~~~~~~
to the CAM.
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. This application requires the following to function properly as of now.
(a) Tune to a valid channel, with szap. a) Tune to a valid channel, with szap.
eg: $ szap -c channels.conf -r "TMC" -x eg: $ szap -c channels.conf -r "TMC" -x
(b) a channels.conf containing a valid PMT PID b) a channels.conf containing a valid PMT PID
eg: TMC:11996:h:0:27500:278:512:650:321 eg: TMC:11996:h:0:27500:278:512:650:321
here 278 is a valid PMT PID. the rest of the values are the here 278 is a valid PMT PID. the rest of the values are the
same ones that szap uses. same ones that szap uses.
(c) after running a szap, you have to run ca_zap, for the c) after running a szap, you have to run ca_zap, for the
descrambler to function, descrambler to function,
eg: $ ca_zap channels.conf "TMC" eg: $ ca_zap channels.conf "TMC"
(d) Hopefully enjoy your favourite subscribed channel as you do with d) Hopefully enjoy your favourite subscribed channel as you do with
a FTA card. a FTA card.
(3) Currently ca_zap, and dst_test, both are meant for demonstration .. note::
Currently ca_zap, and dst_test, both are meant for demonstration
purposes only, they can become full fledged applications if necessary. purposes only, they can become full fledged applications if necessary.
* Cards that fall in this category Cards that fall in this category
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At present the cards that fall in this category are the Twinhan and its 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 clones, these cards are available as VVMER, Tomato, Hercules, Orange and
so on. so on.
* CI modules that are supported CI modules that are supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The CI module support is largely dependent upon the firmware on the cards 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 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 nothing much that can be done in order to make additional CI modules
...@@ -58,11 +74,12 @@ Modules that have been tested by this driver at present are ...@@ -58,11 +74,12 @@ Modules that have been tested by this driver at present are
(2) Viaccess from SCM (2) Viaccess from SCM
(3) Dragoncam (3) Dragoncam
* The High level CI API The High level CI API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
For the programmer
^^^^^^^^^^^^^^^^^^
* For the programmer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
With the High Level CI approach any new card with almost any random With the High Level CI approach any new card with almost any random
architecture can be implemented with this style, the definitions architecture can be implemented with this style, the definitions
inside the switch statement can be easily adapted for any card, thereby inside the switch statement can be easily adapted for any card, thereby
...@@ -74,29 +91,30 @@ array to/from the CI ioctls as defined in the Linux DVB API. No changes ...@@ -74,29 +91,30 @@ 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. have been made in the API to accommodate this feature.
* Why the need for another CI interface ? Why the need for another CI interface?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is one of the most commonly asked question. Well a nice question. This is one of the most commonly asked question. Well a nice question.
Strictly speaking this is not a new interface. Strictly speaking this is not a new interface.
The CI interface is defined in the DVB API in ca.h as The CI interface is defined in the DVB API in ca.h as:
typedef struct ca_slot_info { .. code-block:: c
typedef struct ca_slot_info {
int num; /* slot number */ int num; /* slot number */
int type; /* CA interface this slot supports */ int type; /* CA interface this slot supports */
#define CA_CI 1 /* CI high level interface */ #define CA_CI 1 /* CI high level interface */
#define CA_CI_LINK 2 /* CI link layer level interface */ #define CA_CI_LINK 2 /* CI link layer level interface */
#define CA_CI_PHYS 4 /* CI physical layer level interface */ #define CA_CI_PHYS 4 /* CI physical layer level interface */
#define CA_DESCR 8 /* built-in descrambler */ #define CA_DESCR 8 /* built-in descrambler */
#define CA_SC 128 /* simple smart card interface */ #define CA_SC 128 /* simple smart card interface */
unsigned int flags; unsigned int flags;
#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
#define CA_CI_MODULE_READY 2 #define CA_CI_MODULE_READY 2
} ca_slot_info_t; } ca_slot_info_t;
This CI interface follows the CI high level interface, which is not This CI interface follows the CI high level interface, which is not
implemented by most applications. Hence this area is revisited. implemented by most applications. Hence this area is revisited.
...@@ -113,7 +131,6 @@ means that no session management, link layer or a transport layer do ...@@ -113,7 +131,6 @@ means that no session management, link layer or a transport layer do
exist in this case in the application to driver communication. It is 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. 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 With this High Level CI interface, the interface can be defined with the
regular ioctls. regular ioctls.
...@@ -129,34 +146,36 @@ All these ioctls are also valid for the High level CI interface ...@@ -129,34 +146,36 @@ All these ioctls are also valid for the High level CI interface
#define CA_SET_PID _IOW('o', 135, ca_pid_t) #define CA_SET_PID _IOW('o', 135, ca_pid_t)
On querying the device, the device yields information thus On querying the device, the device yields information thus:
.. code-block:: none
CA_GET_SLOT_INFO CA_GET_SLOT_INFO
---------------------------- ----------------------------
Command = [info] Command = [info]
APP: Number=[1] APP: Number=[1]
APP: Type=[1] APP: Type=[1]
APP: flags=[1] APP: flags=[1]
APP: CI High level interface APP: CI High level interface
APP: CA/CI Module Present APP: CA/CI Module Present
CA_GET_CAP CA_GET_CAP
---------------------------- ----------------------------
Command = [caps] Command = [caps]
APP: Slots=[1] APP: Slots=[1]
APP: Type=[1] APP: Type=[1]
APP: Descrambler keys=[16] APP: Descrambler keys=[16]
APP: Type=[1] APP: Type=[1]
CA_SEND_MSG CA_SEND_MSG
---------------------------- ----------------------------
Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1] Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
Found CA descriptor @ program level Found CA descriptor @ program level
(20) ES type=[2] ES pid=[201] ES length =[0 (0x0)] (20) ES type=[2] ES pid=[201] ES length =[0 (0x0)]
(25) ES type=[4] ES pid=[301] ES length =[0 (0x0)] (25) ES type=[4] ES pid=[301] ES length =[0 (0x0)]
ca_message length is 25 (0x19) bytes 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] 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 Not all ioctl's are implemented in the driver from the API, the other
...@@ -164,21 +183,20 @@ features of the hardware that cannot be implemented by the API are achieved ...@@ -164,21 +183,20 @@ 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 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. used to exchange the data to maintain compatibility with other hardware.
.. code-block:: c
/* a message to/from a CI-CAM */ /* a message to/from a CI-CAM */
typedef struct ca_msg { typedef struct ca_msg {
unsigned int index; unsigned int index;
unsigned int type; unsigned int type;
unsigned int length; unsigned int length;
unsigned char msg[256]; unsigned char msg[256];
} ca_msg_t; } ca_msg_t;
The flow of data can be described thus, The flow of data can be described thus,
.. code-block:: none
App (User) App (User)
----- -----
......
...@@ -22,3 +22,4 @@ License". ...@@ -22,3 +22,4 @@ License".
avermedia avermedia
bt8xx bt8xx
cards cards
ci
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment