Thanks to some discussions I had with Honza, I got some ideas about how to
document the last three undocumented ioctls from ca.h, together with the
two data structures.
With this series (and the previous one), everything at CA, Net, Demux
and DVBv5 Frontend DVB APIs are now documented. That's IMHO
a very good reason to celebrate! Yay!
Please notice that are still gaps at the DVB API documentation, but
those are related to legacy stuff that aren't touched for ages
(DVBv3 frontend API, audio.h, osd.h and video.h). The legacy
DVBv3 frontend API was completely replaced by DVBv5 API.
The other ones are used only by a single driver (av7110).
Mauro Carvalho Chehab (2):
media: ca docs: document CA_SET_DESCR ioctl and structs
media: ca.h: document ca_msg and the corresponding ioctls
Documentation/media/uapi/dvb/ca-get-msg.rst | 19 ++++++-------------
Documentation/media/uapi/dvb/ca-send-msg.rst | 6 +++++-
Documentation/media/uapi/dvb/ca-set-descr.rst | 15 ++-------------
include/uapi/linux/dvb/ca.h | 20 ++++++++++++++++++--
4 files changed, 31 insertions(+), 29 deletions(-)
--
2.13.5
The av7110 driver uses CA_SET_DESCR to store the descrambler
control words at the CA descrambler slots.
Document it.
Thanks-to: Honza Petrouš <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/media/uapi/dvb/ca-set-descr.rst | 15 ++-------------
include/uapi/linux/dvb/ca.h | 9 ++++++++-
2 files changed, 10 insertions(+), 14 deletions(-)
diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst b/Documentation/media/uapi/dvb/ca-set-descr.rst
index 9c484317d55c..a6c47205ffd8 100644
--- a/Documentation/media/uapi/dvb/ca-set-descr.rst
+++ b/Documentation/media/uapi/dvb/ca-set-descr.rst
@@ -28,22 +28,11 @@ Arguments
``msg``
Pointer to struct :c:type:`ca_descr`.
-.. c:type:: ca_descr
-
-.. code-block:: c
-
- struct ca_descr {
- unsigned int index;
- unsigned int parity;
- unsigned char cw[8];
- };
-
-
Description
-----------
-.. note:: This ioctl is undocumented. Documentation is welcome.
-
+CA_SET_DESCR is used for feeding descrambler CA slots with descrambling
+keys (refered as control words).
Return Value
------------
diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
index f66ed53f4dc7..a62ddf0cebcd 100644
--- a/include/uapi/linux/dvb/ca.h
+++ b/include/uapi/linux/dvb/ca.h
@@ -109,9 +109,16 @@ struct ca_msg {
unsigned char msg[256];
};
+/**
+ * struct ca_descr - CA descrambler control words info
+ *
+ * @index: CA Descrambler slot
+ * @parity: control words parity, where 0 means even and 1 means odd
+ * @cw: CA Descrambler control words
+ */
struct ca_descr {
unsigned int index;
- unsigned int parity; /* 0 == even, 1 == odd */
+ unsigned int parity;
unsigned char cw[8];
};
--
2.13.5
Usually, CA messages are sent/received via reading/writing at
the CA device node. However, two drivers (dst_ca and firedtv-ci)
also implement it via ioctls.
Apparently, on both cases, the net result is the same.
Anyway, let's document it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/media/uapi/dvb/ca-get-msg.rst | 19 ++++++-------------
Documentation/media/uapi/dvb/ca-send-msg.rst | 6 +++++-
include/uapi/linux/dvb/ca.h | 11 ++++++++++-
3 files changed, 21 insertions(+), 15 deletions(-)
diff --git a/Documentation/media/uapi/dvb/ca-get-msg.rst b/Documentation/media/uapi/dvb/ca-get-msg.rst
index bdb116552068..ceeda623ce93 100644
--- a/Documentation/media/uapi/dvb/ca-get-msg.rst
+++ b/Documentation/media/uapi/dvb/ca-get-msg.rst
@@ -28,22 +28,15 @@ Arguments
``msg``
Pointer to struct :c:type:`ca_msg`.
-.. c:type:: ca_msg
-
-.. code-block:: c
-
- /* a message to/from a CI-CAM */
- struct ca_msg {
- unsigned int index;
- unsigned int type;
- unsigned int length;
- unsigned char msg[256];
- };
-
Description
-----------
-.. note:: This ioctl is undocumented. Documentation is welcome.
+Receives a message via a CI CA module.
+
+.. note::
+
+ Please notice that, on most drivers, this is done by reading from
+ the /dev/adapter?/ca? device node.
Return Value
diff --git a/Documentation/media/uapi/dvb/ca-send-msg.rst b/Documentation/media/uapi/dvb/ca-send-msg.rst
index 644b6bda1aea..9e91287b7bbc 100644
--- a/Documentation/media/uapi/dvb/ca-send-msg.rst
+++ b/Documentation/media/uapi/dvb/ca-send-msg.rst
@@ -32,8 +32,12 @@ Arguments
Description
-----------
-.. note:: This ioctl is undocumented. Documentation is welcome.
+Sends a message via a CI CA module.
+.. note::
+
+ Please notice that, on most drivers, this is done by writing
+ to the /dev/adapter?/ca? device node.
Return Value
------------
diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
index a62ddf0cebcd..9bcd4cad497b 100644
--- a/include/uapi/linux/dvb/ca.h
+++ b/include/uapi/linux/dvb/ca.h
@@ -101,7 +101,16 @@ struct ca_caps {
unsigned int descr_type;
};
-/* a message to/from a CI-CAM */
+/**
+ * struct ca_msg - a message to/from a CI-CAM
+ *
+ * @index: unused
+ * @type: unused
+ * @length: length of the message
+ * @msg: message
+ *
+ * This struct carries a message to be send/received from a CI CA module.
+ */
struct ca_msg {
unsigned int index;
unsigned int type;
--
2.13.5