* [PATCH 00/15] Improve DVB documentation and reduce its gap
@ 2017-08-31 23:46 Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 01/15] media: dvb/intro: use the term Digital TV to refer to the system Mauro Carvalho Chehab
` (15 more replies)
0 siblings, 16 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 UTC (permalink / raw)
To: Linux Doc Mailing List, Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Masahiro Yamada, Shuah Khan, Ingo Molnar,
Max Kellermann, Sakari Ailus, Colin Ian King
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 that I'll try to address when I
have some time[1].
[1] There's a gap also on the legacy audio, video and OSD APIs,
but, as those are used only by a single very old deprecated
hardware (av7110), it is probably not worth the efforts.
Mauro Carvalho Chehab (15):
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
Documentation/media/dmx.h.rst.exceptions | 20 +-
Documentation/media/frontend.h.rst.exceptions | 185 ++-
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/net.rst | 1 -
drivers/media/dvb-core/dvb_frontend.c | 11 +
include/uapi/linux/dvb/dmx.h | 171 ++-
include/uapi/linux/dvb/frontend.h | 589 +++++++--
27 files changed, 1082 insertions(+), 2437 deletions(-)
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] 27+ messages in thread
* [PATCH 01/15] media: dvb/intro: use the term Digital TV to refer to the system
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 02/15] media: dvb/intro: update references for TV standards Mauro Carvalho Chehab
` (14 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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] 27+ messages in thread
* [PATCH 02/15] media: dvb/intro: update references for TV standards
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 01/15] media: dvb/intro: use the term Digital TV to refer to the system Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 03/15] media: dvb/intro: update the history part of the document Mauro Carvalho Chehab
` (13 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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] 27+ messages in thread
* [PATCH 03/15] media: dvb/intro: update the history part of the document
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 01/15] media: dvb/intro: use the term Digital TV to refer to the system Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 02/15] media: dvb/intro: update references for TV standards Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 04/15] media: dvb/intro: adjust the notices about optional hardware Mauro Carvalho Chehab
` (12 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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] 27+ messages in thread
* [PATCH 04/15] media: dvb/intro: adjust the notices about optional hardware
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (2 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 03/15] media: dvb/intro: update the history part of the document Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 05/15] media: dvb/frontend.h: move out a private internal structure Mauro Carvalho Chehab
` (11 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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] 27+ messages in thread
* [PATCH 05/15] media: dvb/frontend.h: move out a private internal structure
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (3 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 04/15] media: dvb/intro: adjust the notices about optional hardware Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 06/15] media: dvb/frontend.h: document the uAPI file Mauro Carvalho Chehab
` (10 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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,
Masahiro Yamada, Ingo Molnar, Sakari Ailus
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] 27+ messages in thread
* [PATCH 06/15] media: dvb/frontend.h: document the uAPI file
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (4 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 05/15] media: dvb/frontend.h: move out a private internal structure Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 07/15] media: dvb frontend docs: use kernel-doc documentation Mauro Carvalho Chehab
` (9 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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 | 578 ++++++++++++++++++++++++++++++++------
1 file changed, 496 insertions(+), 82 deletions(-)
diff --git a/include/uapi/linux/dvb/frontend.h b/include/uapi/linux/dvb/frontend.h
index 3a80f3d1da1c..c7f2124b7851 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,47 @@ 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
};
+enum fe_type type;
+
+/**
+ * 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 +143,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 +251,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 +306,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 +343,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 +381,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 +412,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 +430,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 +446,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 +540,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 +635,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 +725,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 +747,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 +800,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 +852,76 @@ 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_type {
+ FE_QPSK,
+ FE_QAM,
+ FE_OFDM,
+ FE_ATSC
+};
+
+/*
*/
enum fe_bandwidth {
@@ -492,7 +934,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 +952,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 +995,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] 27+ messages in thread
* [PATCH 07/15] media: dvb frontend docs: use kernel-doc documentation
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (5 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 06/15] media: dvb/frontend.h: document the uAPI file Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 08/15] media: fe_property_parameters.rst: better define properties usage Mauro Carvalho Chehab
` (8 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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 c7f2124b7851..f898cc384f43 100644
--- a/include/uapi/linux/dvb/frontend.h
+++ b/include/uapi/linux/dvb/frontend.h
@@ -554,10 +554,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] 27+ messages in thread
* [PATCH 08/15] media: fe_property_parameters.rst: better define properties usage
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (6 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 07/15] media: dvb frontend docs: use kernel-doc documentation Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 09/15] media: fe_property_parameters.rst: better document bandwidth Mauro Carvalho Chehab
` (7 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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] 27+ messages in thread
* [PATCH 09/15] media: fe_property_parameters.rst: better document bandwidth
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (7 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 08/15] media: fe_property_parameters.rst: better define properties usage Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 10/15] media: dmx.h: get rid of unused DMX_KERNEL_CLIENT Mauro Carvalho Chehab
` (6 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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] 27+ messages in thread
* [PATCH 10/15] media: dmx.h: get rid of unused DMX_KERNEL_CLIENT
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (8 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 09/15] media: fe_property_parameters.rst: better document bandwidth Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 11/15] media: dmx.h: get rid of DMX_GET_CAPS Mauro Carvalho Chehab
` (5 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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 427e4899ed69..d4934e650e6b 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -105,7 +105,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] 27+ messages in thread
* [PATCH 11/15] media: dmx.h: get rid of DMX_GET_CAPS
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (9 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 10/15] media: dmx.h: get rid of unused DMX_KERNEL_CLIENT Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE Mauro Carvalho Chehab
` (4 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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 | 6 ----
5 files changed, 61 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 d4934e650e6b..c0ee44fbdb13 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -117,11 +117,6 @@ struct dmx_pes_filter_params
__u32 flags;
};
-typedef struct dmx_caps {
- __u32 caps;
- int num_decoders;
-} dmx_caps_t;
-
typedef enum dmx_source {
DMX_SOURCE_FRONT0 = 0,
DMX_SOURCE_FRONT1,
@@ -145,7 +140,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, dmx_caps_t)
#define DMX_SET_SOURCE _IOW('o', 49, dmx_source_t)
#define DMX_GET_STC _IOWR('o', 50, struct dmx_stc)
#define DMX_ADD_PID _IOW('o', 51, __u16)
--
2.13.5
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (10 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 11/15] media: dmx.h: get rid of DMX_GET_CAPS Mauro Carvalho Chehab
@ 2017-08-31 23:46 ` Mauro Carvalho Chehab
2017-09-01 6:28 ` Honza Petrouš
2017-08-31 23:47 ` [PATCH 13/15] media: dmx.h: get rid of GET_DMX_EVENT Mauro Carvalho Chehab
` (3 subsequent siblings)
15 siblings, 1 reply; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:46 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 c0ee44fbdb13..dd2b832c02ce 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -117,17 +117,6 @@ struct dmx_pes_filter_params
__u32 flags;
};
-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;
-
struct dmx_stc {
unsigned int num; /* input : which STC? 0..N */
unsigned int base; /* output: divisor for stc to get 90 kHz clock */
@@ -140,7 +129,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, dmx_source_t)
#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)
--
2.13.5
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [PATCH 13/15] media: dmx.h: get rid of GET_DMX_EVENT
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (11 preceding siblings ...)
2017-08-31 23:46 ` [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE Mauro Carvalho Chehab
@ 2017-08-31 23:47 ` Mauro Carvalho Chehab
2017-08-31 23:47 ` [PATCH 14/15] media: dmx.h: add kernel-doc markups and use it at Documentation/ Mauro Carvalho Chehab
` (2 subsequent siblings)
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:47 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] 27+ messages in thread
* [PATCH 14/15] media: dmx.h: add kernel-doc markups and use it at Documentation/
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (12 preceding siblings ...)
2017-08-31 23:47 ` [PATCH 13/15] media: dmx.h: get rid of GET_DMX_EVENT Mauro Carvalho Chehab
@ 2017-08-31 23:47 ` Mauro Carvalho Chehab
2017-08-31 23:47 ` [PATCH 15/15] media: net.rst: Fix the level of a section of the net chapter Mauro Carvalho Chehab
2017-09-01 8:40 ` [PATCH 00/15] Improve DVB documentation and reduce its gap Honza Petrouš
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:47 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 | 152 +++++++++++++++++++------
3 files changed, 127 insertions(+), 203 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 dd2b832c02ce..8357885fc11c 100644
--- a/include/uapi/linux/dvb/dmx.h
+++ b/include/uapi/linux/dvb/dmx.h
@@ -32,28 +32,73 @@
#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
};
-typedef enum dmx_output dmx_output_t;
-
-typedef enum dmx_input
-{
- DMX_IN_FRONTEND, /* Input from a front-end device. */
- DMX_IN_DVR /* Input from the logical DVR device. */
-} dmx_input_t;
+/**
+ * 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.
+ */
-typedef enum dmx_ts_pes
-{
+enum dmx_ts_pes {
DMX_PES_AUDIO0,
DMX_PES_VIDEO0,
DMX_PES_TELETEXT0,
@@ -79,7 +124,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,16 +133,41 @@ typedef enum dmx_ts_pes
#define DMX_PES_PCR DMX_PES_PCR0
-typedef 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];
-} dmx_filter_t;
+};
-
-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;
dmx_filter_t filter;
__u32 timeout;
@@ -107,9 +177,17 @@ struct dmx_sct_filter_params
#define DMX_IMMEDIATE_START 4
};
-
-struct dmx_pes_filter_params
-{
+/**
+ * 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;
dmx_input_t input;
dmx_output_t output;
@@ -117,12 +195,24 @@ 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;
};
+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;
+
#define DMX_START _IO('o', 41)
#define DMX_STOP _IO('o', 42)
#define DMX_SET_FILTER _IOW('o', 43, struct dmx_sct_filter_params)
--
2.13.5
^ permalink raw reply related [flat|nested] 27+ messages in thread
* [PATCH 15/15] media: net.rst: Fix the level of a section of the net chapter
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (13 preceding siblings ...)
2017-08-31 23:47 ` [PATCH 14/15] media: dmx.h: add kernel-doc markups and use it at Documentation/ Mauro Carvalho Chehab
@ 2017-08-31 23:47 ` Mauro Carvalho Chehab
2017-09-01 8:40 ` [PATCH 00/15] Improve DVB documentation and reduce its gap Honza Petrouš
15 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-08-31 23:47 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] 27+ messages in thread
* Re: [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE
2017-08-31 23:46 ` [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE Mauro Carvalho Chehab
@ 2017-09-01 6:28 ` Honza Petrouš
2017-09-01 9:37 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 27+ messages in thread
From: Honza Petrouš @ 2017-09-01 6:28 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-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 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 c0ee44fbdb13..dd2b832c02ce 100644
> --- a/include/uapi/linux/dvb/dmx.h
> +++ b/include/uapi/linux/dvb/dmx.h
> @@ -117,17 +117,6 @@ struct dmx_pes_filter_params
> __u32 flags;
> };
>
> -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;
> -
> struct dmx_stc {
> unsigned int num; /* input : which STC? 0..N */
> unsigned int base; /* output: divisor for stc to get 90 kHz clock */
> @@ -140,7 +129,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, dmx_source_t)
> #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)
> --
> 2.13.5
>
Hi Mauro.
May be I missed something, but how it should be managed the demux
source without that?
Do we have some other way how to set the demux input?
Even in one-frontend configuration we should have to have option
to switch between DMX_SOURCE_FRONT0 & DMX_SOURCE_DVR0.
/Honza
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 00/15] Improve DVB documentation and reduce its gap
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
` (14 preceding siblings ...)
2017-08-31 23:47 ` [PATCH 15/15] media: net.rst: Fix the level of a section of the net chapter Mauro Carvalho Chehab
@ 2017-09-01 8:40 ` Honza Petrouš
2017-09-01 9:32 ` Mauro Carvalho Chehab
15 siblings, 1 reply; 27+ messages in thread
From: Honza Petrouš @ 2017-09-01 8:40 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Masahiro Yamada, Shuah Khan, Ingo Molnar, Max Kellermann,
Sakari Ailus, Colin Ian King
2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 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 that I'll try to address when I
> have some time[1].
>
> [1] There's a gap also on the legacy audio, video and OSD APIs,
> but, as those are used only by a single very old deprecated
> hardware (av7110), it is probably not worth the efforts.
>
I agree that av7110 is very very old piece of hw (but it is already
in my hall of fame because of its Skystar 1 incarnation as
first implementation of DVB in Linux) and it is sad that we still
don't have at least one driver for any SoC with embedded DVB
devices.
I understand that the main issue is that no any DVB-enabled
SoC vendor is interested in upstreaming theirs code, but I still hope
it will change in near future(*)
Without having full-featured DVB device in vanilla, we surely don't
get some parts of DVB API covered. I can imagine that when
somebody comes with such full-featured device he wants to reinvent
just removed bits.
It's my 5 cents
/Honza
(*) My favourite is HiSilicon with very nice Hi3798 4K chip
with announced support from Linaro and already available
devboard for reasonable price.
PS: I'm in no any way connected with HiSilicon nor
any other DVB-enabled SoC vendor.
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 00/15] Improve DVB documentation and reduce its gap
2017-09-01 8:40 ` [PATCH 00/15] Improve DVB documentation and reduce its gap Honza Petrouš
@ 2017-09-01 9:32 ` Mauro Carvalho Chehab
2017-09-04 0:55 ` Soeren Moch
0 siblings, 1 reply; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 9:32 UTC (permalink / raw)
To: Honza Petrouš
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Masahiro Yamada, Shuah Khan, Ingo Molnar, Max Kellermann,
Sakari Ailus, Colin Ian King
Em Fri, 1 Sep 2017 10:40:28 +0200
Honza Petrouš <jpetrous@gmail.com> escreveu:
> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> > 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 that I'll try to address when I
> > have some time[1].
> >
> > [1] There's a gap also on the legacy audio, video and OSD APIs,
> > but, as those are used only by a single very old deprecated
> > hardware (av7110), it is probably not worth the efforts.
> >
>
> I agree that av7110 is very very old piece of hw (but it is already
> in my hall of fame because of its Skystar 1 incarnation as
> first implementation of DVB in Linux) and it is sad that we still
> don't have at least one driver for any SoC with embedded DVB
> devices.
Yeah, av7110 made history. Please notice that this series doesn't
remove any API that it is used by it. All it removes are the APIs
that there's no Kernel driver using.
Carry on APIs without client is usually a very bad idea, as nobody
could be certain about how to use it. It is even worse when such
APIs are not properly documented (with is the case here).
> I understand that the main issue is that no any DVB-enabled
> SoC vendor is interested in upstreaming theirs code, but I still hope
> it will change in near future(*)
We have one driver for a SoC DVB hardware at:
drivers/media/platform/sti/c8sectpfe/
I guess it still doesn't cover the entire SoC, but this is a WiP. If I
remember well, at the midia part of the SoC, they started by submitting
the Remote Controller code.
> Without having full-featured DVB device in vanilla, we surely don't
> get some parts of DVB API covered. I can imagine that when
> somebody comes with such full-featured device he wants to reinvent
> just removed bits.
Re-adding the removed bits is easy. However, the API defined for
av7110 is old and it is showing its age: it assumes a limited number
of possible inputs/outputs. Modern SoC has a lot more ways link the
audio/video IP blocks than what the API provides. On a modern SoC,
not only DVB is supported, but also analog inputs (to support things
like composite input), cameras, HDMI inputs and even analog TV.
All of them interconnected to a media ISP. The current FF API can't
represent such hardware.
The best API to represent those pipelines that exist on SoC for
multimedia is the media controller, where all IP blocks and their
links (whatever they are) can be represented, if needed.
The audio and video DVB API is also too limited: it hasn't
evolved since when it was added. For audio, the ALSA API
allows a way more control of the hardware; for video, the
V4L2 API nowadays has all the bits to control video decoding
and encoding. Both APIs provide support for audio and video
inputs commonly found on those devices.
Also, nowadays, video decoding usually happens at the GPU on SoC. So,
in practice, a SoC FF would likely use the DRM subsystem to control the
video codecs.
So, anyone wanting to upstream drivers for a modern FF hardware would need
to touch a lot inside the DVB API, for it to cover all the needs. A more
appropriate approach to support those devices would be, instead,
to use a set of APIs: DVB, V4L2, ALSA, RC, CEC, MC, DRM.
>
> It's my 5 cents
> /Honza
>
> (*) My favourite is HiSilicon with very nice Hi3798 4K chip
> with announced support from Linaro and already available
> devboard for reasonable price.
>
> PS: I'm in no any way connected with HiSilicon nor
> any other DVB-enabled SoC vendor.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE
2017-09-01 6:28 ` Honza Petrouš
@ 2017-09-01 9:37 ` Mauro Carvalho Chehab
2017-09-01 9:53 ` Honza Petrouš
0 siblings, 1 reply; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 9:37 UTC (permalink / raw)
To: Honza Petrouš
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
Em Fri, 1 Sep 2017 08:28:20 +0200
Honza Petrouš <jpetrous@gmail.com> escreveu:
> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> > 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 c0ee44fbdb13..dd2b832c02ce 100644
> > --- a/include/uapi/linux/dvb/dmx.h
> > +++ b/include/uapi/linux/dvb/dmx.h
> > @@ -117,17 +117,6 @@ struct dmx_pes_filter_params
> > __u32 flags;
> > };
> >
> > -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;
> > -
> > struct dmx_stc {
> > unsigned int num; /* input : which STC? 0..N */
> > unsigned int base; /* output: divisor for stc to get 90 kHz clock */
> > @@ -140,7 +129,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, dmx_source_t)
> > #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)
> > --
> > 2.13.5
> >
>
> Hi Mauro.
>
> May be I missed something, but how it should be managed the demux
> source without that?
> Do we have some other way how to set the demux input?
Yes: via the media controller.
> Even in one-frontend configuration we should have to have option
> to switch between DMX_SOURCE_FRONT0 & DMX_SOURCE_DVR0.
Actually, the sources are configured when a filter is set. I've
no idea what was the original purpose of this API, as there's no
documentation about it anywhere and no drivers use it kernelwide.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE
2017-09-01 9:37 ` Mauro Carvalho Chehab
@ 2017-09-01 9:53 ` Honza Petrouš
2017-09-01 10:45 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 27+ messages in thread
From: Honza Petrouš @ 2017-09-01 9:53 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-01 11:37 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> Em Fri, 1 Sep 2017 08:28:20 +0200
> Honza Petrouš <jpetrous@gmail.com> escreveu:
>
>> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> > 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 c0ee44fbdb13..dd2b832c02ce 100644
>> > --- a/include/uapi/linux/dvb/dmx.h
>> > +++ b/include/uapi/linux/dvb/dmx.h
>> > @@ -117,17 +117,6 @@ struct dmx_pes_filter_params
>> > __u32 flags;
>> > };
>> >
>> > -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;
>> > -
>> > struct dmx_stc {
>> > unsigned int num; /* input : which STC? 0..N */
>> > unsigned int base; /* output: divisor for stc to get 90 kHz clock */
>> > @@ -140,7 +129,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, dmx_source_t)
>> > #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)
>> > --
>> > 2.13.5
>> >
>>
>> Hi Mauro.
>>
>> May be I missed something, but how it should be managed the demux
>> source without that?
>> Do we have some other way how to set the demux input?
>
> Yes: via the media controller.
>
>> Even in one-frontend configuration we should have to have option
>> to switch between DMX_SOURCE_FRONT0 & DMX_SOURCE_DVR0.
>
> Actually, the sources are configured when a filter is set. I've
Do you mean in DMX_SET_FILTER?
I don't see any way how to do it inside struct:
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
#define DMX_KERNEL_CLIENT 0x8000
};
And more - I don't see any reason why it should be done in filter set.
It looks for me like superfluous side-effect. The setting
of the demux source should not be connected with filter setup.
> no idea what was the original purpose of this API, as there's no
> documentation about it anywhere and no drivers use it kernelwide.
If I remember correctly, the original idea (or at least how I remember it) was
to switch source of TS data - from frontend or from dvr (injecting
from userspace).
/Honza
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE
2017-09-01 9:53 ` Honza Petrouš
@ 2017-09-01 10:45 ` Mauro Carvalho Chehab
2017-09-01 11:14 ` Honza Petrouš
0 siblings, 1 reply; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 10:45 UTC (permalink / raw)
To: Honza Petrouš
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
Em Fri, 1 Sep 2017 11:53:11 +0200
Honza Petrouš <jpetrous@gmail.com> escreveu:
> 2017-09-01 11:37 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> > Em Fri, 1 Sep 2017 08:28:20 +0200
> > Honza Petrouš <jpetrous@gmail.com> escreveu:
> >
> >> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >> > 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 c0ee44fbdb13..dd2b832c02ce 100644
> >> > --- a/include/uapi/linux/dvb/dmx.h
> >> > +++ b/include/uapi/linux/dvb/dmx.h
> >> > @@ -117,17 +117,6 @@ struct dmx_pes_filter_params
> >> > __u32 flags;
> >> > };
> >> >
> >> > -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;
> >> > -
> >> > struct dmx_stc {
> >> > unsigned int num; /* input : which STC? 0..N */
> >> > unsigned int base; /* output: divisor for stc to get 90 kHz clock */
> >> > @@ -140,7 +129,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, dmx_source_t)
> >> > #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)
> >> > --
> >> > 2.13.5
> >> >
> >>
> >> Hi Mauro.
> >>
> >> May be I missed something, but how it should be managed the demux
> >> source without that?
> >> Do we have some other way how to set the demux input?
> >
> > Yes: via the media controller.
> >
> >> Even in one-frontend configuration we should have to have option
> >> to switch between DMX_SOURCE_FRONT0 & DMX_SOURCE_DVR0.
> >
> > Actually, the sources are configured when a filter is set. I've
>
> Do you mean in DMX_SET_FILTER?
>
> I don't see any way how to do it inside struct:
>
> 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
> #define DMX_KERNEL_CLIENT 0x8000
> };
No, I'm actually talking about DMX_SET_PES_FILTER filter:
struct dmx_pes_filter_params
{
__u16 pid;
enum dmx_input input;
enum dmx_output output;
enum dmx_ts_pes pes_type;
__u32 flags;
};
it explicitly allows setting both input and output, per PES filter.
> And more - I don't see any reason why it should be done in filter set.
> It looks for me like superfluous side-effect. The setting
> of the demux source should not be connected with filter setup.
>
> > no idea what was the original purpose of this API, as there's no
> > documentation about it anywhere and no drivers use it kernelwide.
>
> If I remember correctly, the original idea (or at least how I remember it) was
> to switch source of TS data - from frontend or from dvr (injecting
> from userspace).
Well, nobody implemented it (at least upstream).
Thanks,
Mauro
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE
2017-09-01 10:45 ` Mauro Carvalho Chehab
@ 2017-09-01 11:14 ` Honza Petrouš
2017-09-01 13:06 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 27+ messages in thread
From: Honza Petrouš @ 2017-09-01 11:14 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-01 12:45 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> Em Fri, 1 Sep 2017 11:53:11 +0200
> Honza Petrouš <jpetrous@gmail.com> escreveu:
>
>> 2017-09-01 11:37 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> > Em Fri, 1 Sep 2017 08:28:20 +0200
>> > Honza Petrouš <jpetrous@gmail.com> escreveu:
>> >
>> >> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>> >> > 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 c0ee44fbdb13..dd2b832c02ce 100644
>> >> > --- a/include/uapi/linux/dvb/dmx.h
>> >> > +++ b/include/uapi/linux/dvb/dmx.h
>> >> > @@ -117,17 +117,6 @@ struct dmx_pes_filter_params
>> >> > __u32 flags;
>> >> > };
>> >> >
>> >> > -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;
>> >> > -
>> >> > struct dmx_stc {
>> >> > unsigned int num; /* input : which STC? 0..N */
>> >> > unsigned int base; /* output: divisor for stc to get 90 kHz clock */
>> >> > @@ -140,7 +129,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, dmx_source_t)
>> >> > #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)
>> >> > --
>> >> > 2.13.5
>> >> >
>> >>
>> >> Hi Mauro.
>> >>
>> >> May be I missed something, but how it should be managed the demux
>> >> source without that?
>> >> Do we have some other way how to set the demux input?
>> >
>> > Yes: via the media controller.
>> >
>> >> Even in one-frontend configuration we should have to have option
>> >> to switch between DMX_SOURCE_FRONT0 & DMX_SOURCE_DVR0.
>> >
>> > Actually, the sources are configured when a filter is set. I've
>>
>> Do you mean in DMX_SET_FILTER?
>>
>> I don't see any way how to do it inside struct:
>>
>> 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
>> #define DMX_KERNEL_CLIENT 0x8000
>> };
>
>
> No, I'm actually talking about DMX_SET_PES_FILTER filter:
>
> struct dmx_pes_filter_params
> {
> __u16 pid;
> enum dmx_input input;
> enum dmx_output output;
> enum dmx_ts_pes pes_type;
> __u32 flags;
> };
>
> it explicitly allows setting both input and output, per PES filter.
Sure, but ONLY for PES filtering. The sections are out of business.
Let me again note that doing demux source switch as side-effectr of
setting PES filter looks more then strange. More logical looks
the possibility to switch source independently (DMX_SET_SOURCE).
Of course, it is only my POV.
/Honza
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE
2017-09-01 11:14 ` Honza Petrouš
@ 2017-09-01 13:06 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-01 13:06 UTC (permalink / raw)
To: Honza Petrouš
Cc: Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet
Em Fri, 1 Sep 2017 13:14:04 +0200
Honza Petrouš <jpetrous@gmail.com> escreveu:
> 2017-09-01 12:45 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> > Em Fri, 1 Sep 2017 11:53:11 +0200
> > Honza Petrouš <jpetrous@gmail.com> escreveu:
> >
> >> 2017-09-01 11:37 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >> > Em Fri, 1 Sep 2017 08:28:20 +0200
> >> > Honza Petrouš <jpetrous@gmail.com> escreveu:
> >> >
> >> >> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >> >> > 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 c0ee44fbdb13..dd2b832c02ce 100644
> >> >> > --- a/include/uapi/linux/dvb/dmx.h
> >> >> > +++ b/include/uapi/linux/dvb/dmx.h
> >> >> > @@ -117,17 +117,6 @@ struct dmx_pes_filter_params
> >> >> > __u32 flags;
> >> >> > };
> >> >> >
> >> >> > -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;
> >> >> > -
> >> >> > struct dmx_stc {
> >> >> > unsigned int num; /* input : which STC? 0..N */
> >> >> > unsigned int base; /* output: divisor for stc to get 90 kHz clock */
> >> >> > @@ -140,7 +129,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, dmx_source_t)
> >> >> > #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)
> >> >> > --
> >> >> > 2.13.5
> >> >> >
> >> >>
> >> >> Hi Mauro.
> >> >>
> >> >> May be I missed something, but how it should be managed the demux
> >> >> source without that?
> >> >> Do we have some other way how to set the demux input?
> >> >
> >> > Yes: via the media controller.
> >> >
> >> >> Even in one-frontend configuration we should have to have option
> >> >> to switch between DMX_SOURCE_FRONT0 & DMX_SOURCE_DVR0.
> >> >
> >> > Actually, the sources are configured when a filter is set. I've
> >>
> >> Do you mean in DMX_SET_FILTER?
> >>
> >> I don't see any way how to do it inside struct:
> >>
> >> 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
> >> #define DMX_KERNEL_CLIENT 0x8000
> >> };
> >
> >
> > No, I'm actually talking about DMX_SET_PES_FILTER filter:
> >
> > struct dmx_pes_filter_params
> > {
> > __u16 pid;
> > enum dmx_input input;
> > enum dmx_output output;
> > enum dmx_ts_pes pes_type;
> > __u32 flags;
> > };
> >
> > it explicitly allows setting both input and output, per PES filter.
>
> Sure, but ONLY for PES filtering. The sections are out of business.
>
> Let me again note that doing demux source switch as side-effectr of
> setting PES filter looks more then strange. More logical looks
> the possibility to switch source independently (DMX_SET_SOURCE).
>
> Of course, it is only my POV.
Yeah, I agree, but it is too late to change it ;)
Both Kernelspace and userspace apps rely on such behavior.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 00/15] Improve DVB documentation and reduce its gap
2017-09-01 9:32 ` Mauro Carvalho Chehab
@ 2017-09-04 0:55 ` Soeren Moch
2017-09-04 11:29 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 27+ messages in thread
From: Soeren Moch @ 2017-09-04 0:55 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Honza Petrouš,
Linux Doc Mailing List, Linux Media Mailing List,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Masahiro Yamada, Shuah Khan, Ingo Molnar, Max Kellermann,
Sakari Ailus, Colin Ian King
Hi Mauro,
On 01.09.2017 11:32, Mauro Carvalho Chehab wrote:
> Em Fri, 1 Sep 2017 10:40:28 +0200
> Honza Petrouš <jpetrous@gmail.com> escreveu:
>
>> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>> 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 that I'll try to address when I
>>> have some time[1].
>>>
>>> [1] There's a gap also on the legacy audio, video and OSD APIs,
>>> but, as those are used only by a single very old deprecated
>>> hardware (av7110), it is probably not worth the efforts.
>>>
av7110 cards may be old, but there are still users of these cards. For
instance I'm watching TV received and decoded with such card in this moment.
So what do you mean with "deprecated hardware"?
>> I agree that av7110 is very very old piece of hw (but it is already
>> in my hall of fame because of its Skystar 1 incarnation as
>> first implementation of DVB in Linux) and it is sad that we still
>> don't have at least one driver for any SoC with embedded DVB
>> devices.
> Yeah, av7110 made history. Please notice that this series doesn't
> remove any API that it is used by it. All it removes are the APIs
> that there's no Kernel driver using.
>
> Carry on APIs without client is usually a very bad idea, as nobody
> could be certain about how to use it. It is even worse when such
> APIs are not properly documented (with is the case here).
>
>> I understand that the main issue is that no any DVB-enabled
>> SoC vendor is interested in upstreaming theirs code, but I still hope
>> it will change in near future(*)
> We have one driver for a SoC DVB hardware at:
> drivers/media/platform/sti/c8sectpfe/
>
> I guess it still doesn't cover the entire SoC, but this is a WiP. If I
> remember well, at the midia part of the SoC, they started by submitting
> the Remote Controller code.
>
>> Without having full-featured DVB device in vanilla, we surely don't
>> get some parts of DVB API covered. I can imagine that when
>> somebody comes with such full-featured device he wants to reinvent
>> just removed bits.
> Re-adding the removed bits is easy. However, the API defined for
> av7110 is old and it is showing its age: it assumes a limited number
> of possible inputs/outputs. Modern SoC has a lot more ways link the
> audio/video IP blocks than what the API provides. On a modern SoC,
> not only DVB is supported, but also analog inputs (to support things
> like composite input), cameras, HDMI inputs and even analog TV.
> All of them interconnected to a media ISP. The current FF API can't
> represent such hardware.
>
> The best API to represent those pipelines that exist on SoC for
> multimedia is the media controller, where all IP blocks and their
> links (whatever they are) can be represented, if needed.
>
> The audio and video DVB API is also too limited: it hasn't
> evolved since when it was added. For audio, the ALSA API
> allows a way more control of the hardware; for video, the
> V4L2 API nowadays has all the bits to control video decoding
> and encoding. Both APIs provide support for audio and video
> inputs commonly found on those devices.
The real advantage of the DVB audio/video/osd API is the possibility
of frame synchronous audio/video/overlay output for high-quality
audio/video playback, maybe with picture-in-picture functionality.
Especially audio synchronization is not easy when the audio format
changes from compressed audio (e.g. AC-3) to PCM (stereo), e.g. on
HDMI output. While HDMI output hardware usually takes video frames and
audio packets (and AVI info frames for audio/video format signalization)
synchronously, V4L2 and ALSA rip these data blocks apart and push these
through different pipelines with different buffering properties. This
makes it very difficult for userspace applications. With the DVB API
the hardware takes care of the synchronisation.
> Also, nowadays, video decoding usually happens at the GPU on SoC. So,
> in practice, a SoC FF would likely use the DRM subsystem to control the
> video codecs.
I think this is a common misunderstanding. Video is decoded on separate
hardware blocks nowadays, not on a (3D-)GPU. GPU vendors like to hide this
fact by declaring all blocks together as GPU, but in SoC architectures
like e.g. imx, sunxi, or meson one can easily see separate 2D-GPU, 3D-GPU,
video codec and image processing / video output blocks.
On imx6q for instance we use etnaviv 2D- and 3D-GPU drivers, a coda
video decoder driver, and ipu-v3 video output drivers. While etnaviv and
ipu-v3 are gpu/drm drivers, the coda video decoder is a media/platform
device and not integrated into the drm framework.
> So, anyone wanting to upstream drivers for a modern FF hardware would need
> to touch a lot inside the DVB API, for it to cover all the needs. A more
> appropriate approach to support those devices would be, instead,
> to use a set of APIs: DVB, V4L2, ALSA, RC, CEC, MC, DRM.
You know I want to upstream a driver for (not so modern) FF hardware, with
the DVB audio/video API and without touching anything inside this API (small
additions to the osd API). I still hope this driver can be accepted.
I fully understand the desire for new APIs to support modern hardware
with additional needs. As kernel developer I also understand that it is
easier to create new APIs instead of extending the exiting ones.
As application programmer instead I would prefer to stick with existing
APIs, at least to get some compatibility lib if older APIs are deprecated
and replaced with newer ones.
It is especially confusing for me to see a lot of new APIs with overlapping
scope. The same functionality is handled by different APIs, why?
You mentioned above, video codecs should be handled by DRM, are V4L2
decoder drivers also deprecated?
Video scaling is usually handled by the DRM output pipeline. This is
efficient
since the image is read only once. For instance on imx6 we have a V4L2
mem2mem
scaler instead.
Video output (including overlays) seems to be handled by DRM nowadays, video
input by MC. The whole media subsystem seems not to have any business with
audio anymore. Is the whole V4L2 API superseded by something else?
As you have worked a lot on documentation recently, can you point me to some
documentation how the different APIs are supposed to work together? What API
to use when?
Thanks,
Soeren
>
>> It's my 5 cents
>> /Honza
>>
>> (*) My favourite is HiSilicon with very nice Hi3798 4K chip
>> with announced support from Linaro and already available
>> devboard for reasonable price.
>>
>> PS: I'm in no any way connected with HiSilicon nor
>> any other DVB-enabled SoC vendor.
> Thanks,
> Mauro
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 00/15] Improve DVB documentation and reduce its gap
2017-09-04 0:55 ` Soeren Moch
@ 2017-09-04 11:29 ` Mauro Carvalho Chehab
2017-09-09 12:49 ` Soeren Moch
0 siblings, 1 reply; 27+ messages in thread
From: Mauro Carvalho Chehab @ 2017-09-04 11:29 UTC (permalink / raw)
To: Soeren Moch
Cc: Mauro Carvalho Chehab, Honza Petrouš,
Linux Doc Mailing List, Linux Media Mailing List, linux-kernel,
Jonathan Corbet, Masahiro Yamada, Shuah Khan, Ingo Molnar,
Max Kellermann, Sakari Ailus, Colin Ian King
Em Mon, 4 Sep 2017 02:55:15 +0200
Soeren Moch <smoch@web.de> escreveu:
> Hi Mauro,
>
> On 01.09.2017 11:32, Mauro Carvalho Chehab wrote:
> > Em Fri, 1 Sep 2017 10:40:28 +0200
> > Honza Petrouš <jpetrous@gmail.com> escreveu:
> >
> >> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> >>> 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 that I'll try to address when I
> >>> have some time[1].
> >>>
> >>> [1] There's a gap also on the legacy audio, video and OSD APIs,
> >>> but, as those are used only by a single very old deprecated
> >>> hardware (av7110), it is probably not worth the efforts.
> >>>
> av7110 cards may be old, but there are still users of these cards.
> For instance I'm watching TV received and decoded with such card in this moment.
> So what do you mean with "deprecated hardware"?
Nobody is telling otherwise. What I mean by "deprecated" is that it is
not a product that you could got to a shop and buy a new one. Its
production stopped a long time ago.
> >> I agree that av7110 is very very old piece of hw (but it is already
> >> in my hall of fame because of its Skystar 1 incarnation as
> >> first implementation of DVB in Linux) and it is sad that we still
> >> don't have at least one driver for any SoC with embedded DVB
> >> devices.
> > Yeah, av7110 made history. Please notice that this series doesn't
> > remove any API that it is used by it. All it removes are the APIs
> > that there's no Kernel driver using.
> >
> > Carry on APIs without client is usually a very bad idea, as nobody
> > could be certain about how to use it. It is even worse when such
> > APIs are not properly documented (with is the case here).
> >
> >> I understand that the main issue is that no any DVB-enabled
> >> SoC vendor is interested in upstreaming theirs code, but I still hope
> >> it will change in near future(*)
> > We have one driver for a SoC DVB hardware at:
> > drivers/media/platform/sti/c8sectpfe/
> >
> > I guess it still doesn't cover the entire SoC, but this is a WiP. If I
> > remember well, at the midia part of the SoC, they started by submitting
> > the Remote Controller code.
> >
> >> Without having full-featured DVB device in vanilla, we surely don't
> >> get some parts of DVB API covered. I can imagine that when
> >> somebody comes with such full-featured device he wants to reinvent
> >> just removed bits.
> > Re-adding the removed bits is easy. However, the API defined for
> > av7110 is old and it is showing its age: it assumes a limited number
> > of possible inputs/outputs. Modern SoC has a lot more ways link the
> > audio/video IP blocks than what the API provides. On a modern SoC,
> > not only DVB is supported, but also analog inputs (to support things
> > like composite input), cameras, HDMI inputs and even analog TV.
> > All of them interconnected to a media ISP. The current FF API can't
> > represent such hardware.
> >
> > The best API to represent those pipelines that exist on SoC for
> > multimedia is the media controller, where all IP blocks and their
> > links (whatever they are) can be represented, if needed.
> >
> > The audio and video DVB API is also too limited: it hasn't
> > evolved since when it was added. For audio, the ALSA API
> > allows a way more control of the hardware; for video, the
> > V4L2 API nowadays has all the bits to control video decoding
> > and encoding. Both APIs provide support for audio and video
> > inputs commonly found on those devices.
> The real advantage of the DVB audio/video/osd API is the possibility
> of frame synchronous audio/video/overlay output for high-quality
> audio/video playback, maybe with picture-in-picture functionality.
>
> Especially audio synchronization is not easy when the audio format
> changes from compressed audio (e.g. AC-3) to PCM (stereo), e.g. on
> HDMI output. While HDMI output hardware usually takes video frames and
> audio packets (and AVI info frames for audio/video format signalization)
> synchronously, V4L2 and ALSA rip these data blocks apart and push these
> through different pipelines with different buffering properties. This
> makes it very difficult for userspace applications. With the DVB API
> the hardware takes care of the synchronisation.
Since ever, V4L2 metadata carries both a timestamp and a frame number. On
ALSA, support for it is more complex, and was discussed for a while.
I'm not sure about the current status, but I guess timestamp suppot was
already added due to compressed audio requirements.
> > Also, nowadays, video decoding usually happens at the GPU on SoC. So,
> > in practice, a SoC FF would likely use the DRM subsystem to control the
> > video codecs.
> I think this is a common misunderstanding. Video is decoded on separate
> hardware blocks nowadays, not on a (3D-)GPU. GPU vendors like to hide this
> fact by declaring all blocks together as GPU, but in SoC architectures
> like e.g. imx, sunxi, or meson one can easily see separate 2D-GPU, 3D-GPU,
> video codec and image processing / video output blocks.
> On imx6q for instance we use etnaviv 2D- and 3D-GPU drivers, a coda
> video decoder driver, and ipu-v3 video output drivers. While etnaviv and
> ipu-v3 are gpu/drm drivers, the coda video decoder is a media/platform
> device and not integrated into the drm framework.
Yeah, the codecs are implemented by a separated IP block (usually a
media DSP), with may be firmware updated. They're usually separated from
2D or 3D IP blocks. Yet, from control/streaming PoV, they're usually
controlled via GL though the DRM subsystem. V4L2 also has support
for such codecs. There are even some solutions on embedded where the
2D/3D/codecs are on a separate chip from the SoC.
> > So, anyone wanting to upstream drivers for a modern FF hardware would need
> > to touch a lot inside the DVB API, for it to cover all the needs. A more
> > appropriate approach to support those devices would be, instead,
> > to use a set of APIs: DVB, V4L2, ALSA, RC, CEC, MC, DRM.
> You know I want to upstream a driver for (not so modern) FF hardware, with
> the DVB audio/video API and without touching anything inside this API (small
> additions to the osd API). I still hope this driver can be accepted.
That has nothing to do with this patch series. The goal here is just to
synchronize the documentation with the current DVB implementation upstream,
specially for the ioctls that all drivers implement.
> I fully understand the desire for new APIs to support modern hardware
> with additional needs. As kernel developer I also understand that it is
> easier to create new APIs instead of extending the exiting ones.
> As application programmer instead I would prefer to stick with existing
> APIs, at least to get some compatibility lib if older APIs are deprecated
> and replaced with newer ones.
>
> It is especially confusing for me to see a lot of new APIs with overlapping
> scope. The same functionality is handled by different APIs, why?
Historic reasons. The addition of audio/video at DVB is one such
example: by the time it was written, there were already ALSA (and OSS),
plus V4L2 (and V4L).
I don't know if you're aware, but, in the early days, it was possible to
control some DVB devices via V4L2. On that time, for some hardware,
there was two drivers for DVB: one inside video4linux and another one
inside dvb directories. Such support got removed, as it was an abberation.
> You mentioned above, video codecs should be handled by DRM, are V4L2
> decoder drivers also deprecated?
V4L2 mem2mem drivers provide a different feature than DRM. On DRM,
a video plane is set to receive, let's say, a MPEG4 stream to be
displayed, usually controlled by GL; on V4L2, the MPEG4 would be converted
to some other format and returned back to userspace (for example, to be
recorded).
Yeah, there are some overlay between them, but it is usually clear
when one should add support to DRM or V4L2.
> Video scaling is usually handled by the DRM output pipeline. This is
> efficient
> since the image is read only once. For instance on imx6 we have a V4L2
> mem2mem
> scaler instead.
It is as efficient to use DRM or V4L2, as both support DMABUF. So,
either way, is possible to do zero-copy data transfers.
> Video output (including overlays) seems to be handled by DRM nowadays, video
> input by MC.
No, MC doesn't handle video buffers. It is meant to just set hardware
pipelines. Ok, in the case of a full featured DVB hardware, if you're
not interested on recording, it would be possible to use MC to setup a
pipeline that would set audio and video decoding pipelines without
the need of any data copies. Yet, you may still need to use other
APIs, in order to syncronize A/V with external things (like a teletext
overlay, or some popup menu).
> The whole media subsystem seems not to have any business with
> audio anymore. Is the whole V4L2 API superseded by something else?
It never had. V4L2 can control audio settings (like language selection
stero/mono switch, and even volume/balance), but it was never meant to
be an API for the digital audio output. Ok, on very ancient hardware, the
audio could be provided only via an analog output pin (or CD cable).
Still, on those cases, the audio is generally connected to the CD or
AUX input at the audio card, and userspace ends by controlling it via
ALSA.
> As you have worked a lot on documentation recently, can you point me to some
> documentation how the different APIs are supposed to work together? What API
> to use when?
Contributions for that are welcome.
We're still fighting to have the current DVB API documented. Before
those patches I'm working with, several parts of the DVB API documentation
are a piece of fiction, as it doesn't match what's implemented.
For example, the CA documentation used to say that the CA is
controlled via /dev/ost/ca. I was not here when DVB was added
usptream. Yet, I'd risk to say that, since when the DVB system was
merged upstream, the CA device was always /dev/adapter?/ca?.
Maybe somewhere between 1999-2001, when the subsystem were on
its early days and out of the Kernel tree, "/dev/ost/*" devnodes
were used for a while.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 27+ messages in thread
* Re: [PATCH 00/15] Improve DVB documentation and reduce its gap
2017-09-04 11:29 ` Mauro Carvalho Chehab
@ 2017-09-09 12:49 ` Soeren Moch
0 siblings, 0 replies; 27+ messages in thread
From: Soeren Moch @ 2017-09-09 12:49 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, Honza Petrouš,
Linux Doc Mailing List, Linux Media Mailing List, linux-kernel,
Jonathan Corbet, Masahiro Yamada, Shuah Khan, Ingo Molnar,
Max Kellermann, Sakari Ailus, Colin Ian King
On 04.09.2017 13:29, Mauro Carvalho Chehab wrote:
> Em Mon, 4 Sep 2017 02:55:15 +0200
> Soeren Moch <smoch@web.de> escreveu:
>
>> Hi Mauro,
>>
>> On 01.09.2017 11:32, Mauro Carvalho Chehab wrote:
>>> Em Fri, 1 Sep 2017 10:40:28 +0200
>>> Honza Petrouš <jpetrous@gmail.com> escreveu:
>>>
>>>> 2017-09-01 1:46 GMT+02:00 Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>>>> 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 that I'll try to address when I
>>>>> have some time[1].
>>>>>
>>>>> [1] There's a gap also on the legacy audio, video and OSD APIs,
>>>>> but, as those are used only by a single very old deprecated
>>>>> hardware (av7110), it is probably not worth the efforts.
>>>>>
>> av7110 cards may be old, but there are still users of these cards.
>> For instance I'm watching TV received and decoded with such card in this moment.
>> So what do you mean with "deprecated hardware"?
> Nobody is telling otherwise. What I mean by "deprecated" is that it is
> not a product that you could got to a shop and buy a new one. Its
> production stopped a long time ago.
>
>>>> I agree that av7110 is very very old piece of hw (but it is already
>>>> in my hall of fame because of its Skystar 1 incarnation as
>>>> first implementation of DVB in Linux) and it is sad that we still
>>>> don't have at least one driver for any SoC with embedded DVB
>>>> devices.
>>> Yeah, av7110 made history. Please notice that this series doesn't
>>> remove any API that it is used by it. All it removes are the APIs
>>> that there's no Kernel driver using.
>>>
>>> Carry on APIs without client is usually a very bad idea, as nobody
>>> could be certain about how to use it. It is even worse when such
>>> APIs are not properly documented (with is the case here).
>>>
>>>> I understand that the main issue is that no any DVB-enabled
>>>> SoC vendor is interested in upstreaming theirs code, but I still hope
>>>> it will change in near future(*)
>>> We have one driver for a SoC DVB hardware at:
>>> drivers/media/platform/sti/c8sectpfe/
>>>
>>> I guess it still doesn't cover the entire SoC, but this is a WiP. If I
>>> remember well, at the midia part of the SoC, they started by submitting
>>> the Remote Controller code.
>>>
>>>> Without having full-featured DVB device in vanilla, we surely don't
>>>> get some parts of DVB API covered. I can imagine that when
>>>> somebody comes with such full-featured device he wants to reinvent
>>>> just removed bits.
>>> Re-adding the removed bits is easy. However, the API defined for
>>> av7110 is old and it is showing its age: it assumes a limited number
>>> of possible inputs/outputs. Modern SoC has a lot more ways link the
>>> audio/video IP blocks than what the API provides. On a modern SoC,
>>> not only DVB is supported, but also analog inputs (to support things
>>> like composite input), cameras, HDMI inputs and even analog TV.
>>> All of them interconnected to a media ISP. The current FF API can't
>>> represent such hardware.
>>>
>>> The best API to represent those pipelines that exist on SoC for
>>> multimedia is the media controller, where all IP blocks and their
>>> links (whatever they are) can be represented, if needed.
>>>
>>> The audio and video DVB API is also too limited: it hasn't
>>> evolved since when it was added. For audio, the ALSA API
>>> allows a way more control of the hardware; for video, the
>>> V4L2 API nowadays has all the bits to control video decoding
>>> and encoding. Both APIs provide support for audio and video
>>> inputs commonly found on those devices.
>> The real advantage of the DVB audio/video/osd API is the possibility
>> of frame synchronous audio/video/overlay output for high-quality
>> audio/video playback, maybe with picture-in-picture functionality.
>>
>> Especially audio synchronization is not easy when the audio format
>> changes from compressed audio (e.g. AC-3) to PCM (stereo), e.g. on
>> HDMI output. While HDMI output hardware usually takes video frames and
>> audio packets (and AVI info frames for audio/video format signalization)
>> synchronously, V4L2 and ALSA rip these data blocks apart and push these
>> through different pipelines with different buffering properties. This
>> makes it very difficult for userspace applications. With the DVB API
>> the hardware takes care of the synchronisation.
> Since ever, V4L2 metadata carries both a timestamp and a frame number. On
> ALSA, support for it is more complex, and was discussed for a while.
> I'm not sure about the current status, but I guess timestamp suppot was
> already added due to compressed audio requirements.
That's my problem, the DVB audio/video API is deprecated, apparently
there is no other new API available which provides the same functionality.
At least for me it is not obvious, how that should work.
>>> Also, nowadays, video decoding usually happens at the GPU on SoC. So,
>>> in practice, a SoC FF would likely use the DRM subsystem to control the
>>> video codecs.
>> I think this is a common misunderstanding. Video is decoded on separate
>> hardware blocks nowadays, not on a (3D-)GPU. GPU vendors like to hide this
>> fact by declaring all blocks together as GPU, but in SoC architectures
>> like e.g. imx, sunxi, or meson one can easily see separate 2D-GPU, 3D-GPU,
>> video codec and image processing / video output blocks.
>> On imx6q for instance we use etnaviv 2D- and 3D-GPU drivers, a coda
>> video decoder driver, and ipu-v3 video output drivers. While etnaviv and
>> ipu-v3 are gpu/drm drivers, the coda video decoder is a media/platform
>> device and not integrated into the drm framework.
> Yeah, the codecs are implemented by a separated IP block (usually a
> media DSP), with may be firmware updated. They're usually separated from
> 2D or 3D IP blocks. Yet, from control/streaming PoV, they're usually
> controlled via GL though the DRM subsystem. V4L2 also has support
> for such codecs. There are even some solutions on embedded where the
> 2D/3D/codecs are on a separate chip from the SoC.
OK, that confirms my opinion. There is no common implementation
in DRM for video decoders.
As application developer I want to see a uniform new API, as it is
really painful
to support different APIs for the same functionality in different hardware.
Will video decoding be handled by DRM or V4L2 in the future?
>>> So, anyone wanting to upstream drivers for a modern FF hardware would need
>>> to touch a lot inside the DVB API, for it to cover all the needs. A more
>>> appropriate approach to support those devices would be, instead,
>>> to use a set of APIs: DVB, V4L2, ALSA, RC, CEC, MC, DRM.
>> You know I want to upstream a driver for (not so modern) FF hardware, with
>> the DVB audio/video API and without touching anything inside this API (small
>> additions to the osd API). I still hope this driver can be accepted.
> That has nothing to do with this patch series. The goal here is just to
> synchronize the documentation with the current DVB implementation upstream,
> specially for the ioctls that all drivers implement.
Agreed. But you brought up the topic of FF hardware, that would need
to "touch a lot inside the DVB API", which IMHO need not necessarily
be the case.
>> I fully understand the desire for new APIs to support modern hardware
>> with additional needs. As kernel developer I also understand that it is
>> easier to create new APIs instead of extending the exiting ones.
>> As application programmer instead I would prefer to stick with existing
>> APIs, at least to get some compatibility lib if older APIs are deprecated
>> and replaced with newer ones.
>>
>> It is especially confusing for me to see a lot of new APIs with overlapping
>> scope. The same functionality is handled by different APIs, why?
> Historic reasons. The addition of audio/video at DVB is one such
> example: by the time it was written, there were already ALSA (and OSS),
> plus V4L2 (and V4L).
>
> I don't know if you're aware, but, in the early days, it was possible to
> control some DVB devices via V4L2. On that time, for some hardware,
> there was two drivers for DVB: one inside video4linux and another one
> inside dvb directories. Such support got removed, as it was an abberation.
I also agree with that. But it looks for me, as the same problem
is getting worse. We still have, and apparently even get more
overlapping new APIs. This is not something an application developer
wants to see.
>> You mentioned above, video codecs should be handled by DRM, are V4L2
>> decoder drivers also deprecated?
> V4L2 mem2mem drivers provide a different feature than DRM. On DRM,
> a video plane is set to receive, let's say, a MPEG4 stream to be
> displayed, usually controlled by GL; on V4L2, the MPEG4 would be converted
> to some other format and returned back to userspace (for example, to be
> recorded).
>
> Yeah, there are some overlay between them, but it is usually clear
> when one should add support to DRM or V4L2.
Yes, it is clear, what is possible with the different APIs.
But sometimes I only get the wrong API implementation,
see below.
>> Video scaling is usually handled by the DRM output pipeline. This is
>> efficient
>> since the image is read only once. For instance on imx6 we have a V4L2
>> mem2mem
>> scaler instead.
> It is as efficient to use DRM or V4L2, as both support DMABUF. So,
> either way, is possible to do zero-copy data transfers.
"Zero-copy" (on the CPU) does not mean no overhead. If I have to save
and reread the scaled image, additional bus traffic is generated which
leads to unnecessary power consumption and slows down other bus
transfers. If the scaled image is directly handed over to the HDMI output,
this can be avoided.
>> Video output (including overlays) seems to be handled by DRM nowadays, video
>> input by MC.
> No, MC doesn't handle video buffers. It is meant to just set hardware
> pipelines. Ok, in the case of a full featured DVB hardware, if you're
> not interested on recording, it would be possible to use MC to setup a
> pipeline that would set audio and video decoding pipelines without
> the need of any data copies. Yet, you may still need to use other
> APIs, in order to syncronize A/V with external things (like a teletext
> overlay, or some popup menu).
Yes, OK, also for video input we need several APIs, not only MC.
>> The whole media subsystem seems not to have any business with
>> audio anymore. Is the whole V4L2 API superseded by something else?
> It never had.
Really? Why it is called media, if it does not handle at least
video and audio?
As application developer I would wish to have an API, which
is able to handle audio and video together, e.g. for HDMI
output.
> V4L2 can control audio settings (like language selection
> stero/mono switch, and even volume/balance), but it was never meant to
> be an API for the digital audio output. Ok, on very ancient hardware, the
> audio could be provided only via an analog output pin (or CD cable).
>
> Still, on those cases, the audio is generally connected to the CD or
> AUX input at the audio card, and userspace ends by controlling it via
> ALSA.
>
>> As you have worked a lot on documentation recently, can you point me to some
>> documentation how the different APIs are supposed to work together? What API
>> to use when?
> Contributions for that are welcome.
Who should write that? I think it's a question for you as media maintainer.
I would like to understand:
How is that, what DVB audio/video/osd provide (for "old hardware"),
supposed to work with modern APIs on modern hardware?
My use case (as with the "old" S2-6400 card [1]) is HDMI output of
frame-synchronous audio and video (DVB transport stream) plus overlay
graphics, preferably with independent scaling for video and overlay.
Video and audio format changes must be handled frame-by-frame on
the fly, as DVB broadcasters sometimes like to switch formats for
advertising and then back for the movie.
I want that to work on modern FF hardware: e.g. imx
(imx6q), sunxi (e.g. Allwinner H5), meson (meson-gxbb S905), rockchip,...
The multimedia-API (or combination of APIs) should hide the hardware
differences from the userspace application (this is the purpose of kernel
APIs), especially I should not be forced to use different APIs for similar
hardware, as , e.g., usually DRM does the scaling, sometimes I have
to use a media mem2mem scaler, because it is implemented that way
(e.g. for imx6q) and not in DRM, what would be the preferred variant
for my use case. Similar for video decoders: DRM/V4L2.
>From all the different drivers for the mentioned SoCs for me it is not
obvious, what the global strategy in linux/linux-media is to support my
use case (hardware of the mentioned SoCs supports all that).
Which API (-combination) is designated to support this case on
all available modern hardware? Which API I should select in my
userspace application, in which direction should I (and hopefully
others) try to improve the existing (multi-)media kernel drivers in
linux, to get closer to common support for that classic multimedia
use case?
Some explanation or documentation for this would really be appreciated.
Regards,
Soeren
[1] https://www.mail-archive.com/linux-media@vger.kernel.org/msg115690.html
> We're still fighting to have the current DVB API documented. Before
> those patches I'm working with, several parts of the DVB API documentation
> are a piece of fiction, as it doesn't match what's implemented.
>
> For example, the CA documentation used to say that the CA is
> controlled via /dev/ost/ca. I was not here when DVB was added
> usptream. Yet, I'd risk to say that, since when the DVB system was
> merged upstream, the CA device was always /dev/adapter?/ca?.
>
> Maybe somewhere between 1999-2001, when the subsystem were on
> its early days and out of the Kernel tree, "/dev/ost/*" devnodes
> were used for a while.
>
> Thanks,
> Mauro
^ permalink raw reply [flat|nested] 27+ messages in thread
end of thread, other threads:[~2017-09-09 12:50 UTC | newest]
Thread overview: 27+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-08-31 23:46 [PATCH 00/15] Improve DVB documentation and reduce its gap Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 01/15] media: dvb/intro: use the term Digital TV to refer to the system Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 02/15] media: dvb/intro: update references for TV standards Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 03/15] media: dvb/intro: update the history part of the document Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 04/15] media: dvb/intro: adjust the notices about optional hardware Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 05/15] media: dvb/frontend.h: move out a private internal structure Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 06/15] media: dvb/frontend.h: document the uAPI file Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 07/15] media: dvb frontend docs: use kernel-doc documentation Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 08/15] media: fe_property_parameters.rst: better define properties usage Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 09/15] media: fe_property_parameters.rst: better document bandwidth Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 10/15] media: dmx.h: get rid of unused DMX_KERNEL_CLIENT Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 11/15] media: dmx.h: get rid of DMX_GET_CAPS Mauro Carvalho Chehab
2017-08-31 23:46 ` [PATCH 12/15] media: dmx.h: get rid of DMX_SET_SOURCE Mauro Carvalho Chehab
2017-09-01 6:28 ` Honza Petrouš
2017-09-01 9:37 ` Mauro Carvalho Chehab
2017-09-01 9:53 ` Honza Petrouš
2017-09-01 10:45 ` Mauro Carvalho Chehab
2017-09-01 11:14 ` Honza Petrouš
2017-09-01 13:06 ` Mauro Carvalho Chehab
2017-08-31 23:47 ` [PATCH 13/15] media: dmx.h: get rid of GET_DMX_EVENT Mauro Carvalho Chehab
2017-08-31 23:47 ` [PATCH 14/15] media: dmx.h: add kernel-doc markups and use it at Documentation/ Mauro Carvalho Chehab
2017-08-31 23:47 ` [PATCH 15/15] media: net.rst: Fix the level of a section of the net chapter Mauro Carvalho Chehab
2017-09-01 8:40 ` [PATCH 00/15] Improve DVB documentation and reduce its gap Honza Petrouš
2017-09-01 9:32 ` Mauro Carvalho Chehab
2017-09-04 0:55 ` Soeren Moch
2017-09-04 11:29 ` Mauro Carvalho Chehab
2017-09-09 12:49 ` Soeren Moch
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.