Merge tag 'media/v4.14-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

Pull media updates from Mauro Carvalho Chehab:
 "Brazil's Independence Day pull request :-)

  This is one of the biggest media pull requests, with 625 patches
  affecting almost all parts of media (RC, DVB, V4L2, CEC, docs).

  This contains:

   - A lot of new drivers:
     * DVB frontends: mxl5xx, stv0910, stv6111;
     * camera flash: as3645a led driver;
     * HDMI receiver: adv748X;
     * camera sensor: Omnivision 6650 5M driver (ov6650);
     * HDMI CEC: ao-cec meson driver;
     * V4L2: Qualcom camss driver;
     * Remote controller: gpio-ir-tx, pwm-ir-tx and zx-irdec drivers.

   - The DDbridge DVB driver got a massive update, with makes it in sync
     with modern hardware from that vendor;

   - There's an important milestone on this series: the DVB
     documentation was written in 2003, but only started to be updated
     in 2007. It also used to contain several gaps from the time it was
     kept out of tree, mentioning error codes and device nodes that
     never existed upstream. On this series, it received a massive
     update: all non-deprecated digital TV APIs are now in sync with the
     current implementation;

   - Some DVB APIs that aren't used by any upstream driver got removed;

   - Other parts of the media documentation algo got updated, fixing
     some bugs on its PDF output and making it compatible with Sphinx
     version 1.6.

     As the number of hacks required to build PDF output reduced, I hope
     we'll have less troubles as newer versions of our documentation
     toolchain are released (famous last words);

   - As usual, lots of driver cleanups and improvements"

* tag 'media/v4.14-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (624 commits)
  media: leds: as3645a: add V4L2_FLASH_LED_CLASS dependency
  media: get rid of removed DMX_GET_CAPS and DMX_SET_SOURCE leftovers
  media: Revert "[media] v4l: async: make v4l2 coexist with devicetree nodes in a dt overlay"
  media: staging: atomisp: sh_css_calloc shall return a pointer to the allocated space
  media: Revert "[media] lirc_dev: remove superfluous get/put_device() calls"
  media: add qcom_camss.rst to v4l-drivers rst file
  media: dvb headers: make checkpatch happier
  media: dvb uapi: move frontend legacy API to another part of the book
  media: pixfmt-srggb12p.rst: better format the table for PDF output
  media: docs-rst: media: Don't use \small for V4L2_PIX_FMT_SRGGB10 documentation
  media: index.rst: don't write "Contents:" on PDF output
  media: pixfmt*.rst: replace a two dots by a comma
  media: vidioc-g-fmt.rst: adjust table format
  media: vivid.rst: add a blank line to correct ReST format
  media: v4l2 uapi book: get rid of driver programming's chapter
  media: format.rst: use the right markup for important notes
  media: docs-rst: cardlists: change their format to flat-tables
  media: em28xx-cardlist.rst: update to reflect last changes
  media: v4l2-event.rst: adjust table to fit on PDF output
  media: docs: don't show ToC for each part on PDF output
  ...

1 files changed, 106 insertions, 42 deletions

diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
index c18537f3e449..cb150029fdff 100644
--- a/include/uapi/linux/dvb/ca.h
+++ b/include/uapi/linux/dvb/ca.h
@@ -24,67 +24,131 @@
 #ifndef _DVBCA_H_
 #define _DVBCA_H_
 
