* [PATCH v2 00/26] Improve DVB documentation and reduce its gap
@ 2017-09-01 13:24 Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 01/27] media: ca.h: split typedefs from structs Mauro Carvalho Chehab
` (28 more replies)
0 siblings, 29 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The DVB documentation was negligected for a long time, with
resulted on several gaps between the API description and its
documentation.
I'm doing a new reading at the documentation. As result of it,
this series:
- improves the introductory chapter, making it more generic;
- Do some adjustments at the frontend API, using kernel-doc
when possible.
- Remove unused APIs at DVB demux. I suspect that the drivers
implementing such APIs were either never merged upstream,
or the API itself were never used or was deprecated a long
time ago. In any case, it doesn't make any sense to carry
on APIs that aren't properly documented, nor are used on the
upstream Kernel.
With this patch series, the gap between documentation and
code is solved for 3 DVB APIs:
- Frontend API;
- Demux API;
- Net API.
There is still a gap at the CA API, as there are three ioctls that are used
only by a few drivers and whose structs are not properly documented:
CA_GET_MSG, CA_SEND_MSG and CA_SET_DESCR.
The first two ones seem to be related to a way that a few drivers
provide to send/receive messages. Yet, I was unable to get what
"index" and "type" means on those ioctls. The CA_SET_DESCR is
only supported by av7110 driver, and has an even weirder
undocumented struct. I was unable to discover at the Kernel, VDR
or Kaffeine how those structs are filled. I suspect that there's
something wrong there, but I won't risk trying to fix without
knowing more about them. So, let's just document that those
are needing documentation :-)
---
v2: Added CA API patches at the end and verified that everything
compiles after each patch. Also do some fixes at dst_ca for it
to report the error code to userspace and remove boilerplate
code there.
Mauro Carvalho Chehab (27):
media: ca.h: split typedefs from structs
media: dmx.h: split typedefs from structs
media: dvb/intro: use the term Digital TV to refer to the system
media: dvb/intro: update references for TV standards
media: dvb/intro: update the history part of the document
media: dvb/intro: adjust the notices about optional hardware
media: dvb/frontend.h: move out a private internal structure
media: dvb/frontend.h: document the uAPI file
media: dvb frontend docs: use kernel-doc documentation
media: fe_property_parameters.rst: better define properties usage
media: fe_property_parameters.rst: better document bandwidth
media: dmx.h: get rid of unused DMX_KERNEL_CLIENT
media: dmx.h: get rid of DMX_GET_CAPS
media: dmx.h: get rid of DMX_SET_SOURCE
media: dmx.h: get rid of GET_DMX_EVENT
media: dmx.h: add kernel-doc markups and use it at Documentation/
media: net.rst: Fix the level of a section of the net chapter
media: ca.h: get rid of CA_SET_PID
media: ca.h: document most CA data types
media: dst_ca: return a proper error code from CA errors
media: ca-reset.rst: add some description to this ioctl
media: ca-get-cap.rst: document this ioctl
media: ca-get-slot-info.rst: document this ioctl
media: ca-get-descr-info.rst: document this ioctl
media: dvb CA docs: place undocumented data together with ioctls
media: dvb rst: identify the documentation gap at the API
media: dst_ca: remove CA_SET_DESCR boilerplate
Documentation/media/ca.h.rst.exceptions | 1 -
Documentation/media/dmx.h.rst.exceptions | 20 +-
Documentation/media/dvb-drivers/ci.rst | 1 -
Documentation/media/frontend.h.rst.exceptions | 185 ++-
Documentation/media/uapi/dvb/ca-get-cap.rst | 36 +-
Documentation/media/uapi/dvb/ca-get-descr-info.rst | 29 +-
Documentation/media/uapi/dvb/ca-get-msg.rst | 38 +-
Documentation/media/uapi/dvb/ca-get-slot-info.rst | 98 +-
Documentation/media/uapi/dvb/ca-reset.rst | 3 +-
Documentation/media/uapi/dvb/ca-set-descr.rst | 10 +
Documentation/media/uapi/dvb/ca-set-pid.rst | 60 -
Documentation/media/uapi/dvb/ca.rst | 5 +
Documentation/media/uapi/dvb/ca_data_types.rst | 103 +-
Documentation/media/uapi/dvb/ca_function_calls.rst | 1 -
Documentation/media/uapi/dvb/dmx-get-caps.rst | 41 -
Documentation/media/uapi/dvb/dmx-get-event.rst | 60 -
Documentation/media/uapi/dvb/dmx-set-source.rst | 44 -
Documentation/media/uapi/dvb/dmx_fcalls.rst | 3 -
Documentation/media/uapi/dvb/dmx_types.rst | 225 +---
Documentation/media/uapi/dvb/dtv-fe-stats.rst | 17 -
Documentation/media/uapi/dvb/dtv-properties.rst | 15 -
Documentation/media/uapi/dvb/dtv-property.rst | 31 -
Documentation/media/uapi/dvb/dtv-stats.rst | 18 -
Documentation/media/uapi/dvb/dvbproperty-006.rst | 12 -
Documentation/media/uapi/dvb/dvbproperty.rst | 28 +-
.../media/uapi/dvb/fe-diseqc-recv-slave-reply.rst | 40 +-
.../media/uapi/dvb/fe-diseqc-send-burst.rst | 31 +-
.../media/uapi/dvb/fe-diseqc-send-master-cmd.rst | 29 +-
Documentation/media/uapi/dvb/fe-get-info.rst | 370 +-----
Documentation/media/uapi/dvb/fe-get-property.rst | 2 +-
Documentation/media/uapi/dvb/fe-read-status.rst | 83 --
Documentation/media/uapi/dvb/fe-set-tone.rst | 30 -
.../media/uapi/dvb/fe_property_parameters.rst | 1383 +++-----------------
Documentation/media/uapi/dvb/frontend-header.rst | 4 +
Documentation/media/uapi/dvb/intro.rst | 76 +-
Documentation/media/uapi/dvb/legacy_dvb_apis.rst | 5 +
Documentation/media/uapi/dvb/net.rst | 1 -
drivers/media/dvb-core/dmxdev.c | 4 +-
drivers/media/dvb-core/dvb_frontend.c | 11 +
drivers/media/pci/bt8xx/dst_ca.c | 70 +-
drivers/media/pci/ttpci/av7110.h | 2 +-
drivers/media/pci/ttpci/av7110_ca.c | 12 +-
include/uapi/linux/dvb/ca.h | 128 +-
include/uapi/linux/dvb/dmx.h | 191 ++-
include/uapi/linux/dvb/frontend.h | 591 +++++++--
45 files changed, 1267 insertions(+), 2880 deletions(-)
delete mode 100644 Documentation/media/uapi/dvb/ca-set-pid.rst
delete mode 100644 Documentation/media/uapi/dvb/dmx-get-caps.rst
delete mode 100644 Documentation/media/uapi/dvb/dmx-get-event.rst
delete mode 100644 Documentation/media/uapi/dvb/dmx-set-source.rst
delete mode 100644 Documentation/media/uapi/dvb/dtv-fe-stats.rst
delete mode 100644 Documentation/media/uapi/dvb/dtv-properties.rst
delete mode 100644 Documentation/media/uapi/dvb/dtv-property.rst
delete mode 100644 Documentation/media/uapi/dvb/dtv-stats.rst
delete mode 100644 Documentation/media/uapi/dvb/dvbproperty-006.rst
create mode 100644 Documentation/media/uapi/dvb/frontend-header.rst
--
2.13.5
^ permalink raw reply [flat|nested] 36+ messages in thread
* [PATCH v2 01/27] media: ca.h: split typedefs from structs
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 02/27] media: dmx.h: " Mauro Carvalho Chehab
` (27 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sakari Ailus
Using typedefs inside the Kernel is against CodingStyle, and
there's no good usage here.
Just like we did at frontend.h, at changeset 0df289a209e0
("[media] dvb: Get rid of typedev usage for enums"), let's keep
those typedefs only to provide userspace backward compatibility.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/media/pci/ttpci/av7110.h | 2 +-
drivers/media/pci/ttpci/av7110_ca.c | 12 ++++-----
include/uapi/linux/dvb/ca.h | 51 +++++++++++++++++++++++--------------
3 files changed, 39 insertions(+), 26 deletions(-)
diff --git a/drivers/media/pci/ttpci/av7110.h b/drivers/media/pci/ttpci/av7110.h
index 824c1e262fbb..347827925c14 100644
--- a/drivers/media/pci/ttpci/av7110.h
+++ b/drivers/media/pci/ttpci/av7110.h
@@ -177,7 +177,7 @@ struct av7110 {
/* CA */
- ca_slot_info_t ci_slot[2];
+ struct ca_slot_info ci_slot[2];
enum av7110_video_mode vidmode;
struct dmxdev dmxdev;
diff --git a/drivers/media/pci/ttpci/av7110_ca.c b/drivers/media/pci/ttpci/av7110_ca.c
index f64723aea56b..1fe49171d823 100644
--- a/drivers/media/pci/ttpci/av7110_ca.c
+++ b/drivers/media/pci/ttpci/av7110_ca.c
@@ -119,7 +119,7 @@ static void ci_ll_release(struct dvb_ringbuffer *cirbuf, struct dvb_ringbuffer *
}
static int ci_ll_reset(struct dvb_ringbuffer *cibuf, struct file *file,
- int slots, ca_slot_info_t *slot)
+ int slots, struct ca_slot_info *slot)
{
int i;
int len = 0;
@@ -264,7 +264,7 @@ static int dvb_ca_ioctl(struct file *file, unsigned int cmd, void *parg)
break;
case CA_GET_CAP:
{
- ca_caps_t cap;
+ struct ca_caps cap;
cap.slot_num = 2;
cap.slot_type = (FW_CI_LL_SUPPORT(av7110->arm_app) ?
@@ -277,7 +277,7 @@ static int dvb_ca_ioctl(struct file *file, unsigned int cmd, void *parg)
case CA_GET_SLOT_INFO:
{
- ca_slot_info_t *info=(ca_slot_info_t *)parg;
+ struct ca_slot_info *info=(struct ca_slot_info *)parg;
if (info->num < 0 || info->num > 1) {
mutex_unlock(&av7110->ioctl_mutex);
@@ -286,7 +286,7 @@ static int dvb_ca_ioctl(struct file *file, unsigned int cmd, void *parg)
av7110->ci_slot[info->num].num = info->num;
av7110->ci_slot[info->num].type = FW_CI_LL_SUPPORT(av7110->arm_app) ?
CA_CI_LINK : CA_CI;
- memcpy(info, &av7110->ci_slot[info->num], sizeof(ca_slot_info_t));
+ memcpy(info, &av7110->ci_slot[info->num], sizeof(struct ca_slot_info));
break;
}
@@ -298,7 +298,7 @@ static int dvb_ca_ioctl(struct file *file, unsigned int cmd, void *parg)
case CA_GET_DESCR_INFO:
{
- ca_descr_info_t info;
+ struct ca_descr_info info;
info.num = 16;
info.type = CA_ECD;
@@ -308,7 +308,7 @@ static int dvb_ca_ioctl(struct file *file, unsigned int cmd, void *parg)
case CA_SET_DESCR:
{
- ca_descr_t *descr = (ca_descr_t*) parg;
+ struct ca_descr *descr = (struct ca_descr*) parg;
if (descr->index >= 16 || descr->parity > 1) {
mutex_unlock(&av7110->ioctl_mutex);
diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
index c18537f3e449..00cf24587bea 100644
--- a/include/uapi/linux/dvb/ca.h
+++ b/include/uapi/linux/dvb/ca.h
@@ -26,7 +26,7 @@
/* slot interface types and info */
-typedef struct ca_slot_info {
+struct ca_slot_info {
int num; /* slot number */
int type; /* CA interface this slot supports */
@@ -39,52 +39,65 @@ typedef struct ca_slot_info {
unsigned int flags;
#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
#define CA_CI_MODULE_READY 2
-} ca_slot_info_t;
+};
/* descrambler types and info */
-typedef struct ca_descr_info {
+struct ca_descr_info {
unsigned int num; /* number of available descramblers (keys) */
unsigned int type; /* type of supported scrambling system */
#define CA_ECD 1
#define CA_NDS 2
#define CA_DSS 4
-} ca_descr_info_t;
+};
-typedef struct ca_caps {
+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;
+};
/* a message to/from a CI-CAM */
-typedef struct ca_msg {
+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 {
unsigned int index;
unsigned int parity; /* 0 == even, 1 == odd */
unsigned char cw[8];
-} ca_descr_t;
+};
-typedef struct ca_pid {
+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)
+#define CA_SET_PID _IOW('o', 135, struct ca_pid)
+
+#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;
+typedef struct ca_pid ca_pid_t;
+
+#endif
+
#endif
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 02/27] media: dmx.h: split typedefs from structs
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 01/27] media: ca.h: split typedefs from structs Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 03/27] media: dvb/intro: use the term Digital TV to refer to the system Mauro Carvalho Chehab
` (26 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sakari Ailus, Thomas Gleixner, devendra sharma
Using typedefs inside the Kernel is against CodingStyle, and
there's no good usage here.
Just like we did at frontend.h, at changeset 0df289a209e0
("[media] dvb: Get rid of typedev usage for enums"), let's keep
those typedefs only to provide userspace backward compatibility.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/media/dvb-core/dmxdev.c | 4 +--
include/uapi/linux/dvb/dmx.h | 56 ++++++++++++++++++++++++-----------------
2 files changed, 35 insertions(+), 25 deletions(-)
diff --git a/drivers/media/dvb-core/dmxdev.c b/drivers/media/dvb-core/dmxdev.c
index 45e91add73ba..16b0b74c3114 100644
--- a/drivers/media/dvb-core/dmxdev.c
+++ b/drivers/media/dvb-core/dmxdev.c
@@ -562,7 +562,7 @@ static int dvb_dmxdev_start_feed(struct dmxdev *dmxdev,
{
ktime_t timeout = 0;
struct dmx_pes_filter_params *para = &filter->params.pes;
- dmx_output_t otype;
+ enum dmx_output otype;
int ret;
int ts_type;
enum dmx_ts_pes ts_pes;
@@ -787,7 +787,7 @@ static int dvb_dmxdev_filter_free(struct dmxdev *dmxdev,
return 0;
}
-static inline void invert_mode(dmx_filter_t *filter)
+static inline void invert_mode(struct dmx_filter *filter)
{
int i;
diff --git a/include/uapi/linux/dvb/dmx.h b/include/uapi/linux/dvb/dmx.h
index 427e4899ed69..1bc4d6fb0f01 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -43,16 +43,14 @@ enum dmx_output
DMX_OUT_TSDEMUX_TAP /* Like TS_TAP but retrieved from the DMX device */
};
-typedef enum dmx_output dmx_output_t;
-
-typedef enum dmx_input
+enum dmx_input
{
DMX_IN_FRONTEND, /* Input from a front-end device. */
DMX_IN_DVR /* Input from the logical DVR device. */
-} dmx_input_t;
+};
-typedef enum dmx_ts_pes
+enum dmx_ts_pes
{
DMX_PES_AUDIO0,
DMX_PES_VIDEO0,
@@ -79,7 +77,7 @@ typedef enum dmx_ts_pes
DMX_PES_PCR3,
DMX_PES_OTHER
-} dmx_pes_type_t;
+};
#define DMX_PES_AUDIO DMX_PES_AUDIO0
#define DMX_PES_VIDEO DMX_PES_VIDEO0
@@ -88,20 +86,20 @@ typedef enum dmx_ts_pes
#define DMX_PES_PCR DMX_PES_PCR0
-typedef struct dmx_filter
+struct dmx_filter
{
__u8 filter[DMX_FILTER_SIZE];
__u8 mask[DMX_FILTER_SIZE];
__u8 mode[DMX_FILTER_SIZE];
-} dmx_filter_t;
+};
struct dmx_sct_filter_params
{
- __u16 pid;
- dmx_filter_t filter;
- __u32 timeout;
- __u32 flags;
+ __u16 pid;
+ struct dmx_filter filter;
+ __u32 timeout;
+ __u32 flags;
#define DMX_CHECK_CRC 1
#define DMX_ONESHOT 2
#define DMX_IMMEDIATE_START 4
@@ -111,19 +109,19 @@ struct dmx_sct_filter_params
struct dmx_pes_filter_params
{
- __u16 pid;
- dmx_input_t input;
- dmx_output_t output;
- dmx_pes_type_t pes_type;
- __u32 flags;
+ __u16 pid;
+ enum dmx_input input;
+ enum dmx_output output;
+ enum dmx_ts_pes pes_type;
+ __u32 flags;
};
-typedef struct dmx_caps {
+struct dmx_caps {
__u32 caps;
int num_decoders;
-} dmx_caps_t;
+};
-typedef enum dmx_source {
+enum dmx_source {
DMX_SOURCE_FRONT0 = 0,
DMX_SOURCE_FRONT1,
DMX_SOURCE_FRONT2,
@@ -132,7 +130,7 @@ typedef enum dmx_source {
DMX_SOURCE_DVR1,
DMX_SOURCE_DVR2,
DMX_SOURCE_DVR3
-} dmx_source_t;
+};
struct dmx_stc {
unsigned int num; /* input : which STC? 0..N */
@@ -146,10 +144,22 @@ struct dmx_stc {
#define DMX_SET_PES_FILTER _IOW('o', 44, struct dmx_pes_filter_params)
#define DMX_SET_BUFFER_SIZE _IO('o', 45)
#define DMX_GET_PES_PIDS _IOR('o', 47, __u16[5])
-#define DMX_GET_CAPS _IOR('o', 48, dmx_caps_t)
-#define DMX_SET_SOURCE _IOW('o', 49, dmx_source_t)
+#define DMX_GET_CAPS _IOR('o', 48, struct dmx_caps)
+#define DMX_SET_SOURCE _IOW('o', 49, enum dmx_source)
#define DMX_GET_STC _IOWR('o', 50, struct dmx_stc)
#define DMX_ADD_PID _IOW('o', 51, __u16)
#define DMX_REMOVE_PID _IOW('o', 52, __u16)
+#if !defined (__KERNEL__)
+
+/* This is needed for legacy userspace support */
+typedef enum dmx_output dmx_output_t;
+typedef enum dmx_input dmx_input_t;
+typedef enum dmx_ts_pes dmx_pes_type_t;
+typedef struct dmx_filter dmx_filter_t;
+typedef struct dmx_caps dmx_caps_t;
+typedef enum dmx_source dmx_source_t;
+
+#endif
+
#endif /* _UAPI_DVBDMX_H_ */
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 03/27] media: dvb/intro: use the term Digital TV to refer to the system
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 01/27] media: ca.h: split typedefs from structs Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 02/27] media: dmx.h: " Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 04/27] media: dvb/intro: update references for TV standards Mauro Carvalho Chehab
` (25 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
On several places at the introduction, a digital TV board and its
kernel support is called as DVB. The reason is simple: by the
time the document was written, there were no other digital TV
standards :-)
Modernize the specs by referring to them as Digital TV.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/intro.rst | 24 ++++++++++++------------
1 file changed, 12 insertions(+), 12 deletions(-)
diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index 20bd7aec2665..de432ffcba50 100644
--- a/Documentation/media/uapi/dvb/intro.rst
+++ b/Documentation/media/uapi/dvb/intro.rst
@@ -13,7 +13,7 @@ What you need to know
=====================
The reader of this document is required to have some knowledge in the
-area of digital video broadcasting (DVB) and should be familiar with
+area of digital video broadcasting (Digital TV) and should be familiar with
part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
you should know what a program/transport stream (PS/TS) is and what is
meant by a packetized elementary stream (PES) or an I-frame.
@@ -59,14 +59,14 @@ Overview
:alt: dvbstb.svg
:align: center
- Components of a DVB card/STB
+ Components of a Digital TV card/STB
-A DVB PCI card or DVB set-top-box (STB) usually consists of the
+A Digital TV card or set-top-box (STB) usually consists of the
following main hardware components:
-- Frontend consisting of tuner and DVB demodulator
+- Frontend consisting of tuner and digital TV demodulator
- Here the raw signal reaches the DVB hardware from a satellite dish or
+ Here the raw signal reaches the digital TV hardware from a satellite dish or
antenna or directly from cable. The frontend down-converts and
demodulates this signal into an MPEG transport stream (TS). In case
of a satellite frontend, this includes a facility for satellite
@@ -105,10 +105,10 @@ conditional access hardware.
.. _dvb_devices:
-Linux DVB Devices
-=================
+Linux Digital TV Devices
+========================
-The Linux DVB API lets you control these hardware components through
+The Linux Digital TV API lets you control these hardware components through
currently six Unix-style character devices for video, audio, frontend,
demux, CA and IP-over-DVB networking. The video and audio devices
control the MPEG2 decoder hardware, the frontend device the tuner and
@@ -137,8 +137,8 @@ individual devices are called:
- ``/dev/dvb/adapterN/caM``,
-where ``N`` enumerates the DVB PCI cards in a system starting from 0, and ``M``
-enumerates the devices of each type within each adapter, starting
+where ``N`` enumerates the Digital TV cards in a system starting from 0, and
+``M`` enumerates the devices of each type within each adapter, starting
from 0, too. We will omit the “``/dev/dvb/adapterN/``\ ” in the further
discussion of these devices.
@@ -151,8 +151,8 @@ devices are described in the following chapters.
API include files
=================
-For each of the DVB devices a corresponding include file exists. The DVB
-API include files should be included in application sources with a
+For each of the Digital TV devices a corresponding include file exists. The
+Digital TV API include files should be included in application sources with a
partial path like:
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 04/27] media: dvb/intro: update references for TV standards
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (2 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 03/27] media: dvb/intro: use the term Digital TV to refer to the system Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 05/27] media: dvb/intro: update the history part of the document Mauro Carvalho Chehab
` (24 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The references there are only for DVB. Add missing references for
ATSC and ISDB standards.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/intro.rst | 9 ++++++---
1 file changed, 6 insertions(+), 3 deletions(-)
diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index de432ffcba50..991643d3b461 100644
--- a/Documentation/media/uapi/dvb/intro.rst
+++ b/Documentation/media/uapi/dvb/intro.rst
@@ -18,10 +18,13 @@ part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
you should know what a program/transport stream (PS/TS) is and what is
meant by a packetized elementary stream (PES) or an I-frame.
-Various DVB standards documents are available from http://www.dvb.org
-and/or http://www.etsi.org.
+Various Digital TV standards documents are available for download at:
-It is also necessary to know how to access unix/linux devices and how to
+- European standards (DVB): http://www.dvb.org and/or http://www.etsi.org.
+- American standards (ATSC): https://www.atsc.org/standards/
+- Japanese standards (ISDB): http://www.dibeg.org/
+
+It is also necessary to know how to access Linux devices and how to
use ioctl calls. This also includes the knowledge of C or C++.
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 05/27] media: dvb/intro: update the history part of the document
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (3 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 04/27] media: dvb/intro: update references for TV standards Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 06/27] media: dvb/intro: adjust the notices about optional hardware Mauro Carvalho Chehab
` (23 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Convergence doesn't exist anymore. The community itself maintains
the spec. Update accordingly.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/intro.rst | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index 991643d3b461..4e1594816ef4 100644
--- a/Documentation/media/uapi/dvb/intro.rst
+++ b/Documentation/media/uapi/dvb/intro.rst
@@ -39,15 +39,19 @@ grabber cards. As such it was not really well suited to be used for DVB
cards and their new features like recording MPEG streams and filtering
several section and PES data streams at the same time.
-In early 2000, we were approached by Nokia with a proposal for a new
+In early 2000, Convergence was approached by Nokia with a proposal for a new
standard Linux DVB API. As a commitment to the development of terminals
based on open standards, Nokia and Convergence made it available to all
Linux developers and published it on https://linuxtv.org in September
-2000. Convergence is the maintainer of the Linux DVB API. Together with
-the LinuxTV community (i.e. you, the reader of this document), the Linux
-DVB API will be constantly reviewed and improved. With the Linux driver
-for the Siemens/Hauppauge DVB PCI card Convergence provides a first
-implementation of the Linux DVB API.
+2000. With the Linux driver for the Siemens/Hauppauge DVB PCI card,
+Convergence provided a first implementation of the Linux DVB API.
+Convergence was the maintainer of the Linux DVB API in the early
+days.
+
+Now, the API is maintained by the LinuxTV community (i.e. you, the reader
+of this document). The Linux Digital TV API is constantly reviewed and
+improved together with the improvements at the subsystem's core at the
+Kernel.
.. _overview:
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 06/27] media: dvb/intro: adjust the notices about optional hardware
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (4 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 05/27] media: dvb/intro: update the history part of the document Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 07/27] media: dvb/frontend.h: move out a private internal structure Mauro Carvalho Chehab
` (22 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Both CA and decoders are optional. Also, the presence or
absence has nothing to do on being a PCI card or not.
Nowadays, most hardware leaves the decoders to either the
GPU or to some ISP inside the SoC, instead of implementing
it inside the Digital TV part of the device.
So, change the wording to reflect the hardware changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/intro.rst | 29 +++++++++++++++++------------
1 file changed, 17 insertions(+), 12 deletions(-)
diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index 4e1594816ef4..aeafc9ab96c1 100644
--- a/Documentation/media/uapi/dvb/intro.rst
+++ b/Documentation/media/uapi/dvb/intro.rst
@@ -71,8 +71,7 @@ Overview
A Digital TV card or set-top-box (STB) usually consists of the
following main hardware components:
-- Frontend consisting of tuner and digital TV demodulator
-
+Frontend consisting of tuner and digital TV demodulator
Here the raw signal reaches the digital TV hardware from a satellite dish or
antenna or directly from cable. The frontend down-converts and
demodulates this signal into an MPEG transport stream (TS). In case
@@ -80,34 +79,40 @@ following main hardware components:
equipment control (SEC), which allows control of LNB polarization,
multi feed switches or dish rotors.
-- Conditional Access (CA) hardware like CI adapters and smartcard slots
-
+Conditional Access (CA) hardware like CI adapters and smartcard slots
The complete TS is passed through the CA hardware. Programs to which
the user has access (controlled by the smart card) are decoded in
real time and re-inserted into the TS.
-- Demultiplexer which filters the incoming DVB stream
+ .. note::
+ Not every digital TV hardware provides conditional access hardware.
+
+Demultiplexer which filters the incoming DVB stream
The demultiplexer splits the TS into its components like audio and
video streams. Besides usually several of such audio and video
streams it also contains data streams with information about the
programs offered in this or other streams of the same provider.
-- MPEG2 audio and video decoder
-
+MPEG2 audio and video decoder
The main targets of the demultiplexer are the MPEG2 audio and video
decoders. After decoding they pass on the uncompressed audio and
video to the computer screen or (through a PAL/NTSC encoder) to a TV
set.
+ .. note::
+
+ Modern hardware usually doesn't have a separate decoder hardware, as
+ such functionality can be provided by the main CPU, by the graphics
+ adapter of the system or by a signal processing hardware embedded on
+ a Systems on a Chip (SoC) integrated circuit.
+
+ It may also not be needed for certain usages (e.g. for data-only
+ uses like “internet over satellite”).
+
:ref:`stb_components` shows a crude schematic of the control and data
flow between those components.
-On a DVB PCI card not all of these have to be present since some
-functionality can be provided by the main CPU of the PC (e.g. MPEG
-picture and sound decoding) or is not needed (e.g. for data-only uses
-like “internet over satellite”). Also not every card or STB provides
-conditional access hardware.
.. _dvb_devices:
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 07/27] media: dvb/frontend.h: move out a private internal structure
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (5 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 06/27] media: dvb/intro: adjust the notices about optional hardware Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 08/27] media: dvb/frontend.h: document the uAPI file Mauro Carvalho Chehab
` (21 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Max Kellermann, Shuah Khan, Colin Ian King,
Sakari Ailus, Masahiro Yamada
struct dtv_cmds_h is just an ancillary struct used by the
dvb_frontend.c to internally store frontend commands.
It doesn't belong to the userspace header, nor it is used anywhere,
except inside the DVB core. So, remove it from the header.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/media/dvb-core/dvb_frontend.c | 11 +++++++++++
include/uapi/linux/dvb/frontend.h | 11 -----------
2 files changed, 11 insertions(+), 11 deletions(-)
diff --git a/drivers/media/dvb-core/dvb_frontend.c b/drivers/media/dvb-core/dvb_frontend.c
index 114994ca0929..2fcba1616168 100644
--- a/drivers/media/dvb-core/dvb_frontend.c
+++ b/drivers/media/dvb-core/dvb_frontend.c
@@ -1000,6 +1000,17 @@ static int dvb_frontend_clear_cache(struct dvb_frontend *fe)
.buffer = b \
}
+struct dtv_cmds_h {
+ char *name; /* A display name for debugging purposes */
+
+ __u32 cmd; /* A unique ID */
+
+ /* Flags */
+ __u32 set:1; /* Either a set or get property */
+ __u32 buffer:1; /* Does this property use the buffer? */
+ __u32 reserved:30; /* Align */
+};
+
static struct dtv_cmds_h dtv_cmds[DTV_MAX_COMMAND + 1] = {
_DTV_CMD(DTV_TUNE, 1, 0),
_DTV_CMD(DTV_CLEAR, 1, 0),
diff --git a/include/uapi/linux/dvb/frontend.h b/include/uapi/linux/dvb/frontend.h
index afc3972b0879..3a80f3d1da1c 100644
--- a/include/uapi/linux/dvb/frontend.h
+++ b/include/uapi/linux/dvb/frontend.h
@@ -384,17 +384,6 @@ enum atscmh_rs_code_mode {
#define NO_STREAM_ID_FILTER (~0U)
#define LNA_AUTO (~0U)
-struct dtv_cmds_h {
- char *name; /* A display name for debugging purposes */
-
- __u32 cmd; /* A unique ID */
-
- /* Flags */
- __u32 set:1; /* Either a set or get property */
- __u32 buffer:1; /* Does this property use the buffer? */
- __u32 reserved:30; /* Align */
-};
-
/**
* Scale types for the quality parameters.
* @FE_SCALE_NOT_AVAILABLE: That QoS measure is not available. That
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 08/27] media: dvb/frontend.h: document the uAPI file
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (6 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 07/27] media: dvb/frontend.h: move out a private internal structure Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 09/27] media: dvb frontend docs: use kernel-doc documentation Mauro Carvalho Chehab
` (20 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Most of the stuff at the Digital TV frontend header file
are documented only at the Documentation. However, a few
kernel-doc markups are there, several of them with parsing
issues.
Add the missing documentation, copying definitions from the
Documentation when it applies, fixing some bugs.
Please notice that DVBv3 stuff that were deprecated weren't
commented by purpose. Instead, they were clearly tagged as
such.
This patch prepares to move part of the documentation from
Documentation/ to kernel-doc comments.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
include/uapi/linux/dvb/frontend.h | 580 ++++++++++++++++++++++++++++++++------
1 file changed, 498 insertions(+), 82 deletions(-)
diff --git a/include/uapi/linux/dvb/frontend.h b/include/uapi/linux/dvb/frontend.h
index 3a80f3d1da1c..a383c87256f3 100644
--- a/include/uapi/linux/dvb/frontend.h
+++ b/include/uapi/linux/dvb/frontend.h
@@ -28,13 +28,46 @@
#include <linux/types.h>
-enum fe_type {
- FE_QPSK,
- FE_QAM,
- FE_OFDM,
- FE_ATSC
-};
-
+/**
+ * enum fe_caps - Frontend capabilities
+ *
+ * @FE_IS_STUPID: There's something wrong at the
+ * frontend, and it can't report its
+ * capabilities.
+ * @FE_CAN_INVERSION_AUTO: Can auto-detect frequency spectral
+ * band inversion
+ * @FE_CAN_FEC_1_2: Supports FEC 1/2
+ * @FE_CAN_FEC_2_3: Supports FEC 2/3
+ * @FE_CAN_FEC_3_4: Supports FEC 3/4
+ * @FE_CAN_FEC_4_5: Supports FEC 4/5
+ * @FE_CAN_FEC_5_6: Supports FEC 5/6
+ * @FE_CAN_FEC_6_7: Supports FEC 6/7
+ * @FE_CAN_FEC_7_8: Supports FEC 7/8
+ * @FE_CAN_FEC_8_9: Supports FEC 8/9
+ * @FE_CAN_FEC_AUTO: Can auto-detect FEC
+ * @FE_CAN_QPSK: Supports QPSK modulation
+ * @FE_CAN_QAM_16: Supports 16-QAM modulation
+ * @FE_CAN_QAM_32: Supports 32-QAM modulation
+ * @FE_CAN_QAM_64: Supports 64-QAM modulation
+ * @FE_CAN_QAM_128: Supports 128-QAM modulation
+ * @FE_CAN_QAM_256: Supports 256-QAM modulation
+ * @FE_CAN_QAM_AUTO: Can auto-detect QAM modulation
+ * @FE_CAN_TRANSMISSION_MODE_AUTO: Can auto-detect transmission mode
+ * @FE_CAN_BANDWIDTH_AUTO: Can auto-detect bandwidth
+ * @FE_CAN_GUARD_INTERVAL_AUTO: Can auto-detect guard interval
+ * @FE_CAN_HIERARCHY_AUTO: Can auto-detect hierarchy
+ * @FE_CAN_8VSB: Supports 8-VSB modulation
+ * @FE_CAN_16VSB: Supporta 16-VSB modulation
+ * @FE_HAS_EXTENDED_CAPS: Unused
+ * @FE_CAN_MULTISTREAM: Supports multistream filtering
+ * @FE_CAN_TURBO_FEC: Supports "turbo FEC" modulation
+ * @FE_CAN_2G_MODULATION: Supports "2nd generation" modulation,
+ * e. g. DVB-S2, DVB-T2, DVB-C2
+ * @FE_NEEDS_BENDING: Unused
+ * @FE_CAN_RECOVER: Can recover from a cable unplug
+ * automatically
+ * @FE_CAN_MUTE_TS: Can stop spurious TS data output
+ */
enum fe_caps {
FE_IS_STUPID = 0,
FE_CAN_INVERSION_AUTO = 0x1,
@@ -60,15 +93,55 @@ enum fe_caps {
FE_CAN_HIERARCHY_AUTO = 0x100000,
FE_CAN_8VSB = 0x200000,
FE_CAN_16VSB = 0x400000,
- FE_HAS_EXTENDED_CAPS = 0x800000, /* We need more bitspace for newer APIs, indicate this. */
- FE_CAN_MULTISTREAM = 0x4000000, /* frontend supports multistream filtering */
- FE_CAN_TURBO_FEC = 0x8000000, /* frontend supports "turbo fec modulation" */
- FE_CAN_2G_MODULATION = 0x10000000, /* frontend supports "2nd generation modulation" (DVB-S2) */
- FE_NEEDS_BENDING = 0x20000000, /* not supported anymore, don't use (frontend requires frequency bending) */
- FE_CAN_RECOVER = 0x40000000, /* frontend can recover from a cable unplug automatically */
- FE_CAN_MUTE_TS = 0x80000000 /* frontend can stop spurious TS data output */
+ FE_HAS_EXTENDED_CAPS = 0x800000,
+ FE_CAN_MULTISTREAM = 0x4000000,
+ FE_CAN_TURBO_FEC = 0x8000000,
+ FE_CAN_2G_MODULATION = 0x10000000,
+ FE_NEEDS_BENDING = 0x20000000,
+ FE_CAN_RECOVER = 0x40000000,
+ FE_CAN_MUTE_TS = 0x80000000
};
+/*
+ * DEPRECATED: Should be kept just due to backward compatibility.
+ */
+enum fe_type {
+ FE_QPSK,
+ FE_QAM,
+ FE_OFDM,
+ FE_ATSC
+};
+
+/**
+ * struct dvb_frontend_info - Frontend properties and capabilities
+ *
+ * @name: Name of the frontend
+ * @type: **DEPRECATED**.
+ * Should not be used on modern programs,
+ * as a frontend may have more than one type.
+ * In order to get the support types of a given
+ * frontend, use :c:type:`DTV_ENUM_DELSYS`
+ * instead.
+ * @frequency_min: Minimal frequency supported by the frontend.
+ * @frequency_max: Minimal frequency supported by the frontend.
+ * @frequency_stepsize: All frequencies are multiple of this value.
+ * @frequency_tolerance: Frequency tolerance.
+ * @symbol_rate_min: Minimal symbol rate, in bauds
+ * (for Cable/Satellite systems).
+ * @symbol_rate_max: Maximal symbol rate, in bauds
+ * (for Cable/Satellite systems).
+ * @symbol_rate_tolerance: Maximal symbol rate tolerance, in ppm
+ * (for Cable/Satellite systems).
+ * @notifier_delay: **DEPRECATED**. Not used by any driver.
+ * @caps: Capabilities supported by the frontend,
+ * as specified in &enum fe_caps.
+ *
+ * .. note:
+ *
+ * #. The frequencies are specified in Hz for Terrestrial and Cable
+ * systems.
+ * #. The frequencies are specified in kHz for Satellite systems.
+ */
struct dvb_frontend_info {
char name[128];
enum fe_type type; /* DEPRECATED. Use DTV_ENUM_DELSYS instead */
@@ -78,53 +151,102 @@ struct dvb_frontend_info {
__u32 frequency_tolerance;
__u32 symbol_rate_min;
__u32 symbol_rate_max;
- __u32 symbol_rate_tolerance; /* ppm */
+ __u32 symbol_rate_tolerance;
__u32 notifier_delay; /* DEPRECATED */
enum fe_caps caps;
};
-
/**
- * Check out the DiSEqC bus spec available on http://www.eutelsat.org/ for
- * the meaning of this struct...
+ * struct dvb_diseqc_master_cmd - DiSEqC master command
+ *
+ * @msg:
+ * DiSEqC message to be sent. It contains a 3 bytes header with:
+ * framing + address + command, and an optional argument
+ * of up to 3 bytes of data.
+ * @msg_len:
+ * Length of the DiSEqC message. Valid values are 3 to 6.
+ *
+ * Check out the DiSEqC bus spec available on http://www.eutelsat.org/ for
+ * the possible messages that can be used.
*/
struct dvb_diseqc_master_cmd {
- __u8 msg [6]; /* { framing, address, command, data [3] } */
- __u8 msg_len; /* valid values are 3...6 */
+ __u8 msg [6];
+ __u8 msg_len;
};
+/**
+ * struct dvb_diseqc_slave_reply - DiSEqC received data
+ *
+ * @msg:
+ * DiSEqC message buffer to store a message received via DiSEqC.
+ * It contains one byte header with: framing and
+ * an optional argument of up to 3 bytes of data.
+ * @msg_len:
+ * Length of the DiSEqC message. Valid values are 0 to 4,
+ * where 0 means no message.
+ * @timeout:
+ * Return from ioctl after timeout ms with errorcode when
+ * no message was received.
+ *
+ * Check out the DiSEqC bus spec available on http://www.eutelsat.org/ for
+ * the possible messages that can be used.
+ */
struct dvb_diseqc_slave_reply {
- __u8 msg [4]; /* { framing, data [3] } */
- __u8 msg_len; /* valid values are 0...4, 0 means no msg */
- int timeout; /* return from ioctl after timeout ms with */
-}; /* errorcode when no message was received */
+ __u8 msg [4];
+ __u8 msg_len;
+ int timeout;
+};
+/**
+ * enum fe_sec_voltage - DC Voltage used to feed the LNBf
+ *
+ * @SEC_VOLTAGE_13: Output 13V to the LNBf
+ * @SEC_VOLTAGE_18: Output 18V to the LNBf
+ * @SEC_VOLTAGE_OFF: Don't feed the LNBf with a DC voltage
+ */
enum fe_sec_voltage {
SEC_VOLTAGE_13,
SEC_VOLTAGE_18,
SEC_VOLTAGE_OFF
};
+/**
+ * enum fe_sec_tone_mode - Type of tone to be send to the LNBf.
+ * @SEC_TONE_ON: Sends a 22kHz tone burst to the antenna.
+ * @SEC_TONE_OFF: Don't send a 22kHz tone to the antenna (except
+ * if the ``FE_DISEQC_*`` ioctls are called).
+ */
enum fe_sec_tone_mode {
SEC_TONE_ON,
SEC_TONE_OFF
};
+/**
+ * enum fe_sec_mini_cmd - Type of mini burst to be sent
+ *
+ * @SEC_MINI_A: Sends a mini-DiSEqC 22kHz '0' Tone Burst to select
+ * satellite-A
+ * @SEC_MINI_B: Sends a mini-DiSEqC 22kHz '1' Data Burst to select
+ * satellite-B
+ */
enum fe_sec_mini_cmd {
SEC_MINI_A,
SEC_MINI_B
};
/**
- * enum fe_status - enumerates the possible frontend status
- * @FE_HAS_SIGNAL: found something above the noise level
- * @FE_HAS_CARRIER: found a DVB signal
- * @FE_HAS_VITERBI: FEC is stable
- * @FE_HAS_SYNC: found sync bytes
- * @FE_HAS_LOCK: everything's working
- * @FE_TIMEDOUT: no lock within the last ~2 seconds
- * @FE_REINIT: frontend was reinitialized, application is recommended
- * to reset DiSEqC, tone and parameters
+ * enum fe_status - Enumerates the possible frontend status.
+ * @FE_NONE: The frontend doesn't have any kind of lock.
+ * That's the initial frontend status
+ * @FE_HAS_SIGNAL: Has found something above the noise level.
+ * @FE_HAS_CARRIER: Has found a DVB signal.
+ * @FE_HAS_VITERBI: FEC inner coding (Viterbi, LDPC or other inner code).
+ * is stable.
+ * @FE_HAS_SYNC: Synchronization bytes was found.
+ * @FE_HAS_LOCK: DVB were locked and everything is working.
+ * @FE_TIMEDOUT: Fo lock within the last about 2 seconds.
+ * @FE_REINIT: Frontend was reinitialized, application is recommended
+ * to reset DiSEqC, tone and parameters.
*/
enum fe_status {
FE_NONE = 0x00,
@@ -137,12 +259,45 @@ enum fe_status {
FE_REINIT = 0x40,
};
+/**
+ * enum fe_spectral_inversion - Type of inversion band
+ *
+ * @INVERSION_OFF: Don't do spectral band inversion.
+ * @INVERSION_ON: Do spectral band inversion.
+ * @INVERSION_AUTO: Autodetect spectral band inversion.
+ *
+ * This parameter indicates if spectral inversion should be presumed or
+ * not. In the automatic setting (``INVERSION_AUTO``) the hardware will try
+ * to figure out the correct setting by itself. If the hardware doesn't
+ * support, the DVB core will try to lock at the carrier first with
+ * inversion off. If it fails, it will try to enable inversion.
+ */
enum fe_spectral_inversion {
INVERSION_OFF,
INVERSION_ON,
INVERSION_AUTO
};
+/**
+ * enum fe_code_rate - Type of Forward Error Correction (FEC)
+ *
+ *
+ * @FEC_NONE: No Forward Error Correction Code
+ * @FEC_1_2: Forward Error Correction Code 1/2
+ * @FEC_2_3: Forward Error Correction Code 2/3
+ * @FEC_3_4: Forward Error Correction Code 3/4
+ * @FEC_4_5: Forward Error Correction Code 4/5
+ * @FEC_5_6: Forward Error Correction Code 5/6
+ * @FEC_6_7: Forward Error Correction Code 6/7
+ * @FEC_7_8: Forward Error Correction Code 7/8
+ * @FEC_8_9: Forward Error Correction Code 8/9
+ * @FEC_AUTO: Autodetect Error Correction Code
+ * @FEC_3_5: Forward Error Correction Code 3/5
+ * @FEC_9_10: Forward Error Correction Code 9/10
+ * @FEC_2_5: Forward Error Correction Code 2/5
+ *
+ * Please note that not all FEC types are supported by a given standard.
+ */
enum fe_code_rate {
FEC_NONE = 0,
FEC_1_2,
@@ -159,6 +314,26 @@ enum fe_code_rate {
FEC_2_5,
};
+/**
+ * enum fe_modulation - Type of modulation/constellation
+ * @QPSK: QPSK modulation
+ * @QAM_16: 16-QAM modulation
+ * @QAM_32: 32-QAM modulation
+ * @QAM_64: 64-QAM modulation
+ * @QAM_128: 128-QAM modulation
+ * @QAM_256: 256-QAM modulation
+ * @QAM_AUTO: Autodetect QAM modulation
+ * @VSB_8: 8-VSB modulation
+ * @VSB_16: 16-VSB modulation
+ * @PSK_8: 8-PSK modulation
+ * @APSK_16: 16-APSK modulation
+ * @APSK_32: 32-APSK modulation
+ * @DQPSK: DQPSK modulation
+ * @QAM_4_NR: 4-QAM-NR modulation
+ *
+ * Please note that not all modulations are supported by a given standard.
+ *
+ */
enum fe_modulation {
QPSK,
QAM_16,
@@ -176,6 +351,32 @@ enum fe_modulation {
QAM_4_NR,
};
+/**
+ * enum fe_transmit_mode - Transmission mode
+ *
+ * @TRANSMISSION_MODE_AUTO:
+ * Autodetect transmission mode. The hardware will try to find the
+ * correct FFT-size (if capable) to fill in the missing parameters.
+ * @TRANSMISSION_MODE_1K:
+ * Transmission mode 1K
+ * @TRANSMISSION_MODE_2K:
+ * Transmission mode 2K
+ * @TRANSMISSION_MODE_8K:
+ * Transmission mode 8K
+ * @TRANSMISSION_MODE_4K:
+ * Transmission mode 4K
+ * @TRANSMISSION_MODE_16K:
+ * Transmission mode 16K
+ * @TRANSMISSION_MODE_32K:
+ * Transmission mode 32K
+ * @TRANSMISSION_MODE_C1:
+ * Single Carrier (C=1) transmission mode (DTMB only)
+ * @TRANSMISSION_MODE_C3780:
+ * Multi Carrier (C=3780) transmission mode (DTMB only)
+ *
+ * Please note that not all transmission modes are supported by a given
+ * standard.
+ */
enum fe_transmit_mode {
TRANSMISSION_MODE_2K,
TRANSMISSION_MODE_8K,
@@ -188,6 +389,23 @@ enum fe_transmit_mode {
TRANSMISSION_MODE_C3780,
};
+/**
+ * enum fe_guard_interval - Guard interval
+ *
+ * @GUARD_INTERVAL_AUTO: Autodetect the guard interval
+ * @GUARD_INTERVAL_1_128: Guard interval 1/128
+ * @GUARD_INTERVAL_1_32: Guard interval 1/32
+ * @GUARD_INTERVAL_1_16: Guard interval 1/16
+ * @GUARD_INTERVAL_1_8: Guard interval 1/8
+ * @GUARD_INTERVAL_1_4: Guard interval 1/4
+ * @GUARD_INTERVAL_19_128: Guard interval 19/128
+ * @GUARD_INTERVAL_19_256: Guard interval 19/256
+ * @GUARD_INTERVAL_PN420: PN length 420 (1/4)
+ * @GUARD_INTERVAL_PN595: PN length 595 (1/6)
+ * @GUARD_INTERVAL_PN945: PN length 945 (1/9)
+ *
+ * Please note that not all guard intervals are supported by a given standard.
+ */
enum fe_guard_interval {
GUARD_INTERVAL_1_32,
GUARD_INTERVAL_1_16,
@@ -202,6 +420,16 @@ enum fe_guard_interval {
GUARD_INTERVAL_PN945,
};
+/**
+ * enum fe_hierarchy - Hierarchy
+ * @HIERARCHY_NONE: No hierarchy
+ * @HIERARCHY_AUTO: Autodetect hierarchy (if supported)
+ * @HIERARCHY_1: Hierarchy 1
+ * @HIERARCHY_2: Hierarchy 2
+ * @HIERARCHY_4: Hierarchy 4
+ *
+ * Please note that not all hierarchy types are supported by a given standard.
+ */
enum fe_hierarchy {
HIERARCHY_NONE,
HIERARCHY_1,
@@ -210,6 +438,15 @@ enum fe_hierarchy {
HIERARCHY_AUTO
};
+/**
+ * enum fe_interleaving - Interleaving
+ * @INTERLEAVING_NONE: No interleaving.
+ * @INTERLEAVING_AUTO: Auto-detect interleaving.
+ * @INTERLEAVING_240: Interleaving of 240 symbols.
+ * @INTERLEAVING_720: Interleaving of 720 symbols.
+ *
+ * Please note that, currently, only DTMB uses it.
+ */
enum fe_interleaving {
INTERLEAVING_NONE,
INTERLEAVING_AUTO,
@@ -217,7 +454,8 @@ enum fe_interleaving {
INTERLEAVING_720,
};
-/* S2API Commands */
+/* DVBv5 property Commands */
+
#define DTV_UNDEFINED 0
#define DTV_TUNE 1
#define DTV_CLEAR 2
@@ -310,19 +548,79 @@ enum fe_interleaving {
#define DTV_MAX_COMMAND DTV_STAT_TOTAL_BLOCK_COUNT
+/**
+ * enum fe_pilot - Type of pilot tone
+ *
+ * @PILOT_ON: Pilot tones enabled
+ * @PILOT_OFF: Pilot tones disabled
+ * @PILOT_AUTO: Autodetect pilot tones
+ */
enum fe_pilot {
PILOT_ON,
PILOT_OFF,
PILOT_AUTO,
};
+/**
+ * enum fe_rolloff - Rolloff factor (also known as alpha)
+ * @ROLLOFF_35: Roloff factor: 35%
+ * @ROLLOFF_20: Roloff factor: 20%
+ * @ROLLOFF_25: Roloff factor: 25%
+ * @ROLLOFF_AUTO: Auto-detect the roloff factor.
+ *
+ * .. note:
+ *
+ * Roloff factor of 35% is implied on DVB-S. On DVB-S2, it is default.
+ */
enum fe_rolloff {
- ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */
+ ROLLOFF_35,
ROLLOFF_20,
ROLLOFF_25,
ROLLOFF_AUTO,
};
+/**
+ * enum fe_delivery_system - Type of the delivery system
+ *
+ * @SYS_UNDEFINED:
+ * Undefined standard. Generally, indicates an error
+ * @SYS_DVBC_ANNEX_A:
+ * Cable TV: DVB-C following ITU-T J.83 Annex A spec
+ * @SYS_DVBC_ANNEX_B:
+ * Cable TV: DVB-C following ITU-T J.83 Annex B spec (ClearQAM)
+ * @SYS_DVBC_ANNEX_C:
+ * Cable TV: DVB-C following ITU-T J.83 Annex C spec
+ * @SYS_ISDBC:
+ * Cable TV: ISDB-C (no drivers yet)
+ * @SYS_DVBT:
+ * Terrestrial TV: DVB-T
+ * @SYS_DVBT2:
+ * Terrestrial TV: DVB-T2
+ * @SYS_ISDBT:
+ * Terrestrial TV: ISDB-T
+ * @SYS_ATSC:
+ * Terrestrial TV: ATSC
+ * @SYS_ATSCMH:
+ * Terrestrial TV (mobile): ATSC-M/H
+ * @SYS_DTMB:
+ * Terrestrial TV: DTMB
+ * @SYS_DVBS:
+ * Satellite TV: DVB-S
+ * @SYS_DVBS2:
+ * Satellite TV: DVB-S2
+ * @SYS_TURBO:
+ * Satellite TV: DVB-S Turbo
+ * @SYS_ISDBS:
+ * Satellite TV: ISDB-S
+ * @SYS_DAB:
+ * Digital audio: DAB (not fully supported)
+ * @SYS_DSS:
+ * Satellite TV: DSS (not fully supported)
+ * @SYS_CMMB:
+ * Terrestrial TV (mobile): CMMB (not fully supported)
+ * @SYS_DVBH:
+ * Terrestrial TV (mobile): DVB-H (standard deprecated)
+ */
enum fe_delivery_system {
SYS_UNDEFINED,
SYS_DVBC_ANNEX_A,
@@ -345,35 +643,85 @@ enum fe_delivery_system {
SYS_DVBC_ANNEX_C,
};
-/* backward compatibility */
+/* backward compatibility definitions for delivery systems */
#define SYS_DVBC_ANNEX_AC SYS_DVBC_ANNEX_A
-#define SYS_DMBTH SYS_DTMB /* DMB-TH is legacy name, use DTMB instead */
+#define SYS_DMBTH SYS_DTMB /* DMB-TH is legacy name, use DTMB */
-/* ATSC-MH */
+/* ATSC-MH specific parameters */
+/**
+ * enum atscmh_sccc_block_mode - Type of Series Concatenated Convolutional
+ * Code Block Mode.
+ *
+ * @ATSCMH_SCCC_BLK_SEP:
+ * Separate SCCC: the SCCC outer code mode shall be set independently
+ * for each Group Region (A, B, C, D)
+ * @ATSCMH_SCCC_BLK_COMB:
+ * Combined SCCC: all four Regions shall have the same SCCC outer
+ * code mode.
+ * @ATSCMH_SCCC_BLK_RES:
+ * Reserved. Shouldn't be used.
+ */
enum atscmh_sccc_block_mode {
ATSCMH_SCCC_BLK_SEP = 0,
ATSCMH_SCCC_BLK_COMB = 1,
ATSCMH_SCCC_BLK_RES = 2,
};
+/**
+ * enum atscmh_sccc_code_mode - Type of Series Concatenated Convolutional
+ * Code Rate.
+ *
+ * @ATSCMH_SCCC_CODE_HLF:
+ * The outer code rate of a SCCC Block is 1/2 rate.
+ * @ATSCMH_SCCC_CODE_QTR:
+ * The outer code rate of a SCCC Block is 1/4 rate.
+ * @ATSCMH_SCCC_CODE_RES:
+ * Reserved. Should not be used.
+ */
enum atscmh_sccc_code_mode {
ATSCMH_SCCC_CODE_HLF = 0,
ATSCMH_SCCC_CODE_QTR = 1,
ATSCMH_SCCC_CODE_RES = 2,
};
+/**
+ * enum atscmh_rs_frame_ensemble - Reed Solomon(RS) frame ensemble.
+ *
+ * @ATSCMH_RSFRAME_ENS_PRI: Primary Ensemble.
+ * @ATSCMH_RSFRAME_ENS_SEC: Secondary Ensemble.
+ */
enum atscmh_rs_frame_ensemble {
ATSCMH_RSFRAME_ENS_PRI = 0,
ATSCMH_RSFRAME_ENS_SEC = 1,
};
+/**
+ * enum atscmh_rs_frame_mode - Reed Solomon (RS) frame mode.
+ *
+ * @ATSCMH_RSFRAME_PRI_ONLY:
+ * Single Frame: There is only a primary RS Frame for all Group
+ * Regions.
+ * @ATSCMH_RSFRAME_PRI_SEC:
+ * Dual Frame: There are two separate RS Frames: Primary RS Frame for
+ * Group Region A and B and Secondary RS Frame for Group Region C and
+ * D.
+ * @ATSCMH_RSFRAME_RES:
+ * Reserved. Shouldn't be used.
+ */
enum atscmh_rs_frame_mode {
ATSCMH_RSFRAME_PRI_ONLY = 0,
ATSCMH_RSFRAME_PRI_SEC = 1,
ATSCMH_RSFRAME_RES = 2,
};
+/**
+ * enum atscmh_rs_code_mode
+ * @ATSCMH_RSCODE_211_187: Reed Solomon code (211,187).
+ * @ATSCMH_RSCODE_223_187: Reed Solomon code (223,187).
+ * @ATSCMH_RSCODE_235_187: Reed Solomon code (235,187).
+ * @ATSCMH_RSCODE_RES: Reserved. Shouldn't be used.
+ */
enum atscmh_rs_code_mode {
ATSCMH_RSCODE_211_187 = 0,
ATSCMH_RSCODE_223_187 = 1,
@@ -385,16 +733,17 @@ enum atscmh_rs_code_mode {
#define LNA_AUTO (~0U)
/**
- * Scale types for the quality parameters.
+ * enum fecap_scale_params - scale types for the quality parameters.
+ *
* @FE_SCALE_NOT_AVAILABLE: That QoS measure is not available. That
* could indicate a temporary or a permanent
* condition.
* @FE_SCALE_DECIBEL: The scale is measured in 0.001 dB steps, typically
- * used on signal measures.
+ * used on signal measures.
* @FE_SCALE_RELATIVE: The scale is a relative percentual measure,
- * ranging from 0 (0%) to 0xffff (100%).
+ * ranging from 0 (0%) to 0xffff (100%).
* @FE_SCALE_COUNTER: The scale counts the occurrence of an event, like
- * bit error, block error, lapsed time.
+ * bit error, block error, lapsed time.
*/
enum fecap_scale_params {
FE_SCALE_NOT_AVAILABLE = 0,
@@ -406,24 +755,38 @@ enum fecap_scale_params {
/**
* struct dtv_stats - Used for reading a DTV status property
*
- * @value: value of the measure. Should range from 0 to 0xffff;
* @scale: Filled with enum fecap_scale_params - the scale
* in usage for that parameter
*
+ * The ``{unnamed_union}`` may have either one of the values below:
+ *
+ * %svalue
+ * integer value of the measure, for %FE_SCALE_DECIBEL,
+ * used for dB measures. The unit is 0.001 dB.
+ *
+ * %uvalue
+ * unsigned integer value of the measure, used when @scale is
+ * either %FE_SCALE_RELATIVE or %FE_SCALE_COUNTER.
+ *
* For most delivery systems, this will return a single value for each
* parameter.
+ *
* It should be noticed, however, that new OFDM delivery systems like
* ISDB can use different modulation types for each group of carriers.
* On such standards, up to 8 groups of statistics can be provided, one
* for each carrier group (called "layer" on ISDB).
+ *
* In order to be consistent with other delivery systems, the first
* value refers to the entire set of carriers ("global").
- * dtv_status:scale should use the value FE_SCALE_NOT_AVAILABLE when
+ *
+ * @scale should use the value %FE_SCALE_NOT_AVAILABLE when
* the value for the entire group of carriers or from one specific layer
* is not provided by the hardware.
- * st.len should be filled with the latest filled status + 1.
*
- * In other words, for ISDB, those values should be filled like:
+ * @len should be filled with the latest filled status + 1.
+ *
+ * In other words, for ISDB, those values should be filled like::
+ *
* u.st.stat.svalue[0] = global statistics;
* u.st.stat.scale[0] = FE_SCALE_DECIBEL;
* u.st.stat.value[1] = layer A statistics;
@@ -445,11 +808,39 @@ struct dtv_stats {
#define MAX_DTV_STATS 4
+/**
+ * struct dtv_fe_stats - store Digital TV frontend statistics
+ *
+ * @len: length of the statistics - if zero, stats is disabled.
+ * @stat: array with digital TV statistics.
+ *
+ * On most standards, @len can either be 0 or 1. However, for ISDB, each
+ * layer is modulated in separate. So, each layer may have its own set
+ * of statistics. If so, stat[0] carries on a global value for the property.
+ * Indexes 1 to 3 means layer A to B.
+ */
struct dtv_fe_stats {
__u8 len;
struct dtv_stats stat[MAX_DTV_STATS];
} __attribute__ ((packed));
+/**
+ * struct dtv_property - store one of frontend command and its value
+ *
+ * @cmd: Digital TV command.
+ * @reserved: Not used.
+ * @u: Union with the values for the command.
+ * @result: Result of the command set (currently unused).
+ *
+ * The @u union may have either one of the values below:
+ *
+ * %data
+ * an unsigned 32-bits number.
+ * %st
+ * a &struct dtv_fe_stats array of statistics.
+ * %buffer
+ * a buffer of up to 32 characters (currently unused).
+ */
struct dtv_property {
__u32 cmd;
__u32 reserved[3];
@@ -469,17 +860,70 @@ struct dtv_property {
/* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
#define DTV_IOCTL_MAX_MSGS 64
+/**
+ * struct dtv_properties - a set of command/value pairs.
+ *
+ * @num: amount of commands stored at the struct.
+ * @props: a pointer to &struct dtv_property.
+ */
struct dtv_properties {
__u32 num;
struct dtv_property *props;
};
+/*
+ * When set, this flag will disable any zigzagging or other "normal" tuning
+ * behavior. Additionally, there will be no automatic monitoring of the lock
+ * status, and hence no frontend events will be generated. If a frontend device
+ * is closed, this flag will be automatically turned off when the device is
+ * reopened read-write.
+ */
+#define FE_TUNE_MODE_ONESHOT 0x01
+
+/* Digital TV Frontend API calls */
+
+#define FE_GET_INFO _IOR('o', 61, struct dvb_frontend_info)
+
+#define FE_DISEQC_RESET_OVERLOAD _IO('o', 62)
+#define FE_DISEQC_SEND_MASTER_CMD _IOW('o', 63, struct dvb_diseqc_master_cmd)
+#define FE_DISEQC_RECV_SLAVE_REPLY _IOR('o', 64, struct dvb_diseqc_slave_reply)
+#define FE_DISEQC_SEND_BURST _IO('o', 65) /* fe_sec_mini_cmd_t */
+
+#define FE_SET_TONE _IO('o', 66) /* fe_sec_tone_mode_t */
+#define FE_SET_VOLTAGE _IO('o', 67) /* fe_sec_voltage_t */
+#define FE_ENABLE_HIGH_LNB_VOLTAGE _IO('o', 68) /* int */
+
+#define FE_READ_STATUS _IOR('o', 69, fe_status_t)
+#define FE_READ_BER _IOR('o', 70, __u32)
+#define FE_READ_SIGNAL_STRENGTH _IOR('o', 71, __u16)
+#define FE_READ_SNR _IOR('o', 72, __u16)
+#define FE_READ_UNCORRECTED_BLOCKS _IOR('o', 73, __u32)
+
+#define FE_SET_FRONTEND_TUNE_MODE _IO('o', 81) /* unsigned int */
+#define FE_GET_EVENT _IOR('o', 78, struct dvb_frontend_event)
+
+#define FE_DISHNETWORK_SEND_LEGACY_CMD _IO('o', 80) /* unsigned int */
+
+#define FE_SET_PROPERTY _IOW('o', 82, struct dtv_properties)
+#define FE_GET_PROPERTY _IOR('o', 83, struct dtv_properties)
+
#if defined(__DVB_CORE__) || !defined (__KERNEL__)
/*
- * DEPRECATED: The DVBv3 ioctls, structs and enums should not be used on
- * newer programs, as it doesn't support the second generation of digital
- * TV standards, nor supports newer delivery systems.
+ * DEPRECATED: Everything below is deprecated in favor of DVBv5 API
+ *
+ * The DVBv3 only ioctls, structs and enums should not be used on
+ * newer programs, as it doesn't support the second generation of
+ * digital TV standards, nor supports newer delivery systems.
+ * They also don't support modern frontends with usually support multiple
+ * delivery systems.
+ *
+ * Drivers shouldn't use them.
+ *
+ * New applications should use DVBv5 delivery system instead
+ */
+
+/*
*/
enum fe_bandwidth {
@@ -492,7 +936,7 @@ enum fe_bandwidth {
BANDWIDTH_1_712_MHZ,
};
-/* This is needed for legacy userspace support */
+/* This is kept for legacy userspace support */
typedef enum fe_sec_voltage fe_sec_voltage_t;
typedef enum fe_caps fe_caps_t;
typedef enum fe_type fe_type_t;
@@ -510,6 +954,8 @@ typedef enum fe_pilot fe_pilot_t;
typedef enum fe_rolloff fe_rolloff_t;
typedef enum fe_delivery_system fe_delivery_system_t;
+/* DVBv3 structs */
+
struct dvb_qpsk_parameters {
__u32 symbol_rate; /* symbol rate in Symbols per second */
fe_code_rate_t fec_inner; /* forward error correction (see above) */
@@ -551,42 +997,12 @@ struct dvb_frontend_event {
fe_status_t status;
struct dvb_frontend_parameters parameters;
};
-#endif
-#define FE_SET_PROPERTY _IOW('o', 82, struct dtv_properties)
-#define FE_GET_PROPERTY _IOR('o', 83, struct dtv_properties)
-
-/**
- * When set, this flag will disable any zigzagging or other "normal" tuning
- * behaviour. Additionally, there will be no automatic monitoring of the lock
- * status, and hence no frontend events will be generated. If a frontend device
- * is closed, this flag will be automatically turned off when the device is
- * reopened read-write.
- */
-#define FE_TUNE_MODE_ONESHOT 0x01
-
-#define FE_GET_INFO _IOR('o', 61, struct dvb_frontend_info)
-
-#define FE_DISEQC_RESET_OVERLOAD _IO('o', 62)
-#define FE_DISEQC_SEND_MASTER_CMD _IOW('o', 63, struct dvb_diseqc_master_cmd)
-#define FE_DISEQC_RECV_SLAVE_REPLY _IOR('o', 64, struct dvb_diseqc_slave_reply)
-#define FE_DISEQC_SEND_BURST _IO('o', 65) /* fe_sec_mini_cmd_t */
-
-#define FE_SET_TONE _IO('o', 66) /* fe_sec_tone_mode_t */
-#define FE_SET_VOLTAGE _IO('o', 67) /* fe_sec_voltage_t */
-#define FE_ENABLE_HIGH_LNB_VOLTAGE _IO('o', 68) /* int */
-
-#define FE_READ_STATUS _IOR('o', 69, fe_status_t)
-#define FE_READ_BER _IOR('o', 70, __u32)
-#define FE_READ_SIGNAL_STRENGTH _IOR('o', 71, __u16)
-#define FE_READ_SNR _IOR('o', 72, __u16)
-#define FE_READ_UNCORRECTED_BLOCKS _IOR('o', 73, __u32)
+/* DVBv3 API calls */
#define FE_SET_FRONTEND _IOW('o', 76, struct dvb_frontend_parameters)
#define FE_GET_FRONTEND _IOR('o', 77, struct dvb_frontend_parameters)
-#define FE_SET_FRONTEND_TUNE_MODE _IO('o', 81) /* unsigned int */
-#define FE_GET_EVENT _IOR('o', 78, struct dvb_frontend_event)
-#define FE_DISHNETWORK_SEND_LEGACY_CMD _IO('o', 80) /* unsigned int */
+#endif
#endif /*_DVBFRONTEND_H_*/
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 09/27] media: dvb frontend docs: use kernel-doc documentation
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (7 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 08/27] media: dvb/frontend.h: document the uAPI file Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 10/27] media: fe_property_parameters.rst: better define properties usage Mauro Carvalho Chehab
` (19 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Colin Ian King
Now that frontend.h contains most documentation for the frontend,
remove the duplicated information from Documentation/ and use the
kernel-doc auto-generated one instead.
That should simplify maintainership of DVB frontend uAPI, as most
of the documentation will stick with the header file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/frontend.h.rst.exceptions | 185 ++-
Documentation/media/uapi/dvb/dtv-fe-stats.rst | 17 -
Documentation/media/uapi/dvb/dtv-properties.rst | 15 -
Documentation/media/uapi/dvb/dtv-property.rst | 31 -
Documentation/media/uapi/dvb/dtv-stats.rst | 18 -
Documentation/media/uapi/dvb/dvbproperty-006.rst | 12 -
Documentation/media/uapi/dvb/dvbproperty.rst | 28 +-
.../media/uapi/dvb/fe-diseqc-recv-slave-reply.rst | 40 +-
.../media/uapi/dvb/fe-diseqc-send-burst.rst | 31 +-
.../media/uapi/dvb/fe-diseqc-send-master-cmd.rst | 29 +-
Documentation/media/uapi/dvb/fe-get-info.rst | 370 +-----
Documentation/media/uapi/dvb/fe-get-property.rst | 2 +-
Documentation/media/uapi/dvb/fe-read-status.rst | 83 --
Documentation/media/uapi/dvb/fe-set-tone.rst | 30 -
.../media/uapi/dvb/fe_property_parameters.rst | 1277 ++------------------
| 4 +
include/uapi/linux/dvb/frontend.h | 8 +-
17 files changed, 317 insertions(+), 1863 deletions(-)
delete mode 100644 Documentation/media/uapi/dvb/dtv-fe-stats.rst
delete mode 100644 Documentation/media/uapi/dvb/dtv-properties.rst
delete mode 100644 Documentation/media/uapi/dvb/dtv-property.rst
delete mode 100644 Documentation/media/uapi/dvb/dtv-stats.rst
delete mode 100644 Documentation/media/uapi/dvb/dvbproperty-006.rst
create mode 100644 Documentation/media/uapi/dvb/frontend-header.rst
diff --git a/Documentation/media/frontend.h.rst.exceptions b/Documentation/media/frontend.h.rst.exceptions
index 7656770f1936..f7c4df620a52 100644
--- a/Documentation/media/frontend.h.rst.exceptions
+++ b/Documentation/media/frontend.h.rst.exceptions
@@ -25,19 +25,9 @@ ignore define DTV_MAX_COMMAND
ignore define MAX_DTV_STATS
ignore define DTV_IOCTL_MAX_MSGS
-# Stats enum is documented altogether
-replace enum fecap_scale_params :ref:`frontend-stat-properties`
-replace symbol FE_SCALE_COUNTER frontend-stat-properties
-replace symbol FE_SCALE_DECIBEL frontend-stat-properties
-replace symbol FE_SCALE_NOT_AVAILABLE frontend-stat-properties
-replace symbol FE_SCALE_RELATIVE frontend-stat-properties
-
# the same reference is used for both get and set ioctls
replace ioctl FE_SET_PROPERTY :c:type:`FE_GET_PROPERTY`
-# Ignore struct used only internally at Kernel
-ignore struct dtv_cmds_h
-
# Typedefs that use the enum reference
replace typedef fe_sec_voltage_t :c:type:`fe_sec_voltage`
@@ -45,3 +35,178 @@ replace typedef fe_sec_voltage_t :c:type:`fe_sec_voltage`
replace define FE_TUNE_MODE_ONESHOT :c:func:`FE_SET_FRONTEND_TUNE_MODE`
replace define LNA_AUTO dtv-lna
replace define NO_STREAM_ID_FILTER dtv-stream-id
+
+# Those enums are defined at the frontend.h header, and not externally
+
+ignore symbol FE_IS_STUPID
+ignore symbol FE_CAN_INVERSION_AUTO
+ignore symbol FE_CAN_FEC_1_2
+ignore symbol FE_CAN_FEC_2_3
+ignore symbol FE_CAN_FEC_3_4
+ignore symbol FE_CAN_FEC_4_5
+ignore symbol FE_CAN_FEC_5_6
+ignore symbol FE_CAN_FEC_6_7
+ignore symbol FE_CAN_FEC_7_8
+ignore symbol FE_CAN_FEC_8_9
+ignore symbol FE_CAN_FEC_AUTO
+ignore symbol FE_CAN_QPSK
+ignore symbol FE_CAN_QAM_16
+ignore symbol FE_CAN_QAM_32
+ignore symbol FE_CAN_QAM_64
+ignore symbol FE_CAN_QAM_128
+ignore symbol FE_CAN_QAM_256
+ignore symbol FE_CAN_QAM_AUTO
+ignore symbol FE_CAN_TRANSMISSION_MODE_AUTO
+ignore symbol FE_CAN_BANDWIDTH_AUTO
+ignore symbol FE_CAN_GUARD_INTERVAL_AUTO
+ignore symbol FE_CAN_HIERARCHY_AUTO
+ignore symbol FE_CAN_8VSB
+ignore symbol FE_CAN_16VSB
+ignore symbol FE_HAS_EXTENDED_CAPS
+ignore symbol FE_CAN_MULTISTREAM
+ignore symbol FE_CAN_TURBO_FEC
+ignore symbol FE_CAN_2G_MODULATION
+ignore symbol FE_NEEDS_BENDING
+ignore symbol FE_CAN_RECOVER
+ignore symbol FE_CAN_MUTE_TS
+
+ignore symbol QPSK
+ignore symbol QAM_16
+ignore symbol QAM_32
+ignore symbol QAM_64
+ignore symbol QAM_128
+ignore symbol QAM_256
+ignore symbol QAM_AUTO
+ignore symbol VSB_8
+ignore symbol VSB_16
+ignore symbol PSK_8
+ignore symbol APSK_16
+ignore symbol APSK_32
+ignore symbol DQPSK
+ignore symbol QAM_4_NR
+
+ignore symbol SEC_VOLTAGE_13
+ignore symbol SEC_VOLTAGE_18
+ignore symbol SEC_VOLTAGE_OFF
+
+ignore symbol SEC_TONE_ON
+ignore symbol SEC_TONE_OFF
+
+ignore symbol SEC_MINI_A
+ignore symbol SEC_MINI_B
+
+ignore symbol FE_NONE
+ignore symbol FE_HAS_SIGNAL
+ignore symbol FE_HAS_CARRIER
+ignore symbol FE_HAS_VITERBI
+ignore symbol FE_HAS_SYNC
+ignore symbol FE_HAS_LOCK
+ignore symbol FE_REINIT
+ignore symbol FE_TIMEDOUT
+
+ignore symbol FEC_NONE
+ignore symbol FEC_1_2
+ignore symbol FEC_2_3
+ignore symbol FEC_3_4
+ignore symbol FEC_4_5
+ignore symbol FEC_5_6
+ignore symbol FEC_6_7
+ignore symbol FEC_7_8
+ignore symbol FEC_8_9
+ignore symbol FEC_AUTO
+ignore symbol FEC_3_5
+ignore symbol FEC_9_10
+ignore symbol FEC_2_5
+
+ignore symbol TRANSMISSION_MODE_AUTO
+ignore symbol TRANSMISSION_MODE_1K
+ignore symbol TRANSMISSION_MODE_2K
+ignore symbol TRANSMISSION_MODE_8K
+ignore symbol TRANSMISSION_MODE_4K
+ignore symbol TRANSMISSION_MODE_16K
+ignore symbol TRANSMISSION_MODE_32K
+ignore symbol TRANSMISSION_MODE_C1
+ignore symbol TRANSMISSION_MODE_C3780
+ignore symbol TRANSMISSION_MODE_2K
+ignore symbol TRANSMISSION_MODE_8K
+
+ignore symbol GUARD_INTERVAL_AUTO
+ignore symbol GUARD_INTERVAL_1_128
+ignore symbol GUARD_INTERVAL_1_32
+ignore symbol GUARD_INTERVAL_1_16
+ignore symbol GUARD_INTERVAL_1_8
+ignore symbol GUARD_INTERVAL_1_4
+ignore symbol GUARD_INTERVAL_19_128
+ignore symbol GUARD_INTERVAL_19_256
+ignore symbol GUARD_INTERVAL_PN420
+ignore symbol GUARD_INTERVAL_PN595
+ignore symbol GUARD_INTERVAL_PN945
+
+ignore symbol HIERARCHY_NONE
+ignore symbol HIERARCHY_AUTO
+ignore symbol HIERARCHY_1
+ignore symbol HIERARCHY_2
+ignore symbol HIERARCHY_4
+
+ignore symbol INTERLEAVING_NONE
+ignore symbol INTERLEAVING_AUTO
+ignore symbol INTERLEAVING_240
+ignore symbol INTERLEAVING_720
+
+ignore symbol PILOT_ON
+ignore symbol PILOT_OFF
+ignore symbol PILOT_AUTO
+
+ignore symbol ROLLOFF_35
+ignore symbol ROLLOFF_20
+ignore symbol ROLLOFF_25
+ignore symbol ROLLOFF_AUTO
+
+ignore symbol INVERSION_ON
+ignore symbol INVERSION_OFF
+ignore symbol INVERSION_AUTO
+
+ignore symbol SYS_UNDEFINED
+ignore symbol SYS_DVBC_ANNEX_A
+ignore symbol SYS_DVBC_ANNEX_B
+ignore symbol SYS_DVBC_ANNEX_C
+ignore symbol SYS_ISDBC
+ignore symbol SYS_DVBT
+ignore symbol SYS_DVBT2
+ignore symbol SYS_ISDBT
+ignore symbol SYS_ATSC
+ignore symbol SYS_ATSCMH
+ignore symbol SYS_DTMB
+ignore symbol SYS_DVBS
+ignore symbol SYS_DVBS2
+ignore symbol SYS_TURBO
+ignore symbol SYS_ISDBS
+ignore symbol SYS_DAB
+ignore symbol SYS_DSS
+ignore symbol SYS_CMMB
+ignore symbol SYS_DVBH
+
+ignore symbol ATSCMH_SCCC_BLK_SEP
+ignore symbol ATSCMH_SCCC_BLK_COMB
+ignore symbol ATSCMH_SCCC_BLK_RES
+
+ignore symbol ATSCMH_SCCC_CODE_HLF
+ignore symbol ATSCMH_SCCC_CODE_QTR
+ignore symbol ATSCMH_SCCC_CODE_RES
+
+ignore symbol ATSCMH_RSFRAME_ENS_PRI
+ignore symbol ATSCMH_RSFRAME_ENS_SEC
+
+ignore symbol ATSCMH_RSFRAME_PRI_ONLY
+ignore symbol ATSCMH_RSFRAME_PRI_SEC
+ignore symbol ATSCMH_RSFRAME_RES
+
+ignore symbol ATSCMH_RSCODE_211_187
+ignore symbol ATSCMH_RSCODE_223_187
+ignore symbol ATSCMH_RSCODE_235_187
+ignore symbol ATSCMH_RSCODE_RES
+
+ignore symbol FE_SCALE_NOT_AVAILABLE
+ignore symbol FE_SCALE_DECIBEL
+ignore symbol FE_SCALE_RELATIVE
+ignore symbol FE_SCALE_COUNTER
diff --git a/Documentation/media/uapi/dvb/dtv-fe-stats.rst b/Documentation/media/uapi/dvb/dtv-fe-stats.rst
deleted file mode 100644
index e8a02a1f138d..000000000000
--- a/Documentation/media/uapi/dvb/dtv-fe-stats.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-.. c:type:: dtv_fe_stats
-
-*******************
-struct dtv_fe_stats
-*******************
-
-
-.. code-block:: c
-
- #define MAX_DTV_STATS 4
-
- struct dtv_fe_stats {
- __u8 len;
- struct dtv_stats stat[MAX_DTV_STATS];
- } __packed;
diff --git a/Documentation/media/uapi/dvb/dtv-properties.rst b/Documentation/media/uapi/dvb/dtv-properties.rst
deleted file mode 100644
index 48c4e834ad11..000000000000
--- a/Documentation/media/uapi/dvb/dtv-properties.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-.. c:type:: dtv_properties
-
-*********************
-struct dtv_properties
-*********************
-
-
-.. code-block:: c
-
- struct dtv_properties {
- __u32 num;
- struct dtv_property *props;
- };
diff --git a/Documentation/media/uapi/dvb/dtv-property.rst b/Documentation/media/uapi/dvb/dtv-property.rst
deleted file mode 100644
index 3ddc3474b00e..000000000000
--- a/Documentation/media/uapi/dvb/dtv-property.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-.. c:type:: dtv_property
-
-*******************
-struct dtv_property
-*******************
-
-
-.. code-block:: c
-
- /* Reserved fields should be set to 0 */
-
- struct dtv_property {
- __u32 cmd;
- __u32 reserved[3];
- union {
- __u32 data;
- struct dtv_fe_stats st;
- struct {
- __u8 data[32];
- __u32 len;
- __u32 reserved1[3];
- void *reserved2;
- } buffer;
- } u;
- int result;
- } __attribute__ ((packed));
-
- /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
- #define DTV_IOCTL_MAX_MSGS 64
diff --git a/Documentation/media/uapi/dvb/dtv-stats.rst b/Documentation/media/uapi/dvb/dtv-stats.rst
deleted file mode 100644
index 35239e72bf74..000000000000
--- a/Documentation/media/uapi/dvb/dtv-stats.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-.. c:type:: dtv_stats
-
-****************
-struct dtv_stats
-****************
-
-
-.. code-block:: c
-
- struct dtv_stats {
- __u8 scale; /* enum fecap_scale_params type */
- union {
- __u64 uvalue; /* for counters and relative scales */
- __s64 svalue; /* for 1/1000 dB measures */
- };
- } __packed;
diff --git a/Documentation/media/uapi/dvb/dvbproperty-006.rst b/Documentation/media/uapi/dvb/dvbproperty-006.rst
deleted file mode 100644
index 3343a0f306fe..000000000000
--- a/Documentation/media/uapi/dvb/dvbproperty-006.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-**************
-Property types
-**************
-
-On :ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>`,
-the actual action is determined by the dtv_property cmd/data pairs.
-With one single ioctl, is possible to get/set up to 64 properties. The
-actual meaning of each property is described on the next sections.
-
-The available frontend property types are shown on the next section.
diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst
index 843f1d70aff0..c40943be5925 100644
--- a/Documentation/media/uapi/dvb/dvbproperty.rst
+++ b/Documentation/media/uapi/dvb/dvbproperty.rst
@@ -2,8 +2,9 @@
.. _frontend-properties:
-DVB Frontend properties
-=======================
+**************
+Property types
+**************
Tuning into a Digital TV physical channel and starting decoding it
requires changing a set of parameters, in order to control the tuner,
@@ -20,10 +21,15 @@ enough to group the structs that would be required for those new
standards. Also, extending it would break userspace.
So, the legacy union/struct based approach was deprecated, in favor
-of a properties set approach.
+of a properties set approach. On such approach,
+:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used
+to setup the frontend and read its status.
+
+The actual action is determined by a set of dtv_property cmd/data pairs.
+With one single ioctl, is possible to get/set up to 64 properties.
This section describes the new and recommended way to set the frontend,
-with suppports all digital TV delivery systems.
+with supports all digital TV delivery systems.
.. note::
@@ -63,12 +69,9 @@ Mbauds, those properties should be sent to
The code that would that would do the above is show in
:ref:`dtv-prop-example`.
-.. _dtv-prop-example:
-
-Example: Setting digital TV frontend properties
-===============================================
-
.. code-block:: c
+ :caption: Example: Setting digital TV frontend properties
+ :name: dtv-prop-example
#include <stdio.h>
#include <fcntl.h>
@@ -112,17 +115,12 @@ Example: Setting digital TV frontend properties
provides methods for usual operations like program scanning and to
read/write channel descriptor files.
-
.. toctree::
:maxdepth: 1
- dtv-stats
- dtv-fe-stats
- dtv-property
- dtv-properties
- dvbproperty-006
fe_property_parameters
frontend-stat-properties
frontend-property-terrestrial-systems
frontend-property-cable-systems
frontend-property-satellite-systems
+ frontend-header
diff --git a/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst
index 302db2857f90..473855584d7f 100644
--- a/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst
+++ b/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst
@@ -26,8 +26,7 @@ Arguments
File descriptor returned by :ref:`open() <frontend_f_open>`.
``argp``
- pointer to struct
- :c:type:`dvb_diseqc_slave_reply`
+ pointer to struct :c:type:`dvb_diseqc_slave_reply`.
Description
@@ -35,42 +34,7 @@ Description
Receives reply from a DiSEqC 2.0 command.
-.. c:type:: dvb_diseqc_slave_reply
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: struct dvb_diseqc_slave_reply
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - uint8_t
-
- - msg[4]
-
- - DiSEqC message (framing, data[3])
-
- - .. row 2
-
- - uint8_t
-
- - msg_len
-
- - Length of the DiSEqC message. Valid values are 0 to 4, where 0
- means no msg
-
- - .. row 3
-
- - int
-
- - timeout
-
- - Return from ioctl after timeout ms with errorcode when no message
- was received
-
+The received message is stored at the buffer pointed by ``argp``.
Return Value
============
diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst
index e962f6ec5aaf..54d35517e784 100644
--- a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst
+++ b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst
@@ -26,7 +26,7 @@ Arguments
File descriptor returned by :ref:`open() <frontend_f_open>`.
``tone``
- an integer enumered value described at :c:type:`fe_sec_mini_cmd`
+ An integer enumered value described at :c:type:`fe_sec_mini_cmd`.
Description
@@ -39,35 +39,6 @@ read/write permissions.
It provides support for what's specified at
`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. <http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf>`__
-.. c:type:: fe_sec_mini_cmd
-
-.. flat-table:: enum fe_sec_mini_cmd
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _SEC-MINI-A:
-
- ``SEC_MINI_A``
-
- - Sends a mini-DiSEqC 22kHz '0' Tone Burst to select satellite-A
-
- - .. row 3
-
- - .. _SEC-MINI-B:
-
- ``SEC_MINI_B``
-
- - Sends a mini-DiSEqC 22kHz '1' Data Burst to select satellite-B
-
Return Value
============
diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst
index bbcab3df39b5..7392d6747ad6 100644
--- a/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst
+++ b/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst
@@ -33,34 +33,7 @@ Arguments
Description
===========
-Sends a DiSEqC command to the antenna subsystem.
-
-
-.. c:type:: dvb_diseqc_master_cmd
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: struct dvb_diseqc_master_cmd
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - uint8_t
-
- - msg[6]
-
- - DiSEqC message (framing, address, command, data[3])
-
- - .. row 2
-
- - uint8_t
-
- - msg_len
-
- - Length of the DiSEqC message. Valid values are 3 to 6
+Sends the DiSEqC command pointed by ``argp`` to the antenna subsystem.
Return Value
============
diff --git a/Documentation/media/uapi/dvb/fe-get-info.rst b/Documentation/media/uapi/dvb/fe-get-info.rst
index e3d64b251f61..30dde8a791f3 100644
--- a/Documentation/media/uapi/dvb/fe-get-info.rst
+++ b/Documentation/media/uapi/dvb/fe-get-info.rst
@@ -40,112 +40,6 @@ takes a pointer to dvb_frontend_info which is filled by the driver.
When the driver is not compatible with this specification the ioctl
returns an error.
-.. c:type:: dvb_frontend_info
-
-.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-
-.. flat-table:: struct dvb_frontend_info
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - char
-
- - name[128]
-
- - Name of the frontend
-
- - .. row 2
-
- - fe_type_t
-
- - type
-
- - **DEPRECATED**. DVBv3 type. Should not be used on modern programs,
- as a frontend may have more than one type. So, the DVBv5 API
- should be used instead to enumerate and select the frontend type.
-
- - .. row 3
-
- - uint32_t
-
- - frequency_min
-
- - Minimal frequency supported by the frontend
-
- - .. row 4
-
- - uint32_t
-
- - frequency_max
-
- - Maximal frequency supported by the frontend
-
- - .. row 5
-
- - uint32_t
-
- - frequency_stepsize
-
- - Frequency step - all frequencies are multiple of this value
-
- - .. row 6
-
- - uint32_t
-
- - frequency_tolerance
-
- - Tolerance of the frequency
-
- - .. row 7
-
- - uint32_t
-
- - symbol_rate_min
-
- - Minimal symbol rate (for Cable/Satellite systems), in bauds
-
- - .. row 8
-
- - uint32_t
-
- - symbol_rate_max
-
- - Maximal symbol rate (for Cable/Satellite systems), in bauds
-
- - .. row 9
-
- - uint32_t
-
- - symbol_rate_tolerance
-
- - Maximal symbol rate tolerance, in ppm
-
- - .. row 10
-
- - uint32_t
-
- - notifier_delay
-
- - **DEPRECATED**. Not used by any driver.
-
- - .. row 11
-
- - enum :c:type:`fe_caps`
-
- - caps
-
- - Capabilities supported by the frontend
-
-
-.. note::
-
- The frequencies are specified in Hz for Terrestrial and Cable
- systems. They're specified in kHz for Satellite systems
-
frontend capabilities
=====================
@@ -153,269 +47,7 @@ frontend capabilities
Capabilities describe what a frontend can do. Some capabilities are
supported only on some specific frontend types.
-.. c:type:: fe_caps
-
-.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
-
-.. flat-table:: enum fe_caps
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _FE-IS-STUPID:
-
- ``FE_IS_STUPID``
-
- - There's something wrong at the frontend, and it can't report its
- capabilities
-
- - .. row 3
-
- - .. _FE-CAN-INVERSION-AUTO:
-
- ``FE_CAN_INVERSION_AUTO``
-
- - The frontend is capable of auto-detecting inversion
-
- - .. row 4
-
- - .. _FE-CAN-FEC-1-2:
-
- ``FE_CAN_FEC_1_2``
-
- - The frontend supports FEC 1/2
-
- - .. row 5
-
- - .. _FE-CAN-FEC-2-3:
-
- ``FE_CAN_FEC_2_3``
-
- - The frontend supports FEC 2/3
-
- - .. row 6
-
- - .. _FE-CAN-FEC-3-4:
-
- ``FE_CAN_FEC_3_4``
-
- - The frontend supports FEC 3/4
-
- - .. row 7
-
- - .. _FE-CAN-FEC-4-5:
-
- ``FE_CAN_FEC_4_5``
-
- - The frontend supports FEC 4/5
-
- - .. row 8
-
- - .. _FE-CAN-FEC-5-6:
-
- ``FE_CAN_FEC_5_6``
-
- - The frontend supports FEC 5/6
-
- - .. row 9
-
- - .. _FE-CAN-FEC-6-7:
-
- ``FE_CAN_FEC_6_7``
-
- - The frontend supports FEC 6/7
-
- - .. row 10
-
- - .. _FE-CAN-FEC-7-8:
-
- ``FE_CAN_FEC_7_8``
-
- - The frontend supports FEC 7/8
-
- - .. row 11
-
- - .. _FE-CAN-FEC-8-9:
-
- ``FE_CAN_FEC_8_9``
-
- - The frontend supports FEC 8/9
-
- - .. row 12
-
- - .. _FE-CAN-FEC-AUTO:
-
- ``FE_CAN_FEC_AUTO``
-
- - The frontend can autodetect FEC.
-
- - .. row 13
-
- - .. _FE-CAN-QPSK:
-
- ``FE_CAN_QPSK``
-
- - The frontend supports QPSK modulation
-
- - .. row 14
-
- - .. _FE-CAN-QAM-16:
-
- ``FE_CAN_QAM_16``
-
- - The frontend supports 16-QAM modulation
-
- - .. row 15
-
- - .. _FE-CAN-QAM-32:
-
- ``FE_CAN_QAM_32``
-
- - The frontend supports 32-QAM modulation
-
- - .. row 16
-
- - .. _FE-CAN-QAM-64:
-
- ``FE_CAN_QAM_64``
-
- - The frontend supports 64-QAM modulation
-
- - .. row 17
-
- - .. _FE-CAN-QAM-128:
-
- ``FE_CAN_QAM_128``
-
- - The frontend supports 128-QAM modulation
-
- - .. row 18
-
- - .. _FE-CAN-QAM-256:
-
- ``FE_CAN_QAM_256``
-
- - The frontend supports 256-QAM modulation
-
- - .. row 19
-
- - .. _FE-CAN-QAM-AUTO:
-
- ``FE_CAN_QAM_AUTO``
-
- - The frontend can autodetect modulation
-
- - .. row 20
-
- - .. _FE-CAN-TRANSMISSION-MODE-AUTO:
-
- ``FE_CAN_TRANSMISSION_MODE_AUTO``
-
- - The frontend can autodetect the transmission mode
-
- - .. row 21
-
- - .. _FE-CAN-BANDWIDTH-AUTO:
-
- ``FE_CAN_BANDWIDTH_AUTO``
-
- - The frontend can autodetect the bandwidth
-
- - .. row 22
-
- - .. _FE-CAN-GUARD-INTERVAL-AUTO:
-
- ``FE_CAN_GUARD_INTERVAL_AUTO``
-
- - The frontend can autodetect the guard interval
-
- - .. row 23
-
- - .. _FE-CAN-HIERARCHY-AUTO:
-
- ``FE_CAN_HIERARCHY_AUTO``
-
- - The frontend can autodetect hierarch
-
- - .. row 24
-
- - .. _FE-CAN-8VSB:
-
- ``FE_CAN_8VSB``
-
- - The frontend supports 8-VSB modulation
-
- - .. row 25
-
- - .. _FE-CAN-16VSB:
-
- ``FE_CAN_16VSB``
-
- - The frontend supports 16-VSB modulation
-
- - .. row 26
-
- - .. _FE-HAS-EXTENDED-CAPS:
-
- ``FE_HAS_EXTENDED_CAPS``
-
- - Currently, unused
-
- - .. row 27
-
- - .. _FE-CAN-MULTISTREAM:
-
- ``FE_CAN_MULTISTREAM``
-
- - The frontend supports multistream filtering
-
- - .. row 28
-
- - .. _FE-CAN-TURBO-FEC:
-
- ``FE_CAN_TURBO_FEC``
-
- - The frontend supports turbo FEC modulation
-
- - .. row 29
-
- - .. _FE-CAN-2G-MODULATION:
-
- ``FE_CAN_2G_MODULATION``
-
- - The frontend supports "2nd generation modulation" (DVB-S2/T2)>
-
- - .. row 30
-
- - .. _FE-NEEDS-BENDING:
-
- ``FE_NEEDS_BENDING``
-
- - Not supported anymore, don't use it
-
- - .. row 31
-
- - .. _FE-CAN-RECOVER:
-
- ``FE_CAN_RECOVER``
-
- - The frontend can recover from a cable unplug automatically
-
- - .. row 32
-
- - .. _FE-CAN-MUTE-TS:
-
- ``FE_CAN_MUTE_TS``
-
- - The frontend can stop spurious TS data output
+The frontend capabilities are described at :c:type:`fe_caps`.
Return Value
diff --git a/Documentation/media/uapi/dvb/fe-get-property.rst b/Documentation/media/uapi/dvb/fe-get-property.rst
index 015d4db597b5..b22e37c4a787 100644
--- a/Documentation/media/uapi/dvb/fe-get-property.rst
+++ b/Documentation/media/uapi/dvb/fe-get-property.rst
@@ -29,7 +29,7 @@ Arguments
File descriptor returned by :ref:`open() <frontend_f_open>`.
``argp``
- pointer to struct :c:type:`dtv_properties`
+ Pointer to struct :c:type:`dtv_properties`.
Description
diff --git a/Documentation/media/uapi/dvb/fe-read-status.rst b/Documentation/media/uapi/dvb/fe-read-status.rst
index 76b93e386552..21b2db3591fd 100644
--- a/Documentation/media/uapi/dvb/fe-read-status.rst
+++ b/Documentation/media/uapi/dvb/fe-read-status.rst
@@ -52,89 +52,6 @@ The fe_status parameter is used to indicate the current state and/or
state changes of the frontend hardware. It is produced using the enum
:c:type:`fe_status` values on a bitmask
-.. c:type:: fe_status
-
-.. tabularcolumns:: |p{3.5cm}|p{14.0cm}|
-
-.. _fe-status:
-
-.. flat-table:: enum fe_status
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _FE-NONE:
-
- ``FE_NONE``
-
- - The frontend doesn't have any kind of lock. That's the initial frontend status
-
- - .. row 3
-
- - .. _FE-HAS-SIGNAL:
-
- ``FE_HAS_SIGNAL``
-
- - The frontend has found something above the noise level
-
- - .. row 4
-
- - .. _FE-HAS-CARRIER:
-
- ``FE_HAS_CARRIER``
-
- - The frontend has found a DVB signal
-
- - .. row 5
-
- - .. _FE-HAS-VITERBI:
-
- ``FE_HAS_VITERBI``
-
- - The frontend FEC inner coding (Viterbi, LDPC or other inner code)
- is stable
-
- - .. row 6
-
- - .. _FE-HAS-SYNC:
-
- ``FE_HAS_SYNC``
-
- - Synchronization bytes was found
-
- - .. row 7
-
- - .. _FE-HAS-LOCK:
-
- ``FE_HAS_LOCK``
-
- - The DVB were locked and everything is working
-
- - .. row 8
-
- - .. _FE-TIMEDOUT:
-
- ``FE_TIMEDOUT``
-
- - no lock within the last about 2 seconds
-
- - .. row 9
-
- - .. _FE-REINIT:
-
- ``FE_REINIT``
-
- - The frontend was reinitialized, application is recommended to
- reset DiSEqC, tone and parameters
-
Return Value
============
diff --git a/Documentation/media/uapi/dvb/fe-set-tone.rst b/Documentation/media/uapi/dvb/fe-set-tone.rst
index 84e4da3fd4c9..d0950acbbe64 100644
--- a/Documentation/media/uapi/dvb/fe-set-tone.rst
+++ b/Documentation/media/uapi/dvb/fe-set-tone.rst
@@ -45,36 +45,6 @@ this is done using the DiSEqC ioctls.
capability of selecting the band. So, it is recommended that applications
would change to SEC_TONE_OFF when the device is not used.
-.. c:type:: fe_sec_tone_mode
-
-.. flat-table:: enum fe_sec_tone_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _SEC-TONE-ON:
-
- ``SEC_TONE_ON``
-
- - Sends a 22kHz tone burst to the antenna
-
- - .. row 3
-
- - .. _SEC-TONE-OFF:
-
- ``SEC_TONE_OFF``
-
- - Don't send a 22kHz tone to the antenna (except if the
- FE_DISEQC_* ioctls are called)
-
Return Value
============
diff --git a/Documentation/media/uapi/dvb/fe_property_parameters.rst b/Documentation/media/uapi/dvb/fe_property_parameters.rst
index 7bb7559c4500..c6eb74f59b00 100644
--- a/Documentation/media/uapi/dvb/fe_property_parameters.rst
+++ b/Documentation/media/uapi/dvb/fe_property_parameters.rst
@@ -6,6 +6,11 @@
Digital TV property parameters
******************************
+There are several different Digital TV parameters that can be used by
+:ref:`FE_SET_PROPERTY and FE_GET_PROPERTY ioctls<FE_GET_PROPERTY>`.
+This section describes each of them. Please notice, however, that only
+a subset of them are needed to setup a frontend.
+
.. _DTV-UNDEFINED:
@@ -67,144 +72,36 @@ DTV_MODULATION
==============
Specifies the frontend modulation type for delivery systems that
-supports more than one modulation type. The modulation can be one of the
-types defined by enum :c:type:`fe_modulation`.
-
-
-.. c:type:: fe_modulation
-
-Modulation property
--------------------
-
-Most of the digital TV standards currently offers more than one possible
-modulation (sometimes called as "constellation" on some standards). This
-enum contains the values used by the Kernel. Please note that not all
-modulations are supported by a given standard.
-
-
-.. flat-table:: enum fe_modulation
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _QPSK:
-
- ``QPSK``
-
- - QPSK modulation
-
- - .. row 3
-
- - .. _QAM-16:
-
- ``QAM_16``
-
- - 16-QAM modulation
-
- - .. row 4
-
- - .. _QAM-32:
-
- ``QAM_32``
-
- - 32-QAM modulation
-
- - .. row 5
-
- - .. _QAM-64:
-
- ``QAM_64``
-
- - 64-QAM modulation
-
- - .. row 6
-
- - .. _QAM-128:
-
- ``QAM_128``
-
- - 128-QAM modulation
-
- - .. row 7
-
- - .. _QAM-256:
-
- ``QAM_256``
-
- - 256-QAM modulation
-
- - .. row 8
-
- - .. _QAM-AUTO:
-
- ``QAM_AUTO``
-
- - Autodetect QAM modulation
-
- - .. row 9
-
- - .. _VSB-8:
-
- ``VSB_8``
-
- - 8-VSB modulation
-
- - .. row 10
-
- - .. _VSB-16:
-
- ``VSB_16``
-
- - 16-VSB modulation
-
- - .. row 11
-
- - .. _PSK-8:
-
- ``PSK_8``
-
- - 8-PSK modulation
-
- - .. row 12
-
- - .. _APSK-16:
-
- ``APSK_16``
-
- - 16-APSK modulation
-
- - .. row 13
-
- - .. _APSK-32:
-
- ``APSK_32``
-
- - 32-APSK modulation
-
- - .. row 14
-
- - .. _DQPSK:
-
- ``DQPSK``
-
- - DQPSK modulation
-
- - .. row 15
-
- - .. _QAM-4-NR:
-
- ``QAM_4_NR``
-
- - 4-QAM-NR modulation
-
+supports more multiple modulations.
+
+The modulation can be one of the types defined by enum :c:type:`fe_modulation`.
+
+Most of the digital TV standards offers more than one possible
+modulation type.
+
+The table below presents a summary of the types of modulation types
+supported by each delivery system, as currently defined by specs.
+
+======================= =======================================================
+Standard Modulation types
+======================= =======================================================
+ATSC (version 1) 8-VSB and 16-VSB.
+DMTB 4-QAM, 16-QAM, 32-QAM, 64-QAM and 4-QAM-NR.
+DVB-C Annex A/C 16-QAM, 32-QAM, 64-QAM and 256-QAM.
+DVB-C Annex B 64-QAM.
+DVB-T QPSK, 16-QAM and 64-QAM.
+DVB-T2 QPSK, 16-QAM, 64-QAM and 256-QAM.
+DVB-S No need to set. It supports only QPSK.
+DVB-S2 QPSK, 8-PSK, 16-APSK and 32-APSK.
+ISDB-T QPSK, DQPSK, 16-QAM and 64-QAM.
+ISDB-S 8-PSK, QPSK and BPSK.
+======================= =======================================================
+
+.. note::
+
+ Please notice that some of the above modulation types may not be
+ defined currently at the Kernel. The reason is simple: no driver
+ needed such definition yet.
.. _DTV-BANDWIDTH-HZ:
@@ -249,54 +146,7 @@ DTV_INVERSION
Specifies if the frontend should do spectral inversion or not.
-.. c:type:: fe_spectral_inversion
-
-enum fe_modulation: Frontend spectral inversion
------------------------------------------------
-
-This parameter indicates if spectral inversion should be presumed or
-not. In the automatic setting (``INVERSION_AUTO``) the hardware will try
-to figure out the correct setting by itself. If the hardware doesn't
-support, the DVB core will try to lock at the carrier first with
-inversion off. If it fails, it will try to enable inversion.
-
-
-.. flat-table:: enum fe_modulation
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _INVERSION-OFF:
-
- ``INVERSION_OFF``
-
- - Don't do spectral band inversion.
-
- - .. row 3
-
- - .. _INVERSION-ON:
-
- ``INVERSION_ON``
-
- - Do spectral band inversion.
-
- - .. row 4
-
- - .. _INVERSION-AUTO:
-
- ``INVERSION_AUTO``
-
- - Autodetect spectral band inversion.
-
-
+The acceptable values are defined by :c:type:`fe_spectral_inversion`.
.. _DTV-DISEQC-MASTER:
@@ -320,128 +170,9 @@ standards.
DTV_INNER_FEC
=============
-Used cable/satellite transmissions. The acceptable values are:
-
-.. c:type:: fe_code_rate
-
-enum fe_code_rate: type of the Forward Error Correction.
---------------------------------------------------------
-
-.. flat-table:: enum fe_code_rate
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _FEC-NONE:
-
- ``FEC_NONE``
-
- - No Forward Error Correction Code
-
- - .. row 3
-
- - .. _FEC-AUTO:
-
- ``FEC_AUTO``
-
- - Autodetect Error Correction Code
-
- - .. row 4
-
- - .. _FEC-1-2:
-
- ``FEC_1_2``
-
- - Forward Error Correction Code 1/2
-
- - .. row 5
-
- - .. _FEC-2-3:
-
- ``FEC_2_3``
-
- - Forward Error Correction Code 2/3
-
- - .. row 6
-
- - .. _FEC-3-4:
-
- ``FEC_3_4``
-
- - Forward Error Correction Code 3/4
-
- - .. row 7
-
- - .. _FEC-4-5:
-
- ``FEC_4_5``
-
- - Forward Error Correction Code 4/5
-
- - .. row 8
-
- - .. _FEC-5-6:
-
- ``FEC_5_6``
-
- - Forward Error Correction Code 5/6
-
- - .. row 9
-
- - .. _FEC-6-7:
-
- ``FEC_6_7``
-
- - Forward Error Correction Code 6/7
-
- - .. row 10
-
- - .. _FEC-7-8:
-
- ``FEC_7_8``
-
- - Forward Error Correction Code 7/8
-
- - .. row 11
-
- - .. _FEC-8-9:
-
- ``FEC_8_9``
-
- - Forward Error Correction Code 8/9
-
- - .. row 12
-
- - .. _FEC-9-10:
-
- ``FEC_9_10``
-
- - Forward Error Correction Code 9/10
-
- - .. row 13
-
- - .. _FEC-2-5:
-
- ``FEC_2_5``
-
- - Forward Error Correction Code 2/5
-
- - .. row 14
-
- - .. _FEC-3-5:
-
- ``FEC_3_5``
-
- - Forward Error Correction Code 3/5
+Used cable/satellite transmissions.
+The acceptable values are defined by :c:type:`fe_code_rate`.
.. _DTV-VOLTAGE:
@@ -454,44 +185,7 @@ polarzation (horizontal/vertical). When using DiSEqC epuipment this
voltage has to be switched consistently to the DiSEqC commands as
described in the DiSEqC spec.
-
-.. c:type:: fe_sec_voltage
-
-.. flat-table:: enum fe_sec_voltage
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _SEC-VOLTAGE-13:
-
- ``SEC_VOLTAGE_13``
-
- - Set DC voltage level to 13V
-
- - .. row 3
-
- - .. _SEC-VOLTAGE-18:
-
- ``SEC_VOLTAGE_18``
-
- - Set DC voltage level to 18V
-
- - .. row 4
-
- - .. _SEC-VOLTAGE-OFF:
-
- ``SEC_VOLTAGE_OFF``
-
- - Don't send any voltage to the antenna
-
+The acceptable values are defined by :c:type:`fe_sec_voltage`.
.. _DTV-TONE:
@@ -507,50 +201,9 @@ Currently not used.
DTV_PILOT
=========
-Sets DVB-S2 pilot
-
-
-.. c:type:: fe_pilot
-
-fe_pilot type
--------------
-
-
-.. flat-table:: enum fe_pilot
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _PILOT-ON:
-
- ``PILOT_ON``
-
- - Pilot tones enabled
-
- - .. row 3
-
- - .. _PILOT-OFF:
-
- ``PILOT_OFF``
-
- - Pilot tones disabled
-
- - .. row 4
-
- - .. _PILOT-AUTO:
-
- ``PILOT_AUTO``
-
- - Autodetect pilot tones
+Sets DVB-S2 pilot.
+The acceptable values are defined by :c:type:`fe_pilot`.
.. _DTV-ROLLOFF:
@@ -560,56 +213,7 @@ DTV_ROLLOFF
Sets DVB-S2 rolloff
-
-.. c:type:: fe_rolloff
-
-fe_rolloff type
----------------
-
-
-.. flat-table:: enum fe_rolloff
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ROLLOFF-35:
-
- ``ROLLOFF_35``
-
- - Roloff factor: α=35%
-
- - .. row 3
-
- - .. _ROLLOFF-20:
-
- ``ROLLOFF_20``
-
- - Roloff factor: α=20%
-
- - .. row 4
-
- - .. _ROLLOFF-25:
-
- ``ROLLOFF_25``
-
- - Roloff factor: α=25%
-
- - .. row 5
-
- - .. _ROLLOFF-AUTO:
-
- ``ROLLOFF_AUTO``
-
- - Auto-detect the roloff factor.
-
+The acceptable values are defined by :c:type:`fe_rolloff`.
.. _DTV-DISEQC-SLAVE-REPLY:
@@ -641,180 +245,9 @@ Currently not implemented.
DTV_DELIVERY_SYSTEM
===================
-Specifies the type of Delivery system
-
-
-.. c:type:: fe_delivery_system
-
-fe_delivery_system type
------------------------
-
-Possible values:
-
-
-.. flat-table:: enum fe_delivery_system
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _SYS-UNDEFINED:
-
- ``SYS_UNDEFINED``
-
- - Undefined standard. Generally, indicates an error
-
- - .. row 3
-
- - .. _SYS-DVBC-ANNEX-A:
-
- ``SYS_DVBC_ANNEX_A``
-
- - Cable TV: DVB-C following ITU-T J.83 Annex A spec
-
- - .. row 4
-
- - .. _SYS-DVBC-ANNEX-B:
-
- ``SYS_DVBC_ANNEX_B``
-
- - Cable TV: DVB-C following ITU-T J.83 Annex B spec (ClearQAM)
-
- - .. row 5
-
- - .. _SYS-DVBC-ANNEX-C:
-
- ``SYS_DVBC_ANNEX_C``
-
- - Cable TV: DVB-C following ITU-T J.83 Annex C spec
-
- - .. row 6
-
- - .. _SYS-ISDBC:
-
- ``SYS_ISDBC``
-
- - Cable TV: ISDB-C (no drivers yet)
-
- - .. row 7
-
- - .. _SYS-DVBT:
-
- ``SYS_DVBT``
-
- - Terrestral TV: DVB-T
-
- - .. row 8
-
- - .. _SYS-DVBT2:
-
- ``SYS_DVBT2``
-
- - Terrestral TV: DVB-T2
-
- - .. row 9
-
- - .. _SYS-ISDBT:
-
- ``SYS_ISDBT``
-
- - Terrestral TV: ISDB-T
-
- - .. row 10
-
- - .. _SYS-ATSC:
-
- ``SYS_ATSC``
-
- - Terrestral TV: ATSC
-
- - .. row 11
-
- - .. _SYS-ATSCMH:
-
- ``SYS_ATSCMH``
-
- - Terrestral TV (mobile): ATSC-M/H
-
- - .. row 12
-
- - .. _SYS-DTMB:
-
- ``SYS_DTMB``
-
- - Terrestrial TV: DTMB
-
- - .. row 13
-
- - .. _SYS-DVBS:
-
- ``SYS_DVBS``
-
- - Satellite TV: DVB-S
-
- - .. row 14
-
- - .. _SYS-DVBS2:
-
- ``SYS_DVBS2``
-
- - Satellite TV: DVB-S2
-
- - .. row 15
-
- - .. _SYS-TURBO:
-
- ``SYS_TURBO``
-
- - Satellite TV: DVB-S Turbo
-
- - .. row 16
-
- - .. _SYS-ISDBS:
-
- ``SYS_ISDBS``
-
- - Satellite TV: ISDB-S
-
- - .. row 17
-
- - .. _SYS-DAB:
-
- ``SYS_DAB``
-
- - Digital audio: DAB (not fully supported)
-
- - .. row 18
-
- - .. _SYS-DSS:
-
- ``SYS_DSS``
-
- - Satellite TV:"DSS (not fully supported)
-
- - .. row 19
-
- - .. _SYS-CMMB:
-
- ``SYS_CMMB``
-
- - Terrestral TV (mobile):CMMB (not fully supported)
-
- - .. row 20
-
- - .. _SYS-DVBH:
-
- ``SYS_DVBH``
-
- - Terrestral TV (mobile): DVB-H (standard deprecated)
+Specifies the type of Delivery system.
+The acceptable values are defined by :c:type:`fe_delivery_system`.
.. _DTV-ISDBT-PARTIAL-RECEPTION:
@@ -964,7 +397,11 @@ Only the values of the first 3 bits are used. Other bits will be silently ignore
DTV_ISDBT_LAYER[A-C]_FEC
------------------------
-Possible values: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``,
+The Forward Error Correction mechanism used by a given ISDB Layer, as
+defined by :c:type:`fe_code_rate`.
+
+
+Possible values are: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``,
``FEC_5_6``, ``FEC_7_8``
@@ -973,11 +410,17 @@ Possible values: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``,
DTV_ISDBT_LAYER[A-C]_MODULATION
-------------------------------
-Possible values: ``QAM_AUTO``, QP\ ``SK, QAM_16``, ``QAM_64``, ``DQPSK``
+The modulation used by a given ISDB Layer, as defined by
+:c:type:`fe_modulation`.
-Note: If layer C is ``DQPSK`` layer B has to be ``DQPSK``. If layer B is
-``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ =0 layer has to be
-``DQPSK``.
+Possible values are: ``QAM_AUTO``, ``QPSK``, ``QAM_16``, ``QAM_64``, ``DQPSK``
+
+.. note::
+
+ #. If layer C is ``DQPSK``, then layer B has to be ``DQPSK``.
+
+ #. If layer B is ``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ = 0,
+ then layer has to be ``DQPSK``.
.. _DTV-ISDBT-LAYER-SEGMENT-COUNT:
@@ -993,15 +436,15 @@ Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and
.. _isdbt-layer_seg-cnt-table:
.. flat-table:: Truth table for ISDB-T Sound Broadcasting
- :header-rows: 0
+ :header-rows: 1
:stub-columns: 0
- .. row 1
- - PR
+ - Partial Reception
- - SB
+ - Sound Broadcasting
- Layer A width
@@ -1086,7 +529,7 @@ TMCC-structure, as shown in the table below.
.. c:type:: isdbt_layer_interleaving_table
.. flat-table:: ISDB-T time interleaving modes
- :header-rows: 0
+ :header-rows: 1
:stub-columns: 0
@@ -1216,42 +659,7 @@ DTV_ATSCMH_RS_FRAME_MODE
Reed Solomon (RS) frame mode.
-Possible values are:
-
-.. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
-
-.. c:type:: atscmh_rs_frame_mode
-
-.. flat-table:: enum atscmh_rs_frame_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-RSFRAME-PRI-ONLY:
-
- ``ATSCMH_RSFRAME_PRI_ONLY``
-
- - Single Frame: There is only a primary RS Frame for all Group
- Regions.
-
- - .. row 3
-
- - .. _ATSCMH-RSFRAME-PRI-SEC:
-
- ``ATSCMH_RSFRAME_PRI_SEC``
-
- - Dual Frame: There are two separate RS Frames: Primary RS Frame for
- Group Region A and B and Secondary RS Frame for Group Region C and
- D.
-
+The acceptable values are defined by :c:type:`atscmh_rs_frame_mode`.
.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE:
@@ -1261,46 +669,7 @@ DTV_ATSCMH_RS_FRAME_ENSEMBLE
Reed Solomon(RS) frame ensemble.
-Possible values are:
-
-
-.. c:type:: atscmh_rs_frame_ensemble
-
-.. flat-table:: enum atscmh_rs_frame_ensemble
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-RSFRAME-ENS-PRI:
-
- ``ATSCMH_RSFRAME_ENS_PRI``
-
- - Primary Ensemble.
-
- - .. row 3
-
- - .. _ATSCMH-RSFRAME-ENS-SEC:
-
- ``AATSCMH_RSFRAME_PRI_SEC``
-
- - Secondary Ensemble.
-
- - .. row 4
-
- - .. _ATSCMH-RSFRAME-RES:
-
- ``AATSCMH_RSFRAME_RES``
-
- - Reserved. Shouldn't be used.
-
+The acceptable values are defined by :c:type:`atscmh_rs_frame_ensemble`.
.. _DTV-ATSCMH-RS-CODE-MODE-PRI:
@@ -1310,54 +679,7 @@ DTV_ATSCMH_RS_CODE_MODE_PRI
Reed Solomon (RS) code mode (primary).
-Possible values are:
-
-
-.. c:type:: atscmh_rs_code_mode
-
-.. flat-table:: enum atscmh_rs_code_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-RSCODE-211-187:
-
- ``ATSCMH_RSCODE_211_187``
-
- - Reed Solomon code (211,187).
-
- - .. row 3
-
- - .. _ATSCMH-RSCODE-223-187:
-
- ``ATSCMH_RSCODE_223_187``
-
- - Reed Solomon code (223,187).
-
- - .. row 4
-
- - .. _ATSCMH-RSCODE-235-187:
-
- ``ATSCMH_RSCODE_235_187``
-
- - Reed Solomon code (235,187).
-
- - .. row 5
-
- - .. _ATSCMH-RSCODE-RES:
-
- ``ATSCMH_RSCODE_RES``
-
- - Reserved. Shouldn't be used.
-
+The acceptable values are defined by :c:type:`atscmh_rs_code_mode`.
.. _DTV-ATSCMH-RS-CODE-MODE-SEC:
@@ -1367,8 +689,7 @@ DTV_ATSCMH_RS_CODE_MODE_SEC
Reed Solomon (RS) code mode (secondary).
-Possible values are the same as documented on enum
-:c:type:`atscmh_rs_code_mode`:
+The acceptable values are defined by :c:type:`atscmh_rs_code_mode`.
.. _DTV-ATSCMH-SCCC-BLOCK-MODE:
@@ -1378,49 +699,7 @@ DTV_ATSCMH_SCCC_BLOCK_MODE
Series Concatenated Convolutional Code Block Mode.
-Possible values are:
-
-.. tabularcolumns:: |p{4.5cm}|p{13.0cm}|
-
-.. c:type:: atscmh_sccc_block_mode
-
-.. flat-table:: enum atscmh_scc_block_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-SCCC-BLK-SEP:
-
- ``ATSCMH_SCCC_BLK_SEP``
-
- - Separate SCCC: the SCCC outer code mode shall be set independently
- for each Group Region (A, B, C, D)
-
- - .. row 3
-
- - .. _ATSCMH-SCCC-BLK-COMB:
-
- ``ATSCMH_SCCC_BLK_COMB``
-
- - Combined SCCC: all four Regions shall have the same SCCC outer
- code mode.
-
- - .. row 4
-
- - .. _ATSCMH-SCCC-BLK-RES:
-
- ``ATSCMH_SCCC_BLK_RES``
-
- - Reserved. Shouldn't be used.
-
+The acceptable values are defined by :c:type:`atscmh_sccc_block_mode`.
.. _DTV-ATSCMH-SCCC-CODE-MODE-A:
@@ -1430,47 +709,7 @@ DTV_ATSCMH_SCCC_CODE_MODE_A
Series Concatenated Convolutional Code Rate.
-Possible values are:
-
-
-.. c:type:: atscmh_sccc_code_mode
-
-.. flat-table:: enum atscmh_sccc_code_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-SCCC-CODE-HLF:
-
- ``ATSCMH_SCCC_CODE_HLF``
-
- - The outer code rate of a SCCC Block is 1/2 rate.
-
- - .. row 3
-
- - .. _ATSCMH-SCCC-CODE-QTR:
-
- ``ATSCMH_SCCC_CODE_QTR``
-
- - The outer code rate of a SCCC Block is 1/4 rate.
-
- - .. row 4
-
- - .. _ATSCMH-SCCC-CODE-RES:
-
- ``ATSCMH_SCCC_CODE_RES``
-
- - to be documented.
-
-
+The acceptable values are defined by :c:type:`atscmh_sccc_code_mode`.
.. _DTV-ATSCMH-SCCC-CODE-MODE-B:
@@ -1518,8 +757,9 @@ Returns the major/minor version of the DVB API
DTV_CODE_RATE_HP
================
-Used on terrestrial transmissions. The acceptable values are the ones
-described at :c:type:`fe_transmit_mode`.
+Used on terrestrial transmissions.
+
+The acceptable values are defined by :c:type:`fe_transmit_mode`.
.. _DTV-CODE-RATE-LP:
@@ -1527,8 +767,9 @@ described at :c:type:`fe_transmit_mode`.
DTV_CODE_RATE_LP
================
-Used on terrestrial transmissions. The acceptable values are the ones
-described at :c:type:`fe_transmit_mode`.
+Used on terrestrial transmissions.
+
+The acceptable values are defined by :c:type:`fe_transmit_mode`.
.. _DTV-GUARD-INTERVAL:
@@ -1536,242 +777,54 @@ described at :c:type:`fe_transmit_mode`.
DTV_GUARD_INTERVAL
==================
-Possible values are:
-
-
-.. c:type:: fe_guard_interval
-
-Modulation guard interval
--------------------------
-
-
-.. flat-table:: enum fe_guard_interval
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _GUARD-INTERVAL-AUTO:
-
- ``GUARD_INTERVAL_AUTO``
-
- - Autodetect the guard interval
-
- - .. row 3
-
- - .. _GUARD-INTERVAL-1-128:
-
- ``GUARD_INTERVAL_1_128``
-
- - Guard interval 1/128
-
- - .. row 4
-
- - .. _GUARD-INTERVAL-1-32:
-
- ``GUARD_INTERVAL_1_32``
-
- - Guard interval 1/32
-
- - .. row 5
-
- - .. _GUARD-INTERVAL-1-16:
-
- ``GUARD_INTERVAL_1_16``
-
- - Guard interval 1/16
-
- - .. row 6
-
- - .. _GUARD-INTERVAL-1-8:
-
- ``GUARD_INTERVAL_1_8``
-
- - Guard interval 1/8
-
- - .. row 7
-
- - .. _GUARD-INTERVAL-1-4:
-
- ``GUARD_INTERVAL_1_4``
-
- - Guard interval 1/4
-
- - .. row 8
-
- - .. _GUARD-INTERVAL-19-128:
-
- ``GUARD_INTERVAL_19_128``
-
- - Guard interval 19/128
-
- - .. row 9
-
- - .. _GUARD-INTERVAL-19-256:
-
- ``GUARD_INTERVAL_19_256``
-
- - Guard interval 19/256
-
- - .. row 10
-
- - .. _GUARD-INTERVAL-PN420:
-
- ``GUARD_INTERVAL_PN420``
-
- - PN length 420 (1/4)
-
- - .. row 11
-
- - .. _GUARD-INTERVAL-PN595:
-
- ``GUARD_INTERVAL_PN595``
-
- - PN length 595 (1/6)
-
- - .. row 12
-
- - .. _GUARD-INTERVAL-PN945:
-
- ``GUARD_INTERVAL_PN945``
-
- - PN length 945 (1/9)
-
-
-Notes:
-
-1) If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the
-hardware will try to find the correct guard interval (if capable) and
-will use TMCC to fill in the missing parameters.
-
-2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at
-present
-
-3) DTMB specifies PN420, PN595 and PN945.
-
+The acceptable values are defined by :c:type:`fe_guard_interval`.
+
+.. note::
+
+ #. If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the
+ hardware will try to find the correct guard interval (if capable) and
+ will use TMCC to fill in the missing parameters.
+ #. Intervals ``GUARD_INTERVAL_1_128``, ``GUARD_INTERVAL_19_128``
+ and ``GUARD_INTERVAL_19_256`` are used only for DVB-T2 at
+ present.
+ #. Intervals ``GUARD_INTERVAL_PN420``, ``GUARD_INTERVAL_PN595`` and
+ ``GUARD_INTERVAL_PN945`` are used only for DMTB at the present.
+ On such standard, only those intervals and ``GUARD_INTERVAL_AUTO``
+ are valid.
.. _DTV-TRANSMISSION-MODE:
DTV_TRANSMISSION_MODE
=====================
-Specifies the number of carriers used by the standard. This is used only
-on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB
+Specifies the FFT size (with corresponds to the approximate number of
+carriers) used by the standard. This is used only on OFTM-based standards,
+e. g. DVB-T/T2, ISDB-T, DTMB.
+The acceptable values are defined by :c:type:`fe_transmit_mode`.
-.. c:type:: fe_transmit_mode
+.. note::
-enum fe_transmit_mode: Number of carriers per channel
------------------------------------------------------
+ #. ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
+ **mode** on such standard, and are numbered from 1 to 3:
-.. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
+ ==== ======== ========================
+ Mode FFT size Transmission mode
+ ==== ======== ========================
+ 1 2K ``TRANSMISSION_MODE_2K``
+ 2 4K ``TRANSMISSION_MODE_4K``
+ 3 8K ``TRANSMISSION_MODE_8K``
+ ==== ======== ========================
-.. flat-table:: enum fe_transmit_mode
- :header-rows: 1
- :stub-columns: 0
+ #. If ``DTV_TRANSMISSION_MODE`` is set the ``TRANSMISSION_MODE_AUTO``
+ the hardware will try to find the correct FFT-size (if capable) and
+ will use TMCC to fill in the missing parameters.
+ #. DVB-T specifies 2K and 8K as valid sizes.
- - .. row 1
+ #. DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _TRANSMISSION-MODE-AUTO:
-
- ``TRANSMISSION_MODE_AUTO``
-
- - Autodetect transmission mode. The hardware will try to find the
- correct FFT-size (if capable) to fill in the missing parameters.
-
- - .. row 3
-
- - .. _TRANSMISSION-MODE-1K:
-
- ``TRANSMISSION_MODE_1K``
-
- - Transmission mode 1K
-
- - .. row 4
-
- - .. _TRANSMISSION-MODE-2K:
-
- ``TRANSMISSION_MODE_2K``
-
- - Transmission mode 2K
-
- - .. row 5
-
- - .. _TRANSMISSION-MODE-8K:
-
- ``TRANSMISSION_MODE_8K``
-
- - Transmission mode 8K
-
- - .. row 6
-
- - .. _TRANSMISSION-MODE-4K:
-
- ``TRANSMISSION_MODE_4K``
-
- - Transmission mode 4K
-
- - .. row 7
-
- - .. _TRANSMISSION-MODE-16K:
-
- ``TRANSMISSION_MODE_16K``
-
- - Transmission mode 16K
-
- - .. row 8
-
- - .. _TRANSMISSION-MODE-32K:
-
- ``TRANSMISSION_MODE_32K``
-
- - Transmission mode 32K
-
- - .. row 9
-
- - .. _TRANSMISSION-MODE-C1:
-
- ``TRANSMISSION_MODE_C1``
-
- - Single Carrier (C=1) transmission mode (DTMB)
-
- - .. row 10
-
- - .. _TRANSMISSION-MODE-C3780:
-
- ``TRANSMISSION_MODE_C3780``
-
- - Multi Carrier (C=3780) transmission mode (DTMB)
-
-
-Notes:
-
-1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
-'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K
-
-2) If ``DTV_TRANSMISSION_MODE`` is set the ``TRANSMISSION_MODE_AUTO``
-the hardware will try to find the correct FFT-size (if capable) and will
-use TMCC to fill in the missing parameters.
-
-3) DVB-T specifies 2K and 8K as valid sizes.
-
-4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.
-
-5) DTMB specifies C1 and C3780.
+ #. DTMB specifies C1 and C3780.
.. _DTV-HIERARCHY:
@@ -1779,66 +832,9 @@ use TMCC to fill in the missing parameters.
DTV_HIERARCHY
=============
-Frontend hierarchy
-
-
-.. c:type:: fe_hierarchy
-
-Frontend hierarchy
-------------------
-
-
-.. flat-table:: enum fe_hierarchy
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _HIERARCHY-NONE:
-
- ``HIERARCHY_NONE``
-
- - No hierarchy
-
- - .. row 3
-
- - .. _HIERARCHY-AUTO:
-
- ``HIERARCHY_AUTO``
-
- - Autodetect hierarchy (if supported)
-
- - .. row 4
-
- - .. _HIERARCHY-1:
-
- ``HIERARCHY_1``
-
- - Hierarchy 1
-
- - .. row 5
-
- - .. _HIERARCHY-2:
-
- ``HIERARCHY_2``
-
- - Hierarchy 2
-
- - .. row 6
-
- - .. _HIERARCHY-4:
-
- ``HIERARCHY_4``
-
- - Hierarchy 4
+Frontend hierarchy.
+The acceptable values are defined by :c:type:`fe_hierarchy`.
.. _DTV-STREAM-ID:
@@ -1884,60 +880,17 @@ with it, rather than trying to use FE_GET_INFO. In the case of a
legacy frontend, the result is just the same as with FE_GET_INFO, but
in a more structured format
+The acceptable values are defined by :c:type:`fe_delivery_system`.
+
.. _DTV-INTERLEAVING:
DTV_INTERLEAVING
================
-Time interleaving to be used. Currently, used only on DTMB.
-
-
-.. c:type:: fe_interleaving
-
-.. flat-table:: enum fe_interleaving
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _INTERLEAVING-NONE:
-
- ``INTERLEAVING_NONE``
-
- - No interleaving.
-
- - .. row 3
-
- - .. _INTERLEAVING-AUTO:
-
- ``INTERLEAVING_AUTO``
-
- - Auto-detect interleaving.
-
- - .. row 4
-
- - .. _INTERLEAVING-240:
-
- ``INTERLEAVING_240``
-
- - Interleaving of 240 symbols.
-
- - .. row 5
-
- - .. _INTERLEAVING-720:
-
- ``INTERLEAVING_720``
-
- - Interleaving of 720 symbols.
+Time interleaving to be used.
+The acceptable values are defined by :c:type:`fe_interleaving`.
.. _DTV-LNA:
--git a/Documentation/media/uapi/dvb/frontend-header.rst b/Documentation/media/uapi/dvb/frontend-header.rst
new file mode 100644
index 000000000000..8d8433cf1e12
--- /dev/null
+++ b/Documentation/media/uapi/dvb/frontend-header.rst
@@ -0,0 +1,4 @@
+Frontend uAPI data types
+========================
+
+.. kernel-doc:: include/uapi/linux/dvb/frontend.h
diff --git a/include/uapi/linux/dvb/frontend.h b/include/uapi/linux/dvb/frontend.h
index a383c87256f3..8c5191f74bd4 100644
--- a/include/uapi/linux/dvb/frontend.h
+++ b/include/uapi/linux/dvb/frontend.h
@@ -562,10 +562,10 @@ enum fe_pilot {
};
/**
- * enum fe_rolloff - Rolloff factor (also known as alpha)
- * @ROLLOFF_35: Roloff factor: 35%
- * @ROLLOFF_20: Roloff factor: 20%
- * @ROLLOFF_25: Roloff factor: 25%
+ * enum fe_rolloff - Rolloff factor
+ * @ROLLOFF_35: Roloff factor: α=35%
+ * @ROLLOFF_20: Roloff factor: α=20%
+ * @ROLLOFF_25: Roloff factor: α=25%
* @ROLLOFF_AUTO: Auto-detect the roloff factor.
*
* .. note:
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 10/27] media: fe_property_parameters.rst: better define properties usage
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (8 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 09/27] media: dvb frontend docs: use kernel-doc documentation Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 11/27] media: fe_property_parameters.rst: better document bandwidth Mauro Carvalho Chehab
` (18 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Several frontend properties are specific to a subset of the
delivery systems. Make it clearer when describing each
property.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../media/uapi/dvb/fe_property_parameters.rst | 82 ++++++++++++++++++++--
1 file changed, 75 insertions(+), 7 deletions(-)
diff --git a/Documentation/media/uapi/dvb/fe_property_parameters.rst b/Documentation/media/uapi/dvb/fe_property_parameters.rst
index c6eb74f59b00..e085e84fef38 100644
--- a/Documentation/media/uapi/dvb/fe_property_parameters.rst
+++ b/Documentation/media/uapi/dvb/fe_property_parameters.rst
@@ -111,6 +111,8 @@ DTV_BANDWIDTH_HZ
Bandwidth for the channel, in HZ.
+Should be set only for terrestrial delivery systems.
+
Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``,
``8000000``, ``10000000``.
@@ -148,6 +150,7 @@ Specifies if the frontend should do spectral inversion or not.
The acceptable values are defined by :c:type:`fe_spectral_inversion`.
+
.. _DTV-DISEQC-MASTER:
DTV_DISEQC_MASTER
@@ -161,8 +164,9 @@ Currently not implemented.
DTV_SYMBOL_RATE
===============
-Digital TV symbol rate, in bauds (symbols/second). Used on cable
-standards.
+Used on cable and satellite delivery systems.
+
+Digital TV symbol rate, in bauds (symbols/second).
.. _DTV-INNER-FEC:
@@ -170,7 +174,7 @@ standards.
DTV_INNER_FEC
=============
-Used cable/satellite transmissions.
+Used on cable and satellite delivery systems.
The acceptable values are defined by :c:type:`fe_code_rate`.
@@ -180,6 +184,8 @@ The acceptable values are defined by :c:type:`fe_code_rate`.
DTV_VOLTAGE
===========
+Used on satellite delivery systems.
+
The voltage is usually used with non-DiSEqC capable LNBs to switch the
polarzation (horizontal/vertical). When using DiSEqC epuipment this
voltage has to be switched consistently to the DiSEqC commands as
@@ -201,6 +207,8 @@ Currently not used.
DTV_PILOT
=========
+Used on DVB-S2.
+
Sets DVB-S2 pilot.
The acceptable values are defined by :c:type:`fe_pilot`.
@@ -211,7 +219,9 @@ The acceptable values are defined by :c:type:`fe_pilot`.
DTV_ROLLOFF
===========
-Sets DVB-S2 rolloff
+Used on DVB-S2.
+
+Sets DVB-S2 rolloff.
The acceptable values are defined by :c:type:`fe_rolloff`.
@@ -245,7 +255,7 @@ Currently not implemented.
DTV_DELIVERY_SYSTEM
===================
-Specifies the type of Delivery system.
+Specifies the type of the delivery system.
The acceptable values are defined by :c:type:`fe_delivery_system`.
@@ -255,6 +265,8 @@ The acceptable values are defined by :c:type:`fe_delivery_system`.
DTV_ISDBT_PARTIAL_RECEPTION
===========================
+Used only on ISDB.
+
If ``DTV_ISDBT_SOUND_BROADCASTING`` is '0' this bit-field represents
whether the channel is in partial reception mode or not.
@@ -273,6 +285,8 @@ Possible values: 0, 1, -1 (AUTO)
DTV_ISDBT_SOUND_BROADCASTING
============================
+Used only on ISDB.
+
This field represents whether the other DTV_ISDBT_*-parameters are
referring to an ISDB-T and an ISDB-Tsb channel. (See also
``DTV_ISDBT_PARTIAL_RECEPTION``).
@@ -285,6 +299,8 @@ Possible values: 0, 1, -1 (AUTO)
DTV_ISDBT_SB_SUBCHANNEL_ID
==========================
+Used only on ISDB.
+
This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
(Note of the author: This might not be the correct description of the
@@ -320,6 +336,8 @@ Possible values: 0 .. 41, -1 (AUTO)
DTV_ISDBT_SB_SEGMENT_IDX
========================
+Used only on ISDB.
+
This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
``DTV_ISDBT_SB_SEGMENT_IDX`` gives the index of the segment to be
@@ -336,6 +354,8 @@ Note: This value cannot be determined by an automatic channel search.
DTV_ISDBT_SB_SEGMENT_COUNT
==========================
+Used only on ISDB.
+
This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
``DTV_ISDBT_SB_SEGMENT_COUNT`` gives the total count of connected
@@ -351,6 +371,8 @@ Note: This value cannot be determined by an automatic channel search.
DTV-ISDBT-LAYER[A-C] parameters
===============================
+Used only on ISDB.
+
ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
ISDB-T hierarchical layers can be decoded simultaneously. For that
reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders.
@@ -367,6 +389,8 @@ There are 3 parameter sets, for Layers A, B and C.
DTV_ISDBT_LAYER_ENABLED
-----------------------
+Used only on ISDB.
+
Hierarchical reception in ISDB-T is achieved by enabling or disabling
layers in the decoding process. Setting all bits of
``DTV_ISDBT_LAYER_ENABLED`` to '1' forces all layers (if applicable) to
@@ -397,6 +421,8 @@ Only the values of the first 3 bits are used. Other bits will be silently ignore
DTV_ISDBT_LAYER[A-C]_FEC
------------------------
+Used only on ISDB.
+
The Forward Error Correction mechanism used by a given ISDB Layer, as
defined by :c:type:`fe_code_rate`.
@@ -410,6 +436,8 @@ Possible values are: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``,
DTV_ISDBT_LAYER[A-C]_MODULATION
-------------------------------
+Used only on ISDB.
+
The modulation used by a given ISDB Layer, as defined by
:c:type:`fe_modulation`.
@@ -428,6 +456,8 @@ Possible values are: ``QAM_AUTO``, ``QPSK``, ``QAM_16``, ``QAM_64``, ``DQPSK``
DTV_ISDBT_LAYER[A-C]_SEGMENT_COUNT
----------------------------------
+Used only on ISDB.
+
Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)
Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and
@@ -517,6 +547,8 @@ Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and
DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING
--------------------------------------
+Used only on ISDB.
+
Valid values: 0, 1, 2, 4, -1 (AUTO)
when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.
@@ -590,6 +622,8 @@ TMCC-structure, as shown in the table below.
DTV_ATSCMH_FIC_VER
------------------
+Used only on ATSC-MH.
+
Version number of the FIC (Fast Information Channel) signaling data.
FIC is used for relaying information to allow rapid service acquisition
@@ -603,6 +637,8 @@ Possible values: 0, 1, 2, 3, ..., 30, 31
DTV_ATSCMH_PARADE_ID
--------------------
+Used only on ATSC-MH.
+
Parade identification number
A parade is a collection of up to eight MH groups, conveying one or two
@@ -616,6 +652,8 @@ Possible values: 0, 1, 2, 3, ..., 126, 127
DTV_ATSCMH_NOG
--------------
+Used only on ATSC-MH.
+
Number of MH groups per MH subframe for a designated parade.
Possible values: 1, 2, 3, 4, 5, 6, 7, 8
@@ -626,6 +664,8 @@ Possible values: 1, 2, 3, 4, 5, 6, 7, 8
DTV_ATSCMH_TNOG
---------------
+Used only on ATSC-MH.
+
Total number of MH groups including all MH groups belonging to all MH
parades in one MH subframe.
@@ -637,6 +677,8 @@ Possible values: 0, 1, 2, 3, ..., 30, 31
DTV_ATSCMH_SGN
--------------
+Used only on ATSC-MH.
+
Start group number.
Possible values: 0, 1, 2, 3, ..., 14, 15
@@ -647,6 +689,8 @@ Possible values: 0, 1, 2, 3, ..., 14, 15
DTV_ATSCMH_PRC
--------------
+Used only on ATSC-MH.
+
Parade repetition cycle.
Possible values: 1, 2, 3, 4, 5, 6, 7, 8
@@ -657,6 +701,8 @@ Possible values: 1, 2, 3, 4, 5, 6, 7, 8
DTV_ATSCMH_RS_FRAME_MODE
------------------------
+Used only on ATSC-MH.
+
Reed Solomon (RS) frame mode.
The acceptable values are defined by :c:type:`atscmh_rs_frame_mode`.
@@ -667,6 +713,8 @@ The acceptable values are defined by :c:type:`atscmh_rs_frame_mode`.
DTV_ATSCMH_RS_FRAME_ENSEMBLE
----------------------------
+Used only on ATSC-MH.
+
Reed Solomon(RS) frame ensemble.
The acceptable values are defined by :c:type:`atscmh_rs_frame_ensemble`.
@@ -677,6 +725,8 @@ The acceptable values are defined by :c:type:`atscmh_rs_frame_ensemble`.
DTV_ATSCMH_RS_CODE_MODE_PRI
---------------------------
+Used only on ATSC-MH.
+
Reed Solomon (RS) code mode (primary).
The acceptable values are defined by :c:type:`atscmh_rs_code_mode`.
@@ -687,6 +737,8 @@ The acceptable values are defined by :c:type:`atscmh_rs_code_mode`.
DTV_ATSCMH_RS_CODE_MODE_SEC
---------------------------
+Used only on ATSC-MH.
+
Reed Solomon (RS) code mode (secondary).
The acceptable values are defined by :c:type:`atscmh_rs_code_mode`.
@@ -697,6 +749,8 @@ The acceptable values are defined by :c:type:`atscmh_rs_code_mode`.
DTV_ATSCMH_SCCC_BLOCK_MODE
--------------------------
+Used only on ATSC-MH.
+
Series Concatenated Convolutional Code Block Mode.
The acceptable values are defined by :c:type:`atscmh_sccc_block_mode`.
@@ -707,6 +761,8 @@ The acceptable values are defined by :c:type:`atscmh_sccc_block_mode`.
DTV_ATSCMH_SCCC_CODE_MODE_A
---------------------------
+Used only on ATSC-MH.
+
Series Concatenated Convolutional Code Rate.
The acceptable values are defined by :c:type:`atscmh_sccc_code_mode`.
@@ -716,6 +772,8 @@ The acceptable values are defined by :c:type:`atscmh_sccc_code_mode`.
DTV_ATSCMH_SCCC_CODE_MODE_B
---------------------------
+Used only on ATSC-MH.
+
Series Concatenated Convolutional Code Rate.
Possible values are the same as documented on enum
@@ -727,6 +785,8 @@ Possible values are the same as documented on enum
DTV_ATSCMH_SCCC_CODE_MODE_C
---------------------------
+Used only on ATSC-MH.
+
Series Concatenated Convolutional Code Rate.
Possible values are the same as documented on enum
@@ -738,6 +798,8 @@ Possible values are the same as documented on enum
DTV_ATSCMH_SCCC_CODE_MODE_D
---------------------------
+Used only on ATSC-MH.
+
Series Concatenated Convolutional Code Rate.
Possible values are the same as documented on enum
@@ -797,9 +859,11 @@ The acceptable values are defined by :c:type:`fe_guard_interval`.
DTV_TRANSMISSION_MODE
=====================
+
+Used only on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB.
+
Specifies the FFT size (with corresponds to the approximate number of
-carriers) used by the standard. This is used only on OFTM-based standards,
-e. g. DVB-T/T2, ISDB-T, DTMB.
+carriers) used by the standard.
The acceptable values are defined by :c:type:`fe_transmit_mode`.
@@ -832,6 +896,8 @@ The acceptable values are defined by :c:type:`fe_transmit_mode`.
DTV_HIERARCHY
=============
+Used only on DVB-T and DVB-T2.
+
Frontend hierarchy.
The acceptable values are defined by :c:type:`fe_hierarchy`.
@@ -842,6 +908,8 @@ The acceptable values are defined by :c:type:`fe_hierarchy`.
DTV_STREAM_ID
=============
+Used on DVB-S2, DVB-T2 and ISDB-S.
+
DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on
a single transport stream. This property enables the DVB driver to
handle substream filtering, when supported by the hardware. By default,
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 11/27] media: fe_property_parameters.rst: better document bandwidth
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (9 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 10/27] media: fe_property_parameters.rst: better define properties usage Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 12/27] media: dmx.h: get rid of unused DMX_KERNEL_CLIENT Mauro Carvalho Chehab
` (17 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Use a table to document the supported bandwidths. That makes
it clearer to readers.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../media/uapi/dvb/fe_property_parameters.rst | 44 +++++++++++++---------
1 file changed, 26 insertions(+), 18 deletions(-)
diff --git a/Documentation/media/uapi/dvb/fe_property_parameters.rst b/Documentation/media/uapi/dvb/fe_property_parameters.rst
index e085e84fef38..49470f7dda02 100644
--- a/Documentation/media/uapi/dvb/fe_property_parameters.rst
+++ b/Documentation/media/uapi/dvb/fe_property_parameters.rst
@@ -116,30 +116,38 @@ Should be set only for terrestrial delivery systems.
Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``,
``8000000``, ``10000000``.
+======================= =======================================================
+Terrestrial Standard Possible values for bandwidth
+======================= =======================================================
+ATSC (version 1) No need to set. It is always 6MHz.
+DMTB No need to set. It is always 8MHz.
+DVB-T 6MHz, 7MHz and 8MHz.
+DVB-T2 1.172 MHz, 5MHz, 6MHz, 7MHz, 8MHz and 10MHz
+ISDB-T 5MHz, 6MHz, 7MHz and 8MHz, although most places
+ use 6MHz.
+======================= =======================================================
+
+
.. note::
- #. DVB-T supports 6, 7 and 8MHz.
- #. DVB-T2 supports 1.172, 5, 6, 7, 8 and 10MHz.
+ #. For ISDB-Tsb, the bandwidth can vary depending on the number of
+ connected segments.
- #. ISDB-T supports 5MHz, 6MHz, 7MHz and 8MHz, although most
- places use 6MHz.
-
- #. On DVB-C and DVB-S/S2, the bandwidth depends on the symbol rate.
- So, the Kernel will silently ignore setting :ref:`DTV-BANDWIDTH-HZ`.
-
- #. For DVB-C and DVB-S/S2, the Kernel will return an estimation of the
- bandwidth, calculated from :ref:`DTV-SYMBOL-RATE` and from
- the rolloff, with is fixed for DVB-C and DVB-S.
-
- #. For DVB-S2, the bandwidth estimation will use :ref:`DTV-ROLLOFF`.
-
- #. For ISDB-Tsb, it can vary depending on the number of connected
- segments.
-
- #. Bandwidth in ISDB-Tsb can be easily derived from other parameters
+ It can be easily derived from other parameters
(DTV_ISDBT_SB_SEGMENT_IDX, DTV_ISDBT_SB_SEGMENT_COUNT).
+ #. On Satellite and Cable delivery systems, the bandwidth depends on
+ the symbol rate. So, the Kernel will silently ignore any setting
+ :ref:`DTV-BANDWIDTH-HZ`. I will however fill it back with a
+ bandwidth estimation.
+
+ Such bandwidth estimation takes into account the symbol rate set with
+ :ref:`DTV-SYMBOL-RATE`, and the rolloff factor, with is fixed for
+ DVB-C and DVB-S.
+
+ For DVB-S2, the rolloff should also be set via :ref:`DTV-ROLLOFF`.
+
.. _DTV-INVERSION:
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 12/27] media: dmx.h: get rid of unused DMX_KERNEL_CLIENT
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (10 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 11/27] media: fe_property_parameters.rst: better document bandwidth Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 13/27] media: dmx.h: get rid of DMX_GET_CAPS Mauro Carvalho Chehab
` (16 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
There's a flag defined for Digital TV demux that is not used
anywhere, called DMX_KERNEL_CLIENT. Get rid of it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/dmx.h.rst.exceptions | 1 -
Documentation/media/uapi/dvb/dmx_types.rst | 1 -
include/uapi/linux/dvb/dmx.h | 1 -
3 files changed, 3 deletions(-)
diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions
index 2fdb458564ba..933ca5a61ce1 100644
--- a/Documentation/media/dmx.h.rst.exceptions
+++ b/Documentation/media/dmx.h.rst.exceptions
@@ -56,7 +56,6 @@ replace symbol DMX_SOURCE_DVR3 :c:type:`dmx_source`
replace define DMX_CHECK_CRC :c:type:`dmx_sct_filter_params`
replace define DMX_ONESHOT :c:type:`dmx_sct_filter_params`
replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params`
-replace define DMX_KERNEL_CLIENT :c:type:`dmx_sct_filter_params`
# some typedefs should point to struct/enums
replace typedef dmx_caps_t :c:type:`dmx_caps`
diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst
index 80dd659860d7..0f0113205c94 100644
--- a/Documentation/media/uapi/dvb/dmx_types.rst
+++ b/Documentation/media/uapi/dvb/dmx_types.rst
@@ -147,7 +147,6 @@ struct dmx_sct_filter_params
#define DMX_CHECK_CRC 1
#define DMX_ONESHOT 2
#define DMX_IMMEDIATE_START 4
- #define DMX_KERNEL_CLIENT 0x8000
};
diff --git a/include/uapi/linux/dvb/dmx.h b/include/uapi/linux/dvb/dmx.h
index 1bc4d6fb0f01..1702f923d425 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -103,7 +103,6 @@ struct dmx_sct_filter_params
#define DMX_CHECK_CRC 1
#define DMX_ONESHOT 2
#define DMX_IMMEDIATE_START 4
-#define DMX_KERNEL_CLIENT 0x8000
};
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 13/27] media: dmx.h: get rid of DMX_GET_CAPS
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (11 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 12/27] media: dmx.h: get rid of unused DMX_KERNEL_CLIENT Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 14/27] media: dmx.h: get rid of DMX_SET_SOURCE Mauro Carvalho Chehab
` (15 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
There's no driver currently using it; it is also not
documented about what it would be supposed to do.
So, get rid of it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/dmx.h.rst.exceptions | 1 -
Documentation/media/uapi/dvb/dmx-get-caps.rst | 41 ---------------------------
Documentation/media/uapi/dvb/dmx_fcalls.rst | 1 -
Documentation/media/uapi/dvb/dmx_types.rst | 12 --------
include/uapi/linux/dvb/dmx.h | 7 -----
5 files changed, 62 deletions(-)
delete mode 100644 Documentation/media/uapi/dvb/dmx-get-caps.rst
diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions
index 933ca5a61ce1..5572d2dc9d0e 100644
--- a/Documentation/media/dmx.h.rst.exceptions
+++ b/Documentation/media/dmx.h.rst.exceptions
@@ -58,7 +58,6 @@ replace define DMX_ONESHOT :c:type:`dmx_sct_filter_params`
replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params`
# some typedefs should point to struct/enums
-replace typedef dmx_caps_t :c:type:`dmx_caps`
replace typedef dmx_filter_t :c:type:`dmx_filter`
replace typedef dmx_pes_type_t :c:type:`dmx_pes_type`
replace typedef dmx_input_t :c:type:`dmx_input`
diff --git a/Documentation/media/uapi/dvb/dmx-get-caps.rst b/Documentation/media/uapi/dvb/dmx-get-caps.rst
deleted file mode 100644
index 145fb520d779..000000000000
--- a/Documentation/media/uapi/dvb/dmx-get-caps.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_GET_CAPS:
-
-============
-DMX_GET_CAPS
-============
-
-Name
-----
-
-DMX_GET_CAPS
-
-
-Synopsis
---------
-
-.. c:function:: int ioctl(fd, DMX_GET_CAPS, struct dmx_caps *caps)
- :name: DMX_GET_CAPS
-
-Arguments
----------
-
-``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
-
-``caps``
- Pointer to struct :c:type:`dmx_caps`
-
-
-Description
------------
-
-.. note:: This ioctl is undocumented. Documentation is welcome.
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst
index 77a1554d9834..49e013d4540f 100644
--- a/Documentation/media/uapi/dvb/dmx_fcalls.rst
+++ b/Documentation/media/uapi/dvb/dmx_fcalls.rst
@@ -21,7 +21,6 @@ Demux Function Calls
dmx-get-event
dmx-get-stc
dmx-get-pes-pids
- dmx-get-caps
dmx-set-source
dmx-add-pid
dmx-remove-pid
diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst
index 0f0113205c94..9e907b85cf16 100644
--- a/Documentation/media/uapi/dvb/dmx_types.rst
+++ b/Documentation/media/uapi/dvb/dmx_types.rst
@@ -199,18 +199,6 @@ struct dmx_stc
};
-struct dmx_caps
-===============
-
-.. c:type:: dmx_caps
-
-.. code-block:: c
-
- typedef struct dmx_caps {
- __u32 caps;
- int num_decoders;
- } dmx_caps_t;
-
enum dmx_source
===============
diff --git a/include/uapi/linux/dvb/dmx.h b/include/uapi/linux/dvb/dmx.h
index 1702f923d425..db8bd00c93de 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -115,11 +115,6 @@ struct dmx_pes_filter_params
__u32 flags;
};
-struct dmx_caps {
- __u32 caps;
- int num_decoders;
-};
-
enum dmx_source {
DMX_SOURCE_FRONT0 = 0,
DMX_SOURCE_FRONT1,
@@ -143,7 +138,6 @@ struct dmx_stc {
#define DMX_SET_PES_FILTER _IOW('o', 44, struct dmx_pes_filter_params)
#define DMX_SET_BUFFER_SIZE _IO('o', 45)
#define DMX_GET_PES_PIDS _IOR('o', 47, __u16[5])
-#define DMX_GET_CAPS _IOR('o', 48, struct dmx_caps)
#define DMX_SET_SOURCE _IOW('o', 49, enum dmx_source)
#define DMX_GET_STC _IOWR('o', 50, struct dmx_stc)
#define DMX_ADD_PID _IOW('o', 51, __u16)
@@ -156,7 +150,6 @@ typedef enum dmx_output dmx_output_t;
typedef enum dmx_input dmx_input_t;
typedef enum dmx_ts_pes dmx_pes_type_t;
typedef struct dmx_filter dmx_filter_t;
-typedef struct dmx_caps dmx_caps_t;
typedef enum dmx_source dmx_source_t;
#endif
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 14/27] media: dmx.h: get rid of DMX_SET_SOURCE
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (12 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 13/27] media: dmx.h: get rid of DMX_GET_CAPS Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 15/27] media: dmx.h: get rid of GET_DMX_EVENT Mauro Carvalho Chehab
` (14 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
No driver uses this ioctl, nor it is documented anywhere.
So, get rid of it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/dmx.h.rst.exceptions | 13 --------
Documentation/media/uapi/dvb/dmx-set-source.rst | 44 -------------------------
Documentation/media/uapi/dvb/dmx_fcalls.rst | 1 -
Documentation/media/uapi/dvb/dmx_types.rst | 20 -----------
include/uapi/linux/dvb/dmx.h | 12 -------
5 files changed, 90 deletions(-)
delete mode 100644 Documentation/media/uapi/dvb/dmx-set-source.rst
diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions
index 5572d2dc9d0e..d2dac35bb84b 100644
--- a/Documentation/media/dmx.h.rst.exceptions
+++ b/Documentation/media/dmx.h.rst.exceptions
@@ -40,18 +40,6 @@ replace enum dmx_input :c:type:`dmx_input`
replace symbol DMX_IN_FRONTEND :c:type:`dmx_input`
replace symbol DMX_IN_DVR :c:type:`dmx_input`
-# dmx_source_t symbols
-replace enum dmx_source :c:type:`dmx_source`
-replace symbol DMX_SOURCE_FRONT0 :c:type:`dmx_source`
-replace symbol DMX_SOURCE_FRONT1 :c:type:`dmx_source`
-replace symbol DMX_SOURCE_FRONT2 :c:type:`dmx_source`
-replace symbol DMX_SOURCE_FRONT3 :c:type:`dmx_source`
-replace symbol DMX_SOURCE_DVR0 :c:type:`dmx_source`
-replace symbol DMX_SOURCE_DVR1 :c:type:`dmx_source`
-replace symbol DMX_SOURCE_DVR2 :c:type:`dmx_source`
-replace symbol DMX_SOURCE_DVR3 :c:type:`dmx_source`
-
-
# Flags for struct dmx_sct_filter_params
replace define DMX_CHECK_CRC :c:type:`dmx_sct_filter_params`
replace define DMX_ONESHOT :c:type:`dmx_sct_filter_params`
@@ -61,4 +49,3 @@ replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params`
replace typedef dmx_filter_t :c:type:`dmx_filter`
replace typedef dmx_pes_type_t :c:type:`dmx_pes_type`
replace typedef dmx_input_t :c:type:`dmx_input`
-replace typedef dmx_source_t :c:type:`dmx_source`
diff --git a/Documentation/media/uapi/dvb/dmx-set-source.rst b/Documentation/media/uapi/dvb/dmx-set-source.rst
deleted file mode 100644
index ac7f77b25e06..000000000000
--- a/Documentation/media/uapi/dvb/dmx-set-source.rst
+++ /dev/null
@@ -1,44 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_SET_SOURCE:
-
-==============
-DMX_SET_SOURCE
-==============
-
-Name
-----
-
-DMX_SET_SOURCE
-
-
-Synopsis
---------
-
-.. c:function:: int ioctl(fd, DMX_SET_SOURCE, struct dmx_source *src)
- :name: DMX_SET_SOURCE
-
-
-Arguments
----------
-
-
-``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
-
-``src``
- Undocumented.
-
-
-Description
------------
-
-.. note:: This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst
index 49e013d4540f..be98d60877f2 100644
--- a/Documentation/media/uapi/dvb/dmx_fcalls.rst
+++ b/Documentation/media/uapi/dvb/dmx_fcalls.rst
@@ -21,6 +21,5 @@ Demux Function Calls
dmx-get-event
dmx-get-stc
dmx-get-pes-pids
- dmx-set-source
dmx-add-pid
dmx-remove-pid
diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst
index 9e907b85cf16..a205c02ccdc1 100644
--- a/Documentation/media/uapi/dvb/dmx_types.rst
+++ b/Documentation/media/uapi/dvb/dmx_types.rst
@@ -197,23 +197,3 @@ struct dmx_stc
unsigned int base; /* output: divisor for stc to get 90 kHz clock */
__u64 stc; /* output: stc in 'base'*90 kHz units */
};
-
-
-
-enum dmx_source
-===============
-
-.. c:type:: dmx_source
-
-.. code-block:: c
-
- typedef enum dmx_source {
- DMX_SOURCE_FRONT0 = 0,
- DMX_SOURCE_FRONT1,
- DMX_SOURCE_FRONT2,
- DMX_SOURCE_FRONT3,
- DMX_SOURCE_DVR0 = 16,
- DMX_SOURCE_DVR1,
- DMX_SOURCE_DVR2,
- DMX_SOURCE_DVR3
- } dmx_source_t;
diff --git a/include/uapi/linux/dvb/dmx.h b/include/uapi/linux/dvb/dmx.h
index db8bd00c93de..08dc17060321 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -115,16 +115,6 @@ struct dmx_pes_filter_params
__u32 flags;
};
-enum dmx_source {
- DMX_SOURCE_FRONT0 = 0,
- DMX_SOURCE_FRONT1,
- DMX_SOURCE_FRONT2,
- DMX_SOURCE_FRONT3,
- DMX_SOURCE_DVR0 = 16,
- DMX_SOURCE_DVR1,
- DMX_SOURCE_DVR2,
- DMX_SOURCE_DVR3
-};
struct dmx_stc {
unsigned int num; /* input : which STC? 0..N */
@@ -138,7 +128,6 @@ struct dmx_stc {
#define DMX_SET_PES_FILTER _IOW('o', 44, struct dmx_pes_filter_params)
#define DMX_SET_BUFFER_SIZE _IO('o', 45)
#define DMX_GET_PES_PIDS _IOR('o', 47, __u16[5])
-#define DMX_SET_SOURCE _IOW('o', 49, enum dmx_source)
#define DMX_GET_STC _IOWR('o', 50, struct dmx_stc)
#define DMX_ADD_PID _IOW('o', 51, __u16)
#define DMX_REMOVE_PID _IOW('o', 52, __u16)
@@ -150,7 +139,6 @@ typedef enum dmx_output dmx_output_t;
typedef enum dmx_input dmx_input_t;
typedef enum dmx_ts_pes dmx_pes_type_t;
typedef struct dmx_filter dmx_filter_t;
-typedef enum dmx_source dmx_source_t;
#endif
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 15/27] media: dmx.h: get rid of GET_DMX_EVENT
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (13 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 14/27] media: dmx.h: get rid of DMX_SET_SOURCE Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 16/27] media: dmx.h: add kernel-doc markups and use it at Documentation/ Mauro Carvalho Chehab
` (13 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
This seems to be a pure fictional API :-)
It only exists at the DVB book, with no code implemeting it.
So, just get rid of it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/dmx-get-event.rst | 60 --------------------------
Documentation/media/uapi/dvb/dmx_fcalls.rst | 1 -
Documentation/media/uapi/dvb/dmx_types.rst | 19 --------
3 files changed, 80 deletions(-)
delete mode 100644 Documentation/media/uapi/dvb/dmx-get-event.rst
diff --git a/Documentation/media/uapi/dvb/dmx-get-event.rst b/Documentation/media/uapi/dvb/dmx-get-event.rst
deleted file mode 100644
index 8be626c29158..000000000000
--- a/Documentation/media/uapi/dvb/dmx-get-event.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_GET_EVENT:
-
-=============
-DMX_GET_EVENT
-=============
-
-Name
-----
-
-DMX_GET_EVENT
-
-
-Synopsis
---------
-
-.. c:function:: int ioctl( int fd, DMX_GET_EVENT, struct dmx_event *ev)
- :name: DMX_GET_EVENT
-
-
-Arguments
----------
-
-``fd``
- File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
-
-``ev``
- Pointer to the location where the event is to be stored.
-
-
-Description
------------
-
-This ioctl call returns an event if available. If an event is not
-available, the behavior depends on whether the device is in blocking or
-non-blocking mode. In the latter case, the call fails immediately with
-errno set to ``EWOULDBLOCK``. In the former case, the call blocks until an
-event becomes available.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EWOULDBLOCK``
-
- - There is no event pending, and the device is in non-blocking mode.
diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst
index be98d60877f2..a17289143220 100644
--- a/Documentation/media/uapi/dvb/dmx_fcalls.rst
+++ b/Documentation/media/uapi/dvb/dmx_fcalls.rst
@@ -18,7 +18,6 @@ Demux Function Calls
dmx-set-filter
dmx-set-pes-filter
dmx-set-buffer-size
- dmx-get-event
dmx-get-stc
dmx-get-pes-pids
dmx-add-pid
diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst
index a205c02ccdc1..171205ed86a4 100644
--- a/Documentation/media/uapi/dvb/dmx_types.rst
+++ b/Documentation/media/uapi/dvb/dmx_types.rst
@@ -166,25 +166,6 @@ struct dmx_pes_filter_params
__u32 flags;
};
-
-struct dmx_event
-================
-
-.. c:type:: dmx_event
-
-.. code-block:: c
-
- struct dmx_event
- {
- dmx_event_t event;
- time_t timeStamp;
- union
- {
- dmx_scrambling_status_t scrambling;
- } u;
- };
-
-
struct dmx_stc
==============
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 16/27] media: dmx.h: add kernel-doc markups and use it at Documentation/
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (14 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 15/27] media: dmx.h: get rid of GET_DMX_EVENT Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 17/27] media: net.rst: Fix the level of a section of the net chapter Mauro Carvalho Chehab
` (12 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
The demux documentation is pretty poor nowadays: most of the
structs and enums aren't documented at all.
Add proper kernel-doc markups for them and use it.
Now, the demux API is fully documented :-)
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/dmx.h.rst.exceptions | 5 +
Documentation/media/uapi/dvb/dmx_types.rst | 173 +----------------------------
include/uapi/linux/dvb/dmx.h | 139 ++++++++++++++++++-----
3 files changed, 120 insertions(+), 197 deletions(-)
diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions
index d2dac35bb84b..629db384104a 100644
--- a/Documentation/media/dmx.h.rst.exceptions
+++ b/Documentation/media/dmx.h.rst.exceptions
@@ -49,3 +49,8 @@ replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params`
replace typedef dmx_filter_t :c:type:`dmx_filter`
replace typedef dmx_pes_type_t :c:type:`dmx_pes_type`
replace typedef dmx_input_t :c:type:`dmx_input`
+
+ignore symbol DMX_OUT_DECODER
+ignore symbol DMX_OUT_TAP
+ignore symbol DMX_OUT_TS_TAP
+ignore symbol DMX_OUT_TSDEMUX_TAP
diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst
index 171205ed86a4..2a023a4f516c 100644
--- a/Documentation/media/uapi/dvb/dmx_types.rst
+++ b/Documentation/media/uapi/dvb/dmx_types.rst
@@ -6,175 +6,4 @@
Demux Data Types
****************
-Output for the demux
-====================
-
-.. c:type:: dmx_output
-
-.. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
-
-.. flat-table:: enum dmx_output
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _DMX-OUT-DECODER:
-
- DMX_OUT_DECODER
-
- - Streaming directly to decoder.
-
- - .. row 3
-
- - .. _DMX-OUT-TAP:
-
- DMX_OUT_TAP
-
- - Output going to a memory buffer (to be retrieved via the read
- command). Delivers the stream output to the demux device on which
- the ioctl is called.
-
- - .. row 4
-
- - .. _DMX-OUT-TS-TAP:
-
- DMX_OUT_TS_TAP
-
- - Output multiplexed into a new TS (to be retrieved by reading from
- the logical DVR device). Routes output to the logical DVR device
- ``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from
- all filters for which ``DMX_OUT_TS_TAP`` was specified.
-
- - .. row 5
-
- - .. _DMX-OUT-TSDEMUX-TAP:
-
- DMX_OUT_TSDEMUX_TAP
-
- - Like :ref:`DMX_OUT_TS_TAP <DMX-OUT-TS-TAP>` but retrieved
- from the DMX device.
-
-
-dmx_input_t
-===========
-
-.. c:type:: dmx_input
-
-.. code-block:: c
-
- typedef enum
- {
- DMX_IN_FRONTEND, /* Input from a front-end device. */
- DMX_IN_DVR /* Input from the logical DVR device. */
- } dmx_input_t;
-
-
-dmx_pes_type_t
-==============
-
-.. c:type:: dmx_pes_type
-
-
-.. code-block:: c
-
- typedef enum
- {
- DMX_PES_AUDIO0,
- DMX_PES_VIDEO0,
- DMX_PES_TELETEXT0,
- DMX_PES_SUBTITLE0,
- DMX_PES_PCR0,
-
- DMX_PES_AUDIO1,
- DMX_PES_VIDEO1,
- DMX_PES_TELETEXT1,
- DMX_PES_SUBTITLE1,
- DMX_PES_PCR1,
-
- DMX_PES_AUDIO2,
- DMX_PES_VIDEO2,
- DMX_PES_TELETEXT2,
- DMX_PES_SUBTITLE2,
- DMX_PES_PCR2,
-
- DMX_PES_AUDIO3,
- DMX_PES_VIDEO3,
- DMX_PES_TELETEXT3,
- DMX_PES_SUBTITLE3,
- DMX_PES_PCR3,
-
- DMX_PES_OTHER
- } dmx_pes_type_t;
-
-
-struct dmx_filter
-=================
-
-.. c:type:: dmx_filter
-
-.. code-block:: c
-
- typedef struct dmx_filter
- {
- __u8 filter[DMX_FILTER_SIZE];
- __u8 mask[DMX_FILTER_SIZE];
- __u8 mode[DMX_FILTER_SIZE];
- } dmx_filter_t;
-
-
-.. c:type:: dmx_sct_filter_params
-
-struct dmx_sct_filter_params
-============================
-
-
-.. code-block:: c
-
- struct dmx_sct_filter_params
- {
- __u16 pid;
- dmx_filter_t filter;
- __u32 timeout;
- __u32 flags;
- #define DMX_CHECK_CRC 1
- #define DMX_ONESHOT 2
- #define DMX_IMMEDIATE_START 4
- };
-
-
-struct dmx_pes_filter_params
-============================
-
-.. c:type:: dmx_pes_filter_params
-
-.. code-block:: c
-
- struct dmx_pes_filter_params
- {
- __u16 pid;
- dmx_input_t input;
- dmx_output_t output;
- dmx_pes_type_t pes_type;
- __u32 flags;
- };
-
-struct dmx_stc
-==============
-
-.. c:type:: dmx_stc
-
-.. code-block:: c
-
- struct dmx_stc {
- unsigned int num; /* input : which STC? 0..N */
- unsigned int base; /* output: divisor for stc to get 90 kHz clock */
- __u64 stc; /* output: stc in 'base'*90 kHz units */
- };
+.. kernel-doc:: include/uapi/linux/dvb/dmx.h
diff --git a/include/uapi/linux/dvb/dmx.h b/include/uapi/linux/dvb/dmx.h
index 08dc17060321..867177b62d68 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -32,26 +32,74 @@
#define DMX_FILTER_SIZE 16
-enum dmx_output
-{
- DMX_OUT_DECODER, /* Streaming directly to decoder. */
- DMX_OUT_TAP, /* Output going to a memory buffer */
- /* (to be retrieved via the read command).*/
- DMX_OUT_TS_TAP, /* Output multiplexed into a new TS */
- /* (to be retrieved by reading from the */
- /* logical DVR device). */
- DMX_OUT_TSDEMUX_TAP /* Like TS_TAP but retrieved from the DMX device */
+/**
+ * enum dmx_output - Output for the demux.
+ *
+ * @DMX_OUT_DECODER:
+ * Streaming directly to decoder.
+ * @DMX_OUT_TAP:
+ * Output going to a memory buffer (to be retrieved via the read command).
+ * Delivers the stream output to the demux device on which the ioctl
+ * is called.
+ * @DMX_OUT_TS_TAP:
+ * Output multiplexed into a new TS (to be retrieved by reading from the
+ * logical DVR device). Routes output to the logical DVR device
+ * ``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from all
+ * filters for which @DMX_OUT_TS_TAP was specified.
+ * @DMX_OUT_TSDEMUX_TAP:
+ * Like @DMX_OUT_TS_TAP but retrieved from the DMX device.
+ */
+enum dmx_output {
+ DMX_OUT_DECODER,
+ DMX_OUT_TAP,
+ DMX_OUT_TS_TAP,
+ DMX_OUT_TSDEMUX_TAP
};
-enum dmx_input
-{
- DMX_IN_FRONTEND, /* Input from a front-end device. */
- DMX_IN_DVR /* Input from the logical DVR device. */
+
+/**
+ * enum dmx_input - Input from the demux.
+ *
+ * @DMX_IN_FRONTEND: Input from a front-end device.
+ * @DMX_IN_DVR: Input from the logical DVR device.
+ */
+enum dmx_input {
+ DMX_IN_FRONTEND,
+ DMX_IN_DVR
};
+/**
+ * enum dmx_ts_pes - type of the PES filter.
+ *
+ * @DMX_PES_AUDIO0: first audio PID. Also referred as @DMX_PES_AUDIO.
+ * @DMX_PES_VIDEO0: first video PID. Also referred as @DMX_PES_VIDEO.
+ * @DMX_PES_TELETEXT0: first teletext PID. Also referred as @DMX_PES_TELETEXT.
+ * @DMX_PES_SUBTITLE0: first subtitle PID. Also referred as @DMX_PES_SUBTITLE.
+ * @DMX_PES_PCR0: first Program Clock Reference PID.
+ * Also refered as @DMX_PES_PCR.
+ *
+ * @DMX_PES_AUDIO1: second audio PID.
+ * @DMX_PES_VIDEO1: second video PID.
+ * @DMX_PES_TELETEXT1: second teletext PID.
+ * @DMX_PES_SUBTITLE1: second subtitle PID.
+ * @DMX_PES_PCR1: second Program Clock Reference PID.
+ *
+ * @DMX_PES_AUDIO2: third audio PID.
+ * @DMX_PES_VIDEO2: third video PID.
+ * @DMX_PES_TELETEXT2: third teletext PID.
+ * @DMX_PES_SUBTITLE2: third subtitle PID.
+ * @DMX_PES_PCR2: third Program Clock Reference PID.
+ *
+ * @DMX_PES_AUDIO3: fourth audio PID.
+ * @DMX_PES_VIDEO3: fourth video PID.
+ * @DMX_PES_TELETEXT3: fourth teletext PID.
+ * @DMX_PES_SUBTITLE3: fourth subtitle PID.
+ * @DMX_PES_PCR3: fourth Program Clock Reference PID.
+ *
+ * @DMX_PES_OTHER: any other PID.
+ */
-enum dmx_ts_pes
-{
+enum dmx_ts_pes {
DMX_PES_AUDIO0,
DMX_PES_VIDEO0,
DMX_PES_TELETEXT0,
@@ -86,16 +134,42 @@ enum dmx_ts_pes
#define DMX_PES_PCR DMX_PES_PCR0
-struct dmx_filter
-{
+
+/**
+ * struct dmx_filter - Specifies a section header filter.
+ *
+ * @filter: bit array with bits to be matched at the section header.
+ * @mask: bits that are valid at the filter bit array.
+ * @mode: mode of match: if bit is zero, it will match if equal (positive
+ * match); if bit is one, it will match if the bit is negated.
+ *
+ * Note: All arrays in this struct have a size of DMX_FILTER_SIZE (16 bytes).
+ */
+struct dmx_filter {
__u8 filter[DMX_FILTER_SIZE];
__u8 mask[DMX_FILTER_SIZE];
__u8 mode[DMX_FILTER_SIZE];
};
-
-struct dmx_sct_filter_params
-{
+/**
+ * struct dmx_sct_filter_params - Specifies a section filter.
+ *
+ * @pid: PID to be filtered.
+ * @filter: section header filter, as defined by &struct dmx_filter.
+ * @timeout: maximum time to filter, in milliseconds.
+ * @flags: extra flags for the section filter.
+ *
+ * Carries the configuration for a MPEG-TS section filter.
+ *
+ * The @flags can be:
+ *
+ * - %DMX_CHECK_CRC - only deliver sections where the CRC check succeeded;
+ * - %DMX_ONESHOT - disable the section filter after one section
+ * has been delivered;
+ * - %DMX_IMMEDIATE_START - Start filter immediately without requiring a
+ * :ref:`DMX_START`.
+ */
+struct dmx_sct_filter_params {
__u16 pid;
struct dmx_filter filter;
__u32 timeout;
@@ -105,7 +179,16 @@ struct dmx_sct_filter_params
#define DMX_IMMEDIATE_START 4
};
-
+/**
+ * struct dmx_pes_filter_params - Specifies Packetized Elementary Stream (PES)
+ * filter parameters.
+ *
+ * @pid: PID to be filtered.
+ * @input: Demux input, as specified by &enum dmx_input.
+ * @output: Demux output, as specified by &enum dmx_output.
+ * @pes_type: Type of the pes filter, as specified by &enum dmx_pes_type.
+ * @flags: Demux PES flags.
+ */
struct dmx_pes_filter_params
{
__u16 pid;
@@ -115,11 +198,17 @@ struct dmx_pes_filter_params
__u32 flags;
};
-
+/**
+ * struct dmx_stc - Stores System Time Counter (STC) information.
+ *
+ * @num: input data: number of the STC, from 0 to N.
+ * @base: output: divisor for STC to get 90 kHz clock.
+ * @stc: output: stc in @base * 90 kHz units.
+ */
struct dmx_stc {
- unsigned int num; /* input : which STC? 0..N */
- unsigned int base; /* output: divisor for stc to get 90 kHz clock */
- __u64 stc; /* output: stc in 'base'*90 kHz units */
+ unsigned int num;
+ unsigned int base;
+ __u64 stc;
};
#define DMX_START _IO('o', 41)
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 17/27] media: net.rst: Fix the level of a section of the net chapter
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (15 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 16/27] media: dmx.h: add kernel-doc markups and use it at Documentation/ Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 18/27] media: ca.h: get rid of CA_SET_PID Mauro Carvalho Chehab
` (11 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Due to a mistake, the DVB net chapter was actually broken
into two different chapters. Fix it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/net.rst | 1 -
1 file changed, 1 deletion(-)
diff --git a/Documentation/media/uapi/dvb/net.rst b/Documentation/media/uapi/dvb/net.rst
index eca42dd53261..00ae5df0c321 100644
--- a/Documentation/media/uapi/dvb/net.rst
+++ b/Documentation/media/uapi/dvb/net.rst
@@ -28,7 +28,6 @@ header.
.. _net_fcalls:
-######################
DVB net Function Calls
######################
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 18/27] media: ca.h: get rid of CA_SET_PID
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (16 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 17/27] media: net.rst: Fix the level of a section of the net chapter Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 19/27] media: ca.h: document most CA data types Mauro Carvalho Chehab
` (10 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Andrew Morton, Masahiro Yamada, Markus Elfring
This ioctl seems to be some attempt to support a feature
at the bt8xx dst_ca driver. Yet, as said there, it
"needs more work". Right now, the code there is just
a boilerplate.
At the end of the day, no driver uses this ioctl, nor it is
documented anywhere (except for "needs more work").
So, get rid of it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/ca.h.rst.exceptions | 1 -
Documentation/media/dvb-drivers/ci.rst | 1 -
Documentation/media/uapi/dvb/ca-set-pid.rst | 60 ----------------------
Documentation/media/uapi/dvb/ca_data_types.rst | 14 -----
Documentation/media/uapi/dvb/ca_function_calls.rst | 1 -
drivers/media/pci/bt8xx/dst_ca.c | 16 ------
include/uapi/linux/dvb/ca.h | 7 ---
7 files changed, 100 deletions(-)
delete mode 100644 Documentation/media/uapi/dvb/ca-set-pid.rst
diff --git a/Documentation/media/ca.h.rst.exceptions b/Documentation/media/ca.h.rst.exceptions
index d7c9fed8c004..553559cc6ad7 100644
--- a/Documentation/media/ca.h.rst.exceptions
+++ b/Documentation/media/ca.h.rst.exceptions
@@ -16,7 +16,6 @@ replace define CA_NDS :c:type:`ca_descr_info`
replace define CA_DSS :c:type:`ca_descr_info`
# some typedefs should point to struct/enums
-replace typedef ca_pid_t :c:type:`ca_pid`
replace typedef ca_slot_info_t :c:type:`ca_slot_info`
replace typedef ca_descr_info_t :c:type:`ca_descr_info`
replace typedef ca_caps_t :c:type:`ca_caps`
diff --git a/Documentation/media/dvb-drivers/ci.rst b/Documentation/media/dvb-drivers/ci.rst
index 69b07e9d1816..87f3748c49b9 100644
--- a/Documentation/media/dvb-drivers/ci.rst
+++ b/Documentation/media/dvb-drivers/ci.rst
@@ -143,7 +143,6 @@ All these ioctls are also valid for the High level CI interface
#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:
diff --git a/Documentation/media/uapi/dvb/ca-set-pid.rst b/Documentation/media/uapi/dvb/ca-set-pid.rst
deleted file mode 100644
index 891c1c72ef24..000000000000
--- a/Documentation/media/uapi/dvb/ca-set-pid.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_SET_PID:
-
-==========
-CA_SET_PID
-==========
-
-Name
-----
-
-CA_SET_PID
-
-
-Synopsis
---------
-
-.. c:function:: int ioctl(fd, CA_SET_PID, struct ca_pid *pid)
- :name: CA_SET_PID
-
-
-Arguments
----------
-
-``fd``
- File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
-
-``pid``
- Pointer to struct :c:type:`ca_pid`.
-
-.. c:type:: ca_pid
-
-.. flat-table:: struct ca_pid
- :header-rows: 1
- :stub-columns: 0
-
- -
- - unsigned int
- - pid
- - Program ID
-
- -
- - int
- - index
- - PID index. Use -1 to disable.
-
-
-
-Description
------------
-
-.. note:: This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/dvb/ca_data_types.rst b/Documentation/media/uapi/dvb/ca_data_types.rst
index d9e27c77426c..555b5137936b 100644
--- a/Documentation/media/uapi/dvb/ca_data_types.rst
+++ b/Documentation/media/uapi/dvb/ca_data_types.rst
@@ -94,17 +94,3 @@ ca_descr_t
unsigned int parity;
unsigned char cw[8];
} ca_descr_t;
-
-
-.. c:type:: ca_pid
-
-ca-pid
-======
-
-
-.. code-block:: c
-
- typedef struct ca_pid {
- unsigned int pid;
- int index; /* -1 == disable*/
- } ca_pid_t;
diff --git a/Documentation/media/uapi/dvb/ca_function_calls.rst b/Documentation/media/uapi/dvb/ca_function_calls.rst
index c085a0ebbc05..87d697851e82 100644
--- a/Documentation/media/uapi/dvb/ca_function_calls.rst
+++ b/Documentation/media/uapi/dvb/ca_function_calls.rst
@@ -18,4 +18,3 @@ CA Function Calls
ca-get-msg
ca-send-msg
ca-set-descr
- ca-set-pid
diff --git a/drivers/media/pci/bt8xx/dst_ca.c b/drivers/media/pci/bt8xx/dst_ca.c
index 90f4263452d3..7db47d8bbe15 100644
--- a/drivers/media/pci/bt8xx/dst_ca.c
+++ b/drivers/media/pci/bt8xx/dst_ca.c
@@ -64,13 +64,6 @@ static int ca_set_slot_descr(void)
return -EOPNOTSUPP;
}
-/* Need some more work */
-static int ca_set_pid(void)
-{
- /* We could make this more graceful ? */
- return -EOPNOTSUPP;
-}
-
static void put_command_and_length(u8 *data, int command, int length)
{
data[0] = (command >> 16) & 0xff;
@@ -629,15 +622,6 @@ static long dst_ca_ioctl(struct file *file, unsigned int cmd, unsigned long ioct
}
dprintk(verbose, DST_CA_INFO, 1, " -->CA_SET_DESCR Success !");
break;
- case CA_SET_PID:
- dprintk(verbose, DST_CA_INFO, 1, " Setting PID");
- if ((ca_set_pid()) < 0) {
- dprintk(verbose, DST_CA_ERROR, 1, " -->CA_SET_PID Failed !");
- result = -1;
- goto free_mem_and_exit;
- }
- dprintk(verbose, DST_CA_INFO, 1, " -->CA_SET_PID Success !");
- break;
default:
result = -EOPNOTSUPP;
}
diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
index 00cf24587bea..859f6c0c4751 100644
--- a/include/uapi/linux/dvb/ca.h
+++ b/include/uapi/linux/dvb/ca.h
@@ -73,11 +73,6 @@ struct ca_descr {
unsigned char cw[8];
};
-struct ca_pid {
- unsigned int pid;
- int index; /* -1 == disable*/
-};
-
#define CA_RESET _IO('o', 128)
#define CA_GET_CAP _IOR('o', 129, struct ca_caps)
#define CA_GET_SLOT_INFO _IOR('o', 130, struct ca_slot_info)
@@ -85,7 +80,6 @@ struct ca_pid {
#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)
-#define CA_SET_PID _IOW('o', 135, struct ca_pid)
#if !defined (__KERNEL__)
@@ -95,7 +89,6 @@ 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;
-typedef struct ca_pid ca_pid_t;
#endif
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 19/27] media: ca.h: document most CA data types
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (17 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 18/27] media: ca.h: get rid of CA_SET_PID Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 20/27] media: dst_ca: return a proper error code from CA errors Mauro Carvalho Chehab
` (9 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
For most of the stuff there, documenting is easy, as the
header file contains information.
Yet, I was unable to document two data structs:
ca_msg and ca_descr
As those two structs are used by a few drivers, keep them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/ca_data_types.rst | 75 ++++---------------------
include/uapi/linux/dvb/ca.h | 78 ++++++++++++++++++++------
2 files changed, 70 insertions(+), 83 deletions(-)
diff --git a/Documentation/media/uapi/dvb/ca_data_types.rst b/Documentation/media/uapi/dvb/ca_data_types.rst
index 555b5137936b..aa57dd176825 100644
--- a/Documentation/media/uapi/dvb/ca_data_types.rst
+++ b/Documentation/media/uapi/dvb/ca_data_types.rst
@@ -6,91 +6,36 @@
CA Data Types
*************
+.. kernel-doc:: include/uapi/linux/dvb/ca.h
-.. c:type:: ca_slot_info
-
-ca_slot_info_t
-==============
-
-
-.. 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;
-
-
-.. c:type:: ca_descr_info
-
-ca_descr_info_t
-===============
-
-
-.. code-block:: c
-
- typedef struct ca_descr_info {
- unsigned int num; /* number of available descramblers (keys) */
- unsigned int type; /* type of supported scrambling system */
- #define CA_ECD 1
- #define CA_NDS 2
- #define CA_DSS 4
- } ca_descr_info_t;
-
-
-.. c:type:: ca_caps
-
-ca_caps_t
-=========
-
+.. c:type:: ca_msg
-.. code-block:: c
+Undocumented data types
+=======================
- 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_cap_t;
+.. note::
+ Those data types are undocumented. Documentation is welcome.
.. c:type:: ca_msg
-ca_msg_t
-========
-
-
.. code-block:: c
/* a message to/from a CI-CAM */
- typedef struct ca_msg {
+ struct ca_msg {
unsigned int index;
unsigned int type;
unsigned int length;
unsigned char msg[256];
- } ca_msg_t;
+ };
.. c:type:: ca_descr
-ca_descr_t
-==========
-
-
.. code-block:: c
- typedef struct ca_descr {
+ struct ca_descr {
unsigned int index;
unsigned int parity;
unsigned char cw[8];
- } ca_descr_t;
+ };
diff --git a/include/uapi/linux/dvb/ca.h b/include/uapi/linux/dvb/ca.h
index 859f6c0c4751..f66ed53f4dc7 100644
--- a/include/uapi/linux/dvb/ca.h
+++ b/include/uapi/linux/dvb/ca.h
@@ -24,39 +24,81 @@
#ifndef _DVBCA_H_
#define _DVBCA_H_
-/* slot interface types and info */
+/**
+ * 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.
+ */
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 */
+ 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
};
-/* descrambler types and info */
-
+/**
+ * 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; /* number of available descramblers (keys) */
- unsigned int type; /* type of supported scrambling system */
+ unsigned int num;
+ unsigned int type;
#define CA_ECD 1
#define CA_NDS 2
#define CA_DSS 4
};
+/**
+ * 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; /* 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 */
+ unsigned int slot_num;
+ unsigned int slot_type;
+ unsigned int descr_num;
+ unsigned int descr_type;
};
/* a message to/from a CI-CAM */
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 20/27] media: dst_ca: return a proper error code from CA errors
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (18 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 19/27] media: ca.h: document most CA data types Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 21/27] media: ca-reset.rst: add some description to this ioctl Mauro Carvalho Chehab
` (8 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Markus Elfring
Right now, on several places, the driver is returning a
"-1" error to userspace, instead of a proper error code.
Fix it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/media/pci/bt8xx/dst_ca.c | 41 +++++++++++++++++++++-------------------
1 file changed, 22 insertions(+), 19 deletions(-)
diff --git a/drivers/media/pci/bt8xx/dst_ca.c b/drivers/media/pci/bt8xx/dst_ca.c
index 7db47d8bbe15..5ebb86f22935 100644
--- a/drivers/media/pci/bt8xx/dst_ca.c
+++ b/drivers/media/pci/bt8xx/dst_ca.c
@@ -137,7 +137,7 @@ static int dst_put_ci(struct dst_state *state, u8 *data, int len, u8 *ca_string,
}
if(dst_ca_comm_err == RETRIES)
- return -1;
+ return -EIO;
return 0;
}
@@ -152,7 +152,7 @@ static int ca_get_app_info(struct dst_state *state)
put_checksum(&command[0], command[0]);
if ((dst_put_ci(state, command, sizeof(command), state->messages, GET_REPLY)) < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->dst_put_ci FAILED !");
- return -1;
+ return -EIO;
}
dprintk(verbose, DST_CA_INFO, 1, " -->dst_put_ci SUCCESS !");
dprintk(verbose, DST_CA_INFO, 1, " ================================ CI Module Application Info ======================================");
@@ -191,7 +191,7 @@ static int ca_get_ca_info(struct dst_state *state)
put_checksum(&slot_command[0], slot_command[0]);
if ((dst_put_ci(state, slot_command, sizeof (slot_command), state->messages, GET_REPLY)) < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->dst_put_ci FAILED !");
- return -1;
+ return -EIO;
}
dprintk(verbose, DST_CA_INFO, 1, " -->dst_put_ci SUCCESS !");
@@ -235,7 +235,7 @@ static int ca_get_slot_caps(struct dst_state *state, struct ca_caps *p_ca_caps,
put_checksum(&slot_command[0], slot_command[0]);
if ((dst_put_ci(state, slot_command, sizeof (slot_command), slot_cap, GET_REPLY)) < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->dst_put_ci FAILED !");
- return -1;
+ return -EIO;
}
dprintk(verbose, DST_CA_NOTICE, 1, " -->dst_put_ci SUCCESS !");
@@ -275,7 +275,7 @@ static int ca_get_slot_info(struct dst_state *state, struct ca_slot_info *p_ca_s
put_checksum(&slot_command[0], 7);
if ((dst_put_ci(state, slot_command, sizeof (slot_command), slot_info, GET_REPLY)) < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->dst_put_ci FAILED !");
- return -1;
+ return -EIO;
}
dprintk(verbose, DST_CA_INFO, 1, " -->dst_put_ci SUCCESS !");
@@ -347,7 +347,7 @@ static int handle_dst_tag(struct dst_state *state, struct ca_msg *p_ca_message,
} else {
if (length > 247) {
dprintk(verbose, DST_CA_ERROR, 1, " Message too long ! *** Bailing Out *** !");
- return -1;
+ return -EIO;
}
hw_buffer->msg[0] = (length & 0xff) + 7;
hw_buffer->msg[1] = 0x40;
@@ -373,7 +373,7 @@ static int write_to_8820(struct dst_state *state, struct ca_msg *hw_buffer, u8 l
dprintk(verbose, DST_CA_ERROR, 1, " DST-CI Command failed.");
dprintk(verbose, DST_CA_NOTICE, 1, " Resetting DST.");
rdc_reset_state(state);
- return -1;
+ return -EIO;
}
dprintk(verbose, DST_CA_NOTICE, 1, " DST-CI Command success.");
@@ -446,7 +446,7 @@ static int dst_check_ca_pmt(struct dst_state *state, struct ca_msg *p_ca_message
if (ca_pmt_reply_test) {
if ((ca_set_pmt(state, p_ca_message, hw_buffer, 1, GET_REPLY)) < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " ca_set_pmt.. failed !");
- return -1;
+ return -EIO;
}
/* Process CA PMT Reply */
@@ -457,7 +457,7 @@ static int dst_check_ca_pmt(struct dst_state *state, struct ca_msg *p_ca_message
if (!ca_pmt_reply_test) {
if ((ca_set_pmt(state, p_ca_message, hw_buffer, 0, NO_REPLY)) < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " ca_set_pmt.. failed !");
- return -1;
+ return -EIO;
}
dprintk(verbose, DST_CA_NOTICE, 1, " ca_set_pmt.. success !");
/* put a dummy message */
@@ -566,17 +566,18 @@ static long dst_ca_ioctl(struct file *file, unsigned int cmd, unsigned long ioct
switch (cmd) {
case CA_SEND_MSG:
dprintk(verbose, DST_CA_INFO, 1, " Sending message");
- if ((ca_send_message(state, p_ca_message, arg)) < 0) {
+ result = ca_send_message(state, p_ca_message, arg);
+
+ if (result < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->CA_SEND_MSG Failed !");
- result = -1;
goto free_mem_and_exit;
}
break;
case CA_GET_MSG:
dprintk(verbose, DST_CA_INFO, 1, " Getting message");
- if ((ca_get_message(state, p_ca_message, arg)) < 0) {
+ result = ca_get_message(state, p_ca_message, arg);
+ if (result < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->CA_GET_MSG Failed !");
- result = -1;
goto free_mem_and_exit;
}
dprintk(verbose, DST_CA_INFO, 1, " -->CA_GET_MSG Success !");
@@ -588,7 +589,8 @@ static long dst_ca_ioctl(struct file *file, unsigned int cmd, unsigned long ioct
break;
case CA_GET_SLOT_INFO:
dprintk(verbose, DST_CA_INFO, 1, " Getting Slot info");
- if ((ca_get_slot_info(state, p_ca_slot_info, arg)) < 0) {
+ result = ca_get_slot_info(state, p_ca_slot_info, arg);
+ if (result < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->CA_GET_SLOT_INFO Failed !");
result = -1;
goto free_mem_and_exit;
@@ -597,25 +599,26 @@ static long dst_ca_ioctl(struct file *file, unsigned int cmd, unsigned long ioct
break;
case CA_GET_CAP:
dprintk(verbose, DST_CA_INFO, 1, " Getting Slot capabilities");
- if ((ca_get_slot_caps(state, p_ca_caps, arg)) < 0) {
+ result = ca_get_slot_caps(state, p_ca_caps, arg);
+ if (result < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->CA_GET_CAP Failed !");
- result = -1;
goto free_mem_and_exit;
}
dprintk(verbose, DST_CA_INFO, 1, " -->CA_GET_CAP Success !");
break;
case CA_GET_DESCR_INFO:
dprintk(verbose, DST_CA_INFO, 1, " Getting descrambler description");
- if ((ca_get_slot_descr(state, p_ca_message, arg)) < 0) {
+ result = ca_get_slot_descr(state, p_ca_message, arg);
+ if (result < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->CA_GET_DESCR_INFO Failed !");
- result = -1;
goto free_mem_and_exit;
}
dprintk(verbose, DST_CA_INFO, 1, " -->CA_GET_DESCR_INFO Success !");
break;
case CA_SET_DESCR:
dprintk(verbose, DST_CA_INFO, 1, " Setting descrambler");
- if ((ca_set_slot_descr()) < 0) {
+ result = ca_set_slot_descr();
+ if (result < 0) {
dprintk(verbose, DST_CA_ERROR, 1, " -->CA_SET_DESCR Failed !");
result = -1;
goto free_mem_and_exit;
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 21/27] media: ca-reset.rst: add some description to this ioctl
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (19 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 20/27] media: dst_ca: return a proper error code from CA errors Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 22/27] media: ca-get-cap.rst: document " Mauro Carvalho Chehab
` (7 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
While we don't have any documentation for it, based on what's
there at Kaffeine and VDR, it seems that this command should
be issued before start using CA. So, document it as such.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/ca-reset.rst | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/media/uapi/dvb/ca-reset.rst b/Documentation/media/uapi/dvb/ca-reset.rst
index 477313121a65..a5dd2797a92f 100644
--- a/Documentation/media/uapi/dvb/ca-reset.rst
+++ b/Documentation/media/uapi/dvb/ca-reset.rst
@@ -28,7 +28,8 @@ Arguments
Description
-----------
-.. note:: This ioctl is undocumented. Documentation is welcome.
+Puts the Conditional Access hardware on its initial state. It should
+be called before start using the CA hardware.
Return Value
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 22/27] media: ca-get-cap.rst: document this ioctl
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (20 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 21/27] media: ca-reset.rst: add some description to this ioctl Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 23/27] media: ca-get-slot-info.rst: " Mauro Carvalho Chehab
` (6 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Instead of a generic boilerplate, fill it with relevant
information about this ioctl.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/ca-get-cap.rst | 36 ++++-------------------------
1 file changed, 5 insertions(+), 31 deletions(-)
diff --git a/Documentation/media/uapi/dvb/ca-get-cap.rst b/Documentation/media/uapi/dvb/ca-get-cap.rst
index fbf7e359cb8a..02d64acfb087 100644
--- a/Documentation/media/uapi/dvb/ca-get-cap.rst
+++ b/Documentation/media/uapi/dvb/ca-get-cap.rst
@@ -28,43 +28,17 @@ Arguments
``caps``
Pointer to struct :c:type:`ca_caps`.
-.. c:type:: struct ca_caps
-
-.. flat-table:: struct ca_caps
- :header-rows: 1
- :stub-columns: 0
-
- -
- - type
- - name
- - description
- -
- - unsigned int
- - slot_num
- - total number of CA card and module slots
- -
- - unsigned int
- - slot_type
- - bitmask with all supported slot types
- -
- - unsigned int
- - descr_num
- - total number of descrambler slots (keys)
- -
- - unsigned int
- - descr_type
- - bit mask with all supported descr types
-
-
Description
-----------
-.. note:: This ioctl is undocumented. Documentation is welcome.
-
+Queries the Kernel for information about the available CA and descrambler
+slots, and their types.
Return Value
------------
-On success 0 is returned, on error -1 and the ``errno`` variable is set
+On success 0 is returned and :c:type:`ca_caps` is filled.
+
+On error, -1 is returned and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 23/27] media: ca-get-slot-info.rst: document this ioctl
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (21 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 22/27] media: ca-get-cap.rst: document " Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 24/27] media: ca-get-descr-info.rst: " Mauro Carvalho Chehab
` (5 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Instead of a generic boilerplate, fill it with relevant
information about this ioctl.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/ca-get-slot-info.rst | 98 +++--------------------
1 file changed, 11 insertions(+), 87 deletions(-)
diff --git a/Documentation/media/uapi/dvb/ca-get-slot-info.rst b/Documentation/media/uapi/dvb/ca-get-slot-info.rst
index 54e5dc78a2dc..d7e41e038ca7 100644
--- a/Documentation/media/uapi/dvb/ca-get-slot-info.rst
+++ b/Documentation/media/uapi/dvb/ca-get-slot-info.rst
@@ -26,100 +26,24 @@ Arguments
File descriptor returned by a previous call to :c:func:`open() <cec-open>`.
``info``
- Pointer to struct c:type:`ca_slot_info`.
-
-.. _ca_slot_info_type:
-
-.. flat-table:: ca_slot_info types
- :header-rows: 1
- :stub-columns: 0
-
- -
- - type
- - name
- - description
- -
- - CA_CI
- - 1
- - CI high level interface
-
- -
- - CA_CI_LINK
- - 2
- - CI link layer level interface
-
- -
- - CA_CI_PHYS
- - 4
- - CI physical layer level interface
-
- -
- - CA_DESCR
- - 8
- - built-in descrambler
-
- -
- - CA_SC
- - 128
- - simple smart card interface
-
-.. _ca_slot_info_flag:
-
-.. flat-table:: ca_slot_info flags
- :header-rows: 1
- :stub-columns: 0
-
- -
- - type
- - name
- - description
-
- -
- - CA_CI_MODULE_PRESENT
- - 1
- - module (or card) inserted
-
- -
- - CA_CI_MODULE_READY
- - 2
- -
-
-.. c:type:: ca_slot_info
-
-.. flat-table:: struct ca_slot_info
- :header-rows: 1
- :stub-columns: 0
-
- -
- - type
- - name
- - description
-
- -
- - int
- - num
- - slot number
-
- -
- - int
- - type
- - CA interface this slot supports, as defined at :ref:`ca_slot_info_type`.
-
- -
- - unsigned int
- - flags
- - flags as defined at :ref:`ca_slot_info_flag`.
-
+ Pointer to struct :c:type:`ca_slot_info`.
Description
-----------
-.. note:: This ioctl is undocumented. Documentation is welcome.
+Returns information about a CA slot identified by
+:c:type:`ca_slot_info`.slot_num.
Return Value
------------
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
+On success 0 is returned, and :c:type:`ca_slot_info` is filled.
+
+On error -1 is returned, and the ``errno`` variable is set
+appropriately.
+
+If the slot is not available, ``errno`` will contain ``-EINVAL``.
+
+The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 24/27] media: ca-get-descr-info.rst: document this ioctl
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (22 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 23/27] media: ca-get-slot-info.rst: " Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 25/27] media: dvb CA docs: place undocumented data together with ioctls Mauro Carvalho Chehab
` (4 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Instead of a generic boilerplate, fill it with relevant
information about this ioctl.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/ca-get-descr-info.rst | 29 +++-------------------
1 file changed, 4 insertions(+), 25 deletions(-)
diff --git a/Documentation/media/uapi/dvb/ca-get-descr-info.rst b/Documentation/media/uapi/dvb/ca-get-descr-info.rst
index 7bf327a3d0e3..e564fbb8d524 100644
--- a/Documentation/media/uapi/dvb/ca-get-descr-info.rst
+++ b/Documentation/media/uapi/dvb/ca-get-descr-info.rst
@@ -27,37 +27,16 @@ Arguments
``desc``
Pointer to struct :c:type:`ca_descr_info`.
-.. c:type:: struct ca_descr_info
-
-.. flat-table:: struct ca_descr_info
- :header-rows: 1
- :stub-columns: 0
-
- -
- - type
- - name
- - description
-
- -
- - unsigned int
- - num
- - number of available descramblers (keys)
- -
- - unsigned int
- - type
- - type of supported scrambling system. Valid values are:
- ``CA_ECD``, ``CA_NDS`` and ``CA_DSS``.
-
-
Description
-----------
-.. note:: This ioctl is undocumented. Documentation is welcome.
-
+Returns information about all descrambler slots.
Return Value
------------
-On success 0 is returned, on error -1 and the ``errno`` variable is set
+On success 0 is returned, and :c:type:`ca_descr_info` is filled.
+
+On error -1 is returned, and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 25/27] media: dvb CA docs: place undocumented data together with ioctls
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (23 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 24/27] media: ca-get-descr-info.rst: " Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 26/27] media: dvb rst: identify the documentation gap at the API Mauro Carvalho Chehab
` (3 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Right now, the same undocumented structs are on two places:
at ca_data_types.rst and together with their ioctls.
Move them to just one place and use the standard way to
represent them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/ca-get-msg.rst | 38 ++++++--------------------
Documentation/media/uapi/dvb/ca-set-descr.rst | 10 +++++++
Documentation/media/uapi/dvb/ca_data_types.rst | 32 ----------------------
3 files changed, 19 insertions(+), 61 deletions(-)
diff --git a/Documentation/media/uapi/dvb/ca-get-msg.rst b/Documentation/media/uapi/dvb/ca-get-msg.rst
index 121588da3ef1..1ee9d667c901 100644
--- a/Documentation/media/uapi/dvb/ca-get-msg.rst
+++ b/Documentation/media/uapi/dvb/ca-get-msg.rst
@@ -28,37 +28,17 @@ Arguments
``msg``
Pointer to struct :c:type:`ca_msg`.
+.. c:type:: ca_msg
-.. c:type:: struct ca_msg
-
-.. flat-table:: struct ca_msg
- :header-rows: 1
- :stub-columns: 0
-
- -
- - type
- - name
- - description
- -
- - unsigned int
- - index
- -
-
- -
- - unsigned int
- - type
- -
-
- -
- - unsigned int
- - length
- -
-
- -
- - unsigned char
- - msg[256]
- -
+.. 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
-----------
diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst b/Documentation/media/uapi/dvb/ca-set-descr.rst
index 70f7b3cf12ad..95de34cf74ba 100644
--- a/Documentation/media/uapi/dvb/ca-set-descr.rst
+++ b/Documentation/media/uapi/dvb/ca-set-descr.rst
@@ -28,6 +28,16 @@ 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
-----------
diff --git a/Documentation/media/uapi/dvb/ca_data_types.rst b/Documentation/media/uapi/dvb/ca_data_types.rst
index aa57dd176825..ac7cbd76ddd5 100644
--- a/Documentation/media/uapi/dvb/ca_data_types.rst
+++ b/Documentation/media/uapi/dvb/ca_data_types.rst
@@ -7,35 +7,3 @@ CA Data Types
*************
.. kernel-doc:: include/uapi/linux/dvb/ca.h
-
-.. c:type:: ca_msg
-
-Undocumented data types
-=======================
-
-.. note::
-
- Those data types are undocumented. Documentation is welcome.
-
-.. 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];
- };
-
-
-.. c:type:: ca_descr
-
-.. code-block:: c
-
- struct ca_descr {
- unsigned int index;
- unsigned int parity;
- unsigned char cw[8];
- };
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 26/27] media: dvb rst: identify the documentation gap at the API
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (24 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 25/27] media: dvb CA docs: place undocumented data together with ioctls Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 27/27] media: dst_ca: remove CA_SET_DESCR boilerplate Mauro Carvalho Chehab
` (2 subsequent siblings)
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Now that DVB spec is almost in sync, document what's missing.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/dvb/ca.rst | 5 +++++
Documentation/media/uapi/dvb/legacy_dvb_apis.rst | 5 +++++
2 files changed, 10 insertions(+)
diff --git a/Documentation/media/uapi/dvb/ca.rst b/Documentation/media/uapi/dvb/ca.rst
index 14b14abda1ae..e3de778a5678 100644
--- a/Documentation/media/uapi/dvb/ca.rst
+++ b/Documentation/media/uapi/dvb/ca.rst
@@ -10,6 +10,11 @@ accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl
definitions can be accessed by including ``linux/dvb/ca.h`` in your
application.
+.. note::
+
+ There are three ioctls at this API that aren't documented:
+ :ref:`CA_GET_MSG`, :ref:`CA_SEND_MSG` and :ref:`CA_SET_DESCR`.
+ Documentation for them are welcome.
.. toctree::
:maxdepth: 1
diff --git a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst b/Documentation/media/uapi/dvb/legacy_dvb_apis.rst
index 2957f5a988b0..dac349a1bb27 100644
--- a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst
+++ b/Documentation/media/uapi/dvb/legacy_dvb_apis.rst
@@ -12,6 +12,11 @@ drivers should use it. Instead, audio and video should be using the V4L2
and ALSA APIs, and the pipelines should be set using the Media
Controller API
+.. note::
+
+ The APIs described here doesn't necessarily reflect the current
+ code implementation.
+
.. toctree::
:maxdepth: 1
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* [PATCH v2 27/27] media: dst_ca: remove CA_SET_DESCR boilerplate
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (25 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 26/27] media: dvb rst: identify the documentation gap at the API Mauro Carvalho Chehab
@ 2017-09-01 13:24 ` Mauro Carvalho Chehab
2017-09-03 20:05 ` [PATCH v2 00/26] Improve DVB documentation and reduce its gap Honza Petrouš
2017-09-03 20:31 ` Honza Petrouš
28 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:24 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Markus Elfring
This ioctl is not implemented at dst_ca driver. There's just
a boilerplate code there. Remove it, as it is unlikely that
anyone would implement it those days.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
drivers/media/pci/bt8xx/dst_ca.c | 17 -----------------
1 file changed, 17 deletions(-)
diff --git a/drivers/media/pci/bt8xx/dst_ca.c b/drivers/media/pci/bt8xx/dst_ca.c
index 5ebb86f22935..530b3e9764ce 100644
--- a/drivers/media/pci/bt8xx/dst_ca.c
+++ b/drivers/media/pci/bt8xx/dst_ca.c
@@ -57,13 +57,6 @@ static unsigned int verbose = 5;
module_param(verbose, int, 0644);
MODULE_PARM_DESC(verbose, "verbose startup messages, default is 1 (yes)");
-/* Need some more work */
-static int ca_set_slot_descr(void)
-{
- /* We could make this more graceful ? */
- return -EOPNOTSUPP;
-}
-
static void put_command_and_length(u8 *data, int command, int length)
{
data[0] = (command >> 16) & 0xff;
@@ -615,16 +608,6 @@ static long dst_ca_ioctl(struct file *file, unsigned int cmd, unsigned long ioct
}
dprintk(verbose, DST_CA_INFO, 1, " -->CA_GET_DESCR_INFO Success !");
break;
- case CA_SET_DESCR:
- dprintk(verbose, DST_CA_INFO, 1, " Setting descrambler");
- result = ca_set_slot_descr();
- if (result < 0) {
- dprintk(verbose, DST_CA_ERROR, 1, " -->CA_SET_DESCR Failed !");
- result = -1;
- goto free_mem_and_exit;
- }
- dprintk(verbose, DST_CA_INFO, 1, " -->CA_SET_DESCR Success !");
- break;
default:
result = -EOPNOTSUPP;
}
--
2.13.5
^ permalink raw reply related [flat|nested] 36+ messages in thread
* Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (26 preceding siblings ...)
2017-09-01 13:24 ` [PATCH v2 27/27] media: dst_ca: remove CA_SET_DESCR boilerplate Mauro Carvalho Chehab
@ 2017-09-03 20:05 ` Honza Petrouš
2017-09-04 0:54 ` Mauro Carvalho Chehab
2017-09-04 1:17 ` Mauro Carvalho Chehab
2017-09-03 20:31 ` Honza Petrouš
28 siblings, 2 replies; 36+ messages in thread
From: Honza Petrouš @ 2017-09-03 20:05 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
> There is still a gap at the CA API, as there are three ioctls that are used
> only by a few drivers and whose structs are not properly documented:
> CA_GET_MSG, CA_SEND_MSG and CA_SET_DESCR.
>
> The first two ones seem to be related to a way that a few drivers
> provide to send/receive messages.
I never seen usage of such R/W ioctls, all drivers I have access to
are using read()/write() variant of communication.
Yet, I was unable to get what
> "index" and "type" means on those ioctls. The CA_SET_DESCR is
> only supported by av7110 driver, and has an even weirder
> undocumented struct. I was unable to discover at the Kernel, VDR
> or Kaffeine how those structs are filled. I suspect that there's
> something wrong there, but I won't risk trying to fix without
> knowing more about them. So, let's just document that those
> are needing documentation :-)
>
1) #define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
============================================
CA_SET_DESCR is used for feeding descrambler device
with correct keys (called here "control words") what
allows to get services unscrambled.
The best docu is:
"Digital Video Broadcasting (DVB);
Support for use of the DVB Scrambling Algorithm version 3
within digital broadcasting systems"
Defined as DVB Document A125 and publicly
available here:
https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
typedef struct ca_descr {
unsigned int index;
unsigned int parity; /* 0 == even, 1 == odd */
unsigned char cw[8];
} ca_descr_t;
The 'index' is adress of the descrambler instance, as there exist
limited number of them (retieved by CA_GET_DESCR_INFO).
See below:
2) #define CA_SET_PID _IOW('o', 135, ca_pid_t)
=======================================
The second ioctl was used to link particular PID with particular
descrambler, what means that all such pids (you are allowed
to create n-to-1 link), can be descrambled by one descrambler.
This is needed in case of multiservice descrambling, when
usually exist one key (control word) per one service (so all PIDs
for one service have to be linked with one descrambler)
Without this ioctl there is no way to address particular
descrambler and so no way to use more then ONE descrambler
per demux
/Honza
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (27 preceding siblings ...)
2017-09-03 20:05 ` [PATCH v2 00/26] Improve DVB documentation and reduce its gap Honza Petrouš
@ 2017-09-03 20:31 ` Honza Petrouš
28 siblings, 0 replies; 36+ messages in thread
From: Honza Petrouš @ 2017-09-03 20:31 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
> There is still a gap at the CA API, as there are three ioctls that are used
> only by a few drivers and whose structs are not properly documented:
> CA_GET_MSG, CA_SEND_MSG and CA_SET_DESCR.
>
> The first two ones seem to be related to a way that a few drivers
> provide to send/receive messages. Yet, I was unable to get what
> "index" and "type" means on those ioctls. The CA_SET_DESCR is
> only supported by av7110 driver, and has an even weirder
> undocumented struct. I was unable to discover at the Kernel, VDR
> or Kaffeine how those structs are filled. I suspect that there's
> something wrong there, but I won't risk trying to fix without
> knowing more about them. So, let's just document that those
> are needing documentation :-)
>
BTW, I just remembered dvblast app, part of videolan.org:
http://www.videolan.org/projects/dvblast.html
which is using CA_GET_MSG/CA_SEND_MSG:
https://code.videolan.org/videolan/dvblast/blob/master/en50221.c
/Honza
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap
2017-09-03 20:05 ` [PATCH v2 00/26] Improve DVB documentation and reduce its gap Honza Petrouš
@ 2017-09-04 0:54 ` Mauro Carvalho Chehab
2017-09-04 7:12 ` Honza Petrouš
2017-09-04 1:17 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-04 0:54 UTC (permalink / raw)
To: Honza Petrouš
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
Em Sun, 3 Sep 2017 22:05:23 +0200
Honza Petrouš <jpetrous@gmail.com> escreveu:
> 1) #define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
> ============================================
>
> CA_SET_DESCR is used for feeding descrambler device
> with correct keys (called here "control words") what
> allows to get services unscrambled.
>
> The best docu is:
>
> "Digital Video Broadcasting (DVB);
> Support for use of the DVB Scrambling Algorithm version 3
> within digital broadcasting systems"
>
> Defined as DVB Document A125 and publicly
> available here:
>
> https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
>
>
> typedef struct ca_descr {
> unsigned int index;
> unsigned int parity; /* 0 == even, 1 == odd */
> unsigned char cw[8];
> } ca_descr_t;
>
> The 'index' is adress of the descrambler instance, as there exist
> limited number of them (retieved by CA_GET_DESCR_INFO).
Thanks for the info. If I understood well, the enclosed patch should
be documenting it.
Thanks,
Mauro
[PATCH] media: ca docs: document CA_SET_DESCR ioctl and structs
The av7110 driver uses CA_SET_DESCR to store the descrambler
control words at the CA descrambler slots.
Document it.
Thanks-to: Honza Petrouš <jpetrous@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
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];
};
^ permalink raw reply related [flat|nested] 36+ messages in thread
* Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap
2017-09-03 20:05 ` [PATCH v2 00/26] Improve DVB documentation and reduce its gap Honza Petrouš
2017-09-04 0:54 ` Mauro Carvalho Chehab
@ 2017-09-04 1:17 ` Mauro Carvalho Chehab
1 sibling, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-04 1:17 UTC (permalink / raw)
To: Honza Petrouš
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
Em Sun, 3 Sep 2017 22:05:23 +0200
Honza Petrouš <jpetrous@gmail.com> escreveu:
> > There is still a gap at the CA API, as there are three ioctls that are used
> > only by a few drivers and whose structs are not properly documented:
> > CA_GET_MSG, CA_SEND_MSG and CA_SET_DESCR.
> >
> > The first two ones seem to be related to a way that a few drivers
> > provide to send/receive messages.
>
> I never seen usage of such R/W ioctls, all drivers I have access to
> are using read()/write() variant of communication.
Yeah, the normal usage is to use R/W syscalls.
> BTW, I just remembered dvblast app, part of videolan.org:
>
> http://www.videolan.org/projects/dvblast.html
>
> which is using CA_GET_MSG/CA_SEND_MSG:
>
> https://code.videolan.org/videolan/dvblast/blob/master/en50221.c
>From the ca_msg struct:
/* a message to/from a CI-CAM */
struct ca_msg {
unsigned int index;
unsigned int type;
unsigned int length;
unsigned char msg[256];
};
It only uses length and msg fields. Describing those seem
quite obvious. However, what "index" and "type" means?
Within the Kernel, only two drivers implement it:
$ git grep -l ca_msg drivers/
drivers/media/firewire/firedtv-ci.c
drivers/media/pci/bt8xx/dst_ca.c
At the dst_ca driver, checking for those fields don't give any
useful result:
$ grep index drivers/media/pci/bt8xx/dst_ca.c
(nothing)
$ grep type drivers/media/pci/bt8xx/dst_ca.c
// Copy application_type, application_manufacturer and manufacturer_code
p_ca_caps->slot_type = 1;
p_ca_caps->descr_type = 1;
p_ca_slot_info->type = CA_CI;
p_ca_slot_info->type = CA_CI;
(btw, using "1" for slot_type and descr_type there seems a very bad
thing)
The code at ca_get_message(), handle_dst_tag(), ca_set_pmt(), etc also
doesn't seem to be using neither one of those fields.
The same happens at firedtv-ci: it also doesn't seem to be using
none of those fields.
It should be noticed that, the dst_ca seems to allow more than one
descrambler:
p_ca_caps->descr_num = slot_cap[7];
Yet, the index is not used. So, it doesn't seem to be related to
the descrambler index (or there's an implementation bug there - and
at dvblast - as none uses it).
What *I* suspect is that this were meant to be used for either
CA index/type or DESCR index/type, but, when this got implemented,
people discovered that this would be useless and never actually
used those fields. Yet, I may be completely wrong and those were
added to mean something else.
If so, then we could just change the struct to:
struct ca_msg {
unsigned int reserved[2];
unsigned int length;
unsigned char msg[256];
};
And document just length and msg.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap
2017-09-04 0:54 ` Mauro Carvalho Chehab
@ 2017-09-04 7:12 ` Honza Petrouš
2017-09-04 9:06 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 36+ messages in thread
From: Honza Petrouš @ 2017-09-04 7:12 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
2017-09-04 2:54 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> Em Sun, 3 Sep 2017 22:05:23 +0200
> Honza Petrouš <jpetrous@gmail.com> escreveu:
>
>> 1) #define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
>> ============================================
>>
>> CA_SET_DESCR is used for feeding descrambler device
>> with correct keys (called here "control words") what
>> allows to get services unscrambled.
>>
>> The best docu is:
>>
>> "Digital Video Broadcasting (DVB);
>> Support for use of the DVB Scrambling Algorithm version 3
>> within digital broadcasting systems"
>>
>> Defined as DVB Document A125 and publicly
>> available here:
>>
>> https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
>>
>>
>> typedef struct ca_descr {
>> unsigned int index;
>> unsigned int parity; /* 0 == even, 1 == odd */
>> unsigned char cw[8];
>> } ca_descr_t;
>>
>> The 'index' is adress of the descrambler instance, as there exist
>> limited number of them (retieved by CA_GET_DESCR_INFO).
>
> Thanks for the info. If I understood well, the enclosed patch should
> be documenting it.
>
>
> Thanks,
> Mauro
>
> [PATCH] media: ca docs: document CA_SET_DESCR ioctl and structs
>
> The av7110 driver uses CA_SET_DESCR to store the descrambler
> control words at the CA descrambler slots.
>
> Document it.
>
> Thanks-to: Honza Petrouš <jpetrous@gmail.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>
> 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];
> };
>
>
Yeh, it should be that way.
BTW, the only issue I have in mind is how to link particular
descrambler with the PID
after your removal of the CA_SET_PID. And yes, I know that currently we have
no any user of such ioctl in our driver base :)
/Honza
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap
2017-09-04 7:12 ` Honza Petrouš
@ 2017-09-04 9:06 ` Mauro Carvalho Chehab
2017-09-04 9:40 ` Honza Petrouš
0 siblings, 1 reply; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-04 9:06 UTC (permalink / raw)
To: Honza Petrouš
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
Em Mon, 4 Sep 2017 09:12:49 +0200
Honza Petrouš <jpetrous@gmail.com> escreveu:
> 2017-09-04 2:54 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> > Em Sun, 3 Sep 2017 22:05:23 +0200
> > Honza Petrouš <jpetrous@gmail.com> escreveu:
> >
> >> 1) #define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
> >> ============================================
> >>
> >> CA_SET_DESCR is used for feeding descrambler device
> >> with correct keys (called here "control words") what
> >> allows to get services unscrambled.
> >>
> >> The best docu is:
> >>
> >> "Digital Video Broadcasting (DVB);
> >> Support for use of the DVB Scrambling Algorithm version 3
> >> within digital broadcasting systems"
> >>
> >> Defined as DVB Document A125 and publicly
> >> available here:
> >>
> >> https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
> >>
> >>
> >> typedef struct ca_descr {
> >> unsigned int index;
> >> unsigned int parity; /* 0 == even, 1 == odd */
> >> unsigned char cw[8];
> >> } ca_descr_t;
> >>
> >> The 'index' is adress of the descrambler instance, as there exist
> >> limited number of them (retieved by CA_GET_DESCR_INFO).
> >
> > Thanks for the info. If I understood well, the enclosed patch should
> > be documenting it.
> >
> >
> > Thanks,
> > Mauro
> >
> > [PATCH] media: ca docs: document CA_SET_DESCR ioctl and structs
> >
> > The av7110 driver uses CA_SET_DESCR to store the descrambler
> > control words at the CA descrambler slots.
> >
> > Document it.
> >
> > Thanks-to: Honza Petrouš <jpetrous@gmail.com>
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> >
> > 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];
> > };
> >
> >
>
> Yeh, it should be that way.
Good! I'll add this patch to the series.
> BTW, the only issue I have in mind is how to link particular
> descrambler with the PID
> after your removal of the CA_SET_PID. And yes, I know that currently we have
> no any user of such ioctl in our driver base :)
Well, I don't think that an ioctl like CA_SET_PID would solve it.
On a generic case with is quite common nowadays on embedded hardware,
We have K demods and M CIs (where K may be different than M).
Also, You may need to route N PIDs to O descramblers.
As user switch channels, the N PIDs should be unset, and another
set of N' pids will be routed.
CA_SET_PID allows to set just one PID, without identifying from
what demod it would be received, and doesn't have a "reset"
function to undo.
So, IMHO, the interface is broken by design. Perhaps that's
the reason why no upstream driver uses it.
What seems to be a much better design would be to use the demux
set filter ioctls and route the PIDs to the right CA.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap
2017-09-04 9:06 ` Mauro Carvalho Chehab
@ 2017-09-04 9:40 ` Honza Petrouš
2017-09-04 11:46 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 36+ messages in thread
From: Honza Petrouš @ 2017-09-04 9:40 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
2017-09-04 11:06 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> Em Mon, 4 Sep 2017 09:12:49 +0200
> Honza Petrouš <jpetrous@gmail.com> escreveu:
>
>> 2017-09-04 2:54 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> > Em Sun, 3 Sep 2017 22:05:23 +0200
>> > Honza Petrouš <jpetrous@gmail.com> escreveu:
>> >
>> >> 1) #define CA_SET_DESCR _IOW('o', 134, ca_descr_t)
>> >> ============================================
>> >>
>> >> CA_SET_DESCR is used for feeding descrambler device
>> >> with correct keys (called here "control words") what
>> >> allows to get services unscrambled.
>> >>
>> >> The best docu is:
>> >>
>> >> "Digital Video Broadcasting (DVB);
>> >> Support for use of the DVB Scrambling Algorithm version 3
>> >> within digital broadcasting systems"
>> >>
>> >> Defined as DVB Document A125 and publicly
>> >> available here:
>> >>
>> >> https://www.dvb.org/resources/public/standards/a125_dvb-csa3.pdf
>> >>
>> >>
>> >> typedef struct ca_descr {
>> >> unsigned int index;
>> >> unsigned int parity; /* 0 == even, 1 == odd */
>> >> unsigned char cw[8];
>> >> } ca_descr_t;
>> >>
>> >> The 'index' is adress of the descrambler instance, as there exist
>> >> limited number of them (retieved by CA_GET_DESCR_INFO).
>> >
>> > Thanks for the info. If I understood well, the enclosed patch should
>> > be documenting it.
>> >
>> >
>> > Thanks,
>> > Mauro
>> >
>> > [PATCH] media: ca docs: document CA_SET_DESCR ioctl and structs
>> >
>> > The av7110 driver uses CA_SET_DESCR to store the descrambler
>> > control words at the CA descrambler slots.
>> >
>> > Document it.
>> >
>> > Thanks-to: Honza Petrouš <jpetrous@gmail.com>
>> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>> >
>> > 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];
>> > };
>> >
>> >
>>
>> Yeh, it should be that way.
>
> Good! I'll add this patch to the series.
>
>> BTW, the only issue I have in mind is how to link particular
>> descrambler with the PID
>> after your removal of the CA_SET_PID. And yes, I know that currently we have
>> no any user of such ioctl in our driver base :)
>
> Well, I don't think that an ioctl like CA_SET_PID would solve it.
>
> On a generic case with is quite common nowadays on embedded hardware,
> We have K demods and M CIs (where K may be different than M).
>
> Also, You may need to route N PIDs to O descramblers.
TBH that is exactly most common use-case = most Digital TV
vendors are scrambling per-service, what requires one descrambler
for all scrambled PIDs (usually only A/V PIDs are scrambled)
for particular service. So we have to add more PIDs to one descrambler
What was possible by multiple call of CA_SET_PID (I agree that much
better would be name like CA_ADD_PID)
>
> As user switch channels, the N PIDs should be unset, and another
> set of N' pids will be routed.
>
> CA_SET_PID allows to set just one PID, without identifying from
> what demod it would be received, and doesn't have a "reset"
> function to undo.
Here I can agree - it looks like the value -1 in 'index' should
do the job, but it, unfortunately, looses info from which descrambler
it should be removed (see note in struct ca_pid for value -1)
>
> So, IMHO, the interface is broken by design. Perhaps that's
> the reason why no upstream driver uses it.
I have the same feeling regarding brokenness.
>
> What seems to be a much better design would be to use the demux
> set filter ioctls and route the PIDs to the right CA.
>
I don't have access to any programmer reference documentation
for any modern DVB-enabled SoC, but I see two possible scenario
of connecting descramblers to the demuxes (most of modern SoCs
have more then one demux) - static one, when every demux has
predefined descramblers already connected to it and dynamic ones,
when any descrambler can be connected to the any demux.
>From that reason I vote to have some descrambler specific ioctl,
which allow more flexibility then if we add it to the filter set ioctl.
My 5 cents
/Honza
PS: I understand that until we get some multi-descrambler device included,
we don't need to address descrambler management.
^ permalink raw reply [flat|nested] 36+ messages in thread
* Re: [PATCH v2 00/26] Improve DVB documentation and reduce its gap
2017-09-04 9:40 ` Honza Petrouš
@ 2017-09-04 11:46 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 36+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-04 11:46 UTC (permalink / raw)
To: Honza Petrouš
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
Em Mon, 4 Sep 2017 11:40:59 +0200
Honza Petrouš <jpetrous@gmail.com> escreveu:
> > So, IMHO, the interface is broken by design. Perhaps that's
> > the reason why no upstream driver uses it.
>
> I have the same feeling regarding brokenness.
>
> >
> > What seems to be a much better design would be to use the demux
> > set filter ioctls and route the PIDs to the right CA.
> >
>
> I don't have access to any programmer reference documentation
> for any modern DVB-enabled SoC, but I see two possible scenario
> of connecting descramblers to the demuxes (most of modern SoCs
> have more then one demux) - static one, when every demux has
> predefined descramblers already connected to it and dynamic ones,
> when any descrambler can be connected to the any demux.
I don't have access to the documentation either, but I know
some designs that have multiple demods that are dynamically set.
Some hardware even allow to dynamically change the maximum amount
of filters per demod at runtime.
> From that reason I vote to have some descrambler specific ioctl,
> which allow more flexibility then if we add it to the filter set ioctl.
I suspect that doing it at the demod does a lot more sense.
Anyway, someone should come with a driver requiring it upstream
for us to discuss and find the better alternatives to support.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 36+ messages in thread
end of thread, other threads:[~2017-09-04 11:46 UTC | newest]
Thread overview: 36+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-09-01 13:24 [PATCH v2 00/26] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 01/27] media: ca.h: split typedefs from structs Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 02/27] media: dmx.h: " Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 03/27] media: dvb/intro: use the term Digital TV to refer to the system Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 04/27] media: dvb/intro: update references for TV standards Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 05/27] media: dvb/intro: update the history part of the document Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 06/27] media: dvb/intro: adjust the notices about optional hardware Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 07/27] media: dvb/frontend.h: move out a private internal structure Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 08/27] media: dvb/frontend.h: document the uAPI file Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 09/27] media: dvb frontend docs: use kernel-doc documentation Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 10/27] media: fe_property_parameters.rst: better define properties usage Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 11/27] media: fe_property_parameters.rst: better document bandwidth Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 12/27] media: dmx.h: get rid of unused DMX_KERNEL_CLIENT Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 13/27] media: dmx.h: get rid of DMX_GET_CAPS Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 14/27] media: dmx.h: get rid of DMX_SET_SOURCE Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 15/27] media: dmx.h: get rid of GET_DMX_EVENT Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 16/27] media: dmx.h: add kernel-doc markups and use it at Documentation/ Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 17/27] media: net.rst: Fix the level of a section of the net chapter Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 18/27] media: ca.h: get rid of CA_SET_PID Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 19/27] media: ca.h: document most CA data types Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 20/27] media: dst_ca: return a proper error code from CA errors Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 21/27] media: ca-reset.rst: add some description to this ioctl Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 22/27] media: ca-get-cap.rst: document " Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 23/27] media: ca-get-slot-info.rst: " Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 24/27] media: ca-get-descr-info.rst: " Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 25/27] media: dvb CA docs: place undocumented data together with ioctls Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 26/27] media: dvb rst: identify the documentation gap at the API Mauro Carvalho Chehab
2017-09-01 13:24 ` [PATCH v2 27/27] media: dst_ca: remove CA_SET_DESCR boilerplate Mauro Carvalho Chehab
2017-09-03 20:05 ` [PATCH v2 00/26] Improve DVB documentation and reduce its gap Honza Petrouš
2017-09-04 0:54 ` Mauro Carvalho Chehab
2017-09-04 7:12 ` Honza Petrouš
2017-09-04 9:06 ` Mauro Carvalho Chehab
2017-09-04 9:40 ` Honza Petrouš
2017-09-04 11:46 ` Mauro Carvalho Chehab
2017-09-04 1:17 ` Mauro Carvalho Chehab
2017-09-03 20:31 ` Honza Petrouš
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.