-/* slot interface types and info */
-
-typedef struct ca_slot_info {
-	int num;               /* slot number */
+/**
+ * struct ca_slot_info - CA slot interface types and info.
+ *
+ * @num:	slot number.
+ * @type:	slot type.
+ * @flags:	flags applicable to the slot.
+ *
+ * This struct stores the CA slot information.
+ *
+ * @type can be:
+ *
+ *	- %CA_CI - CI high level interface;
+ *	- %CA_CI_LINK - CI link layer level interface;
+ *	- %CA_CI_PHYS - CI physical layer level interface;
+ *	- %CA_DESCR - built-in descrambler;
+ *	- %CA_SC -simple smart card interface.
+ *
+ * @flags can be:
+ *
+ *	- %CA_CI_MODULE_PRESENT - module (or card) inserted;
+ *	- %CA_CI_MODULE_READY - module is ready for usage.
+ */
 
-	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 */
+struct ca_slot_info {
+	int num;
+	int type;
+#define CA_CI            1
+#define CA_CI_LINK       2
+#define CA_CI_PHYS       4
+#define CA_DESCR         8
+#define CA_SC          128
 
 	unsigned int flags;
-#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
+#define CA_CI_MODULE_PRESENT 1
 #define CA_CI_MODULE_READY   2
-} ca_slot_info_t;
-
+};
 
-/* descrambler types and info */
 
-typedef struct ca_descr_info {
-	unsigned int num;          /* number of available descramblers (keys) */
-	unsigned int type;         /* type of supported scrambling system */
+/**
+ * struct ca_descr_info - descrambler types and info.
+ *
+ * @num:	number of available descramblers (keys).
+ * @type:	type of supported scrambling system.
+ *
+ * Identifies the number of descramblers and their type.
+ *
+ * @type can be:
+ *
+ *	- %CA_ECD - European Common Descrambler (ECD) hardware;
+ *	- %CA_NDS - Videoguard (NDS) hardware;
+ *	- %CA_DSS - Distributed Sample Scrambling (DSS) hardware.
+ */
+struct ca_descr_info {
+	unsigned int num;
+	unsigned int type;
 #define CA_ECD           1
 #define CA_NDS           2
 #define CA_DSS           4
-} ca_descr_info_t;
+};
 
-typedef struct ca_caps {
-	unsigned int slot_num;     /* total number of CA card and module slots */
-	unsigned int slot_type;    /* OR of all supported types */
-	unsigned int descr_num;    /* total number of descrambler slots (keys) */
-	unsigned int descr_type;   /* OR of all supported types */
-} ca_caps_t;
+/**
+ * struct ca_caps - CA slot interface capabilities.
+ *
+ * @slot_num:	total number of CA card and module slots.
+ * @slot_type:	bitmap with all supported types as defined at
+ *		&struct ca_slot_info (e. g. %CA_CI, %CA_CI_LINK, etc).
+ * @descr_num:	total number of descrambler slots (keys)
+ * @descr_type:	bitmap with all supported types as defined at
+ *		&struct ca_descr_info (e. g. %CA_ECD, %CA_NDS, etc).
+ */
+struct ca_caps {
+	unsigned int slot_num;
+	unsigned int slot_type;
+	unsigned int descr_num;
+	unsigned int descr_type;
+};
 
-/* a message to/from a CI-CAM */
-typedef struct ca_msg {
+/**
+ * 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;
 	unsigned int length;
 	unsigned char msg[256];
-} ca_msg_t;
+};
 
-typedef struct ca_descr {
+/**
+ * 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];
-} ca_descr_t;
-
-typedef struct ca_pid {
-	unsigned int pid;
-	int index;		/* -1 == disable*/
-} ca_pid_t;
+};
 
 #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)
+#define CA_GET_CAP        _IOR('o', 129, struct ca_caps)
+#define CA_GET_SLOT_INFO  _IOR('o', 130, struct ca_slot_info)
+#define CA_GET_DESCR_INFO _IOR('o', 131, struct ca_descr_info)
+#define CA_GET_MSG        _IOR('o', 132, struct ca_msg)
+#define CA_SEND_MSG       _IOW('o', 133, struct ca_msg)
+#define CA_SET_DESCR      _IOW('o', 134, struct ca_descr)
+
+#if !defined(__KERNEL__)
+
+/* This is needed for legacy userspace support */
+typedef struct ca_slot_info ca_slot_info_t;
+typedef struct ca_descr_info  ca_descr_info_t;
+typedef struct ca_caps  ca_caps_t;
+typedef struct ca_msg ca_msg_t;
+typedef struct ca_descr ca_descr_t;
+
+#endif
+
 
 #endif