diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2026-10-02 12:17:24 -0700 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2026-10-02 12:17:24 -0700 |
| commit | 3f1fe48a36b0b6722dc3fd421d93512bac138e9a (patch) | |
| tree | b767d7f6e26bc64334d3f14f8422d187239dc45d /Documentation/userspace-api/media/dvb | |
| download | linux-stable-3f1fe48a36b0b6722dc3fd421d93512bac138e9a.tar.gz linux-stable-3f1fe48a36b0b6722dc3fd421d93512bac138e9a.zip | |
Merge tag 'io_uring-7.3-20261002' of git://git.kernel.org/pub/scm/linux/kernel/git/axboe/linuxgrafted
Pull io_uring fixes from Jens Axboe:
- Fix a task_work add use-after-free with SQPOLL.
The sqpoll thread could pop and complete the last request while
io_req_normal_work_add() was still looking at them after the mpscq
push.
Use the same approach as DEFER_TASKRUN to protect from that, holding
an RCU read lock across the add, and have exit wait for an RCU grace
period for SQPOLL rings as well.
- CQE32 ring fixes: correct the free entry check for 32b CQEs, zero the
big_cqe for aux CQEs, and only post the dummy skip CQE on CQE_MIXED
rings
- Mark the source filter table as COW when cloning bpf filters, so
registering another filter on the source doesn't modify the shared
table in place
- Initialize the task context before running the BPF loop
- Requeue zcrx multishot receives stopped by a local resource
- End a TX_TIMESTAMP multishot cmd when the CQ is full (lollipopkit)
* tag 'io_uring-7.3-20261002' of git://git.kernel.org/pub/scm/linux/kernel/git/axboe/linux:
io_uring: fix task_work add use-after-free with SQPOLL
io_uring/cmd_net: end TX_TIMESTAMP multishot when the CQ is full
io_uring/zcrx: requeue multishot receives stopped by a local resource
io_uring: initialize task context before running the BPF loop
io_uring: zero big_cqe for aux CQEs on CQE32 rings
io_uring: fix free entry check for 32b CQEs on CQE32 rings
io_uring: only post the dummy skip CQE on CQE_MIXED rings
io_uring/bpf_filter: mark source as COW when cloning filters
Diffstat (limited to 'Documentation/userspace-api/media/dvb')
92 files changed, 11474 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/dvb/ca-fclose.rst b/Documentation/userspace-api/media/dvb/ca-fclose.rst new file mode 100644 index 000000000..27f217a35 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-fclose.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _ca_fclose: + +===================== +Digital TV CA close() +===================== + +Name +---- + +Digital TV CA close() + +Synopsis +-------- + +.. c:function:: int close(int fd) + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +Description +----------- + +This system call closes a previously opened CA device. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-fopen.rst b/Documentation/userspace-api/media/dvb/ca-fopen.rst new file mode 100644 index 000000000..7f99908ff --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-fopen.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _ca_fopen: + +==================== +Digital TV CA open() +==================== + +Name +---- + +Digital TV CA open() + +Synopsis +-------- + +.. c:function:: int open(const char *name, int flags) + +Arguments +--------- + +``name`` + Name of specific Digital TV CA device. + +``flags`` + A bit-wise OR of the following flags: + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``O_RDONLY`` + - read-only access + + - - ``O_RDWR`` + - read/write access + + - - ``O_NONBLOCK`` + - open in non-blocking mode + (blocking mode is the default) + +Description +----------- + +This system call opens a named ca device (e.g. ``/dev/dvb/adapter?/ca?``) +for subsequent use. + +When an ``open()`` call has succeeded, the device will be ready for use. The +significance of blocking or non-blocking mode is described in the +documentation for functions where there is a difference. It does not +affect the semantics of the ``open()`` call itself. A device opened in +blocking mode can later be put into non-blocking mode (and vice versa) +using the ``F_SETFL`` command of the ``fcntl`` system call. This is a +standard system call, documented in the Linux manual page for fcntl. +Only one user can open the CA Device in ``O_RDWR`` mode. All other +attempts to open the device in this mode will fail, and an error code +will be returned. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-get-cap.rst b/Documentation/userspace-api/media/dvb/ca-get-cap.rst new file mode 100644 index 000000000..9b29513ee --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-get-cap.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_GET_CAP: + +========== +CA_GET_CAP +========== + +Name +---- + +CA_GET_CAP + +Synopsis +-------- + +.. c:macro:: CA_GET_CAP + +``int ioctl(fd, CA_GET_CAP, struct ca_caps *caps)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``caps`` + Pointer to struct :c:type:`ca_caps`. + +Description +----------- + +Queries the Kernel for information about the available CA and descrambler +slots, and their types. + +Return Value +------------ + +On success 0 is returned and :c:type:`ca_caps` is filled. + +On error, -1 is returned and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst new file mode 100644 index 000000000..0cfdcdab3 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_GET_DESCR_INFO: + +================= +CA_GET_DESCR_INFO +================= + +Name +---- + +CA_GET_DESCR_INFO + +Synopsis +-------- + +.. c:macro:: CA_GET_DESCR_INFO + +``int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``desc`` + Pointer to struct :c:type:`ca_descr_info`. + +Description +----------- + +Returns information about all descrambler slots. + +Return Value +------------ + +On success 0 is returned, and :c:type:`ca_descr_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-get-msg.rst b/Documentation/userspace-api/media/dvb/ca-get-msg.rst new file mode 100644 index 000000000..7c9a8d197 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-get-msg.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_GET_MSG: + +========== +CA_GET_MSG +========== + +Name +---- + +CA_GET_MSG + +Synopsis +-------- + +.. c:macro:: CA_GET_MSG + +``int ioctl(fd, CA_GET_MSG, struct ca_msg *msg)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``msg`` + Pointer to struct :c:type:`ca_msg`. + +Description +----------- + +Receives a message via a CI CA module. + +.. note:: + + Please notice that, on most drivers, this is done by reading from + the /dev/adapter?/ca? device node. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst new file mode 100644 index 000000000..582444af7 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_GET_SLOT_INFO: + +================ +CA_GET_SLOT_INFO +================ + +Name +---- + +CA_GET_SLOT_INFO + +Synopsis +-------- + +.. c:macro:: CA_GET_SLOT_INFO + +``int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``info`` + Pointer to struct :c:type:`ca_slot_info`. + +Description +----------- + +Returns information about a CA slot identified by +:c:type:`ca_slot_info`.slot_num. + +Return Value +------------ + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``ENODEV`` + - the slot is not available. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-reset.rst b/Documentation/userspace-api/media/dvb/ca-reset.rst new file mode 100644 index 000000000..b01ca48f0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-reset.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_RESET: + +======== +CA_RESET +======== + +Name +---- + +CA_RESET + +Synopsis +-------- + +.. c:macro:: CA_RESET + +``int ioctl(fd, CA_RESET)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +Description +----------- + +Puts the Conditional Access hardware on its initial state. It should +be called before start using the CA hardware. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-send-msg.rst b/Documentation/userspace-api/media/dvb/ca-send-msg.rst new file mode 100644 index 000000000..7dd2ab4ef --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-send-msg.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_SEND_MSG: + +=========== +CA_SEND_MSG +=========== + +Name +---- + +CA_SEND_MSG + +Synopsis +-------- + +.. c:macro:: CA_SEND_MSG + +``int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``msg`` + Pointer to struct :c:type:`ca_msg`. + +Description +----------- + +Sends a message via a CI CA module. + +.. note:: + + Please notice that, on most drivers, this is done by writing + to the /dev/adapter?/ca? device node. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-set-descr.rst b/Documentation/userspace-api/media/dvb/ca-set-descr.rst new file mode 100644 index 000000000..a740af34c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-set-descr.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_SET_DESCR: + +============ +CA_SET_DESCR +============ + +Name +---- + +CA_SET_DESCR + +Synopsis +-------- + +.. c:macro:: CA_SET_DESCR + +``int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``msg`` + Pointer to struct :c:type:`ca_descr`. + +Description +----------- + +CA_SET_DESCR is used for feeding descrambler CA slots with descrambling +keys (referred as control words). + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca.h.rst.exceptions b/Documentation/userspace-api/media/dvb/ca.h.rst.exceptions new file mode 100644 index 000000000..f6828238e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca.h.rst.exceptions @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _DVBCA_H_ + +# struct ca_slot_info defines +replace define CA_CI :c:type:`ca_slot_info` +replace define CA_CI_LINK :c:type:`ca_slot_info` +replace define CA_CI_PHYS :c:type:`ca_slot_info` +replace define CA_DESCR :c:type:`ca_slot_info` +replace define CA_SC :c:type:`ca_slot_info` +replace define CA_CI_MODULE_PRESENT :c:type:`ca_slot_info` +replace define CA_CI_MODULE_READY :c:type:`ca_slot_info` + +# struct ca_descr_info defines +replace define CA_ECD :c:type:`ca_descr_info` +replace define CA_NDS :c:type:`ca_descr_info` +replace define CA_DSS :c:type:`ca_descr_info` + +# some typedefs should point to struct/enums +replace typedef ca_slot_info_t :c:type:`ca_slot_info` +replace typedef ca_descr_info_t :c:type:`ca_descr_info` +replace typedef ca_caps_t :c:type:`ca_caps` +replace typedef ca_msg_t :c:type:`ca_msg` +replace typedef ca_descr_t :c:type:`ca_descr` diff --git a/Documentation/userspace-api/media/dvb/ca.rst b/Documentation/userspace-api/media/dvb/ca.rst new file mode 100644 index 000000000..0dc00e5e4 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_ca: + +#################### +Digital TV CA Device +#################### + +The Digital TV CA device controls the conditional access hardware. It +can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and ioctl +definitions can be accessed by including ``linux/dvb/ca.h`` in your +application. + +.. note:: + + There are three ioctls at this API that aren't documented: + :ref:`CA_GET_MSG`, :ref:`CA_SEND_MSG` and :ref:`CA_SET_DESCR`. + Documentation for them are welcome. + +.. toctree:: + :maxdepth: 1 + + ca_data_types + ca_function_calls + ca_high_level diff --git a/Documentation/userspace-api/media/dvb/ca_data_types.rst b/Documentation/userspace-api/media/dvb/ca_data_types.rst new file mode 100644 index 000000000..54ea2a987 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca_data_types.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _ca_data_types: + +************* +CA Data Types +************* + +.. kernel-doc:: include/uapi/linux/dvb/ca.h diff --git a/Documentation/userspace-api/media/dvb/ca_function_calls.rst b/Documentation/userspace-api/media/dvb/ca_function_calls.rst new file mode 100644 index 000000000..3b893fbd5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca_function_calls.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _ca_function_calls: + +***************** +CA Function Calls +***************** + +.. toctree:: + :maxdepth: 1 + + ca-fopen + ca-fclose + ca-reset + ca-get-cap + ca-get-slot-info + ca-get-descr-info + ca-get-msg + ca-send-msg + ca-set-descr diff --git a/Documentation/userspace-api/media/dvb/ca_high_level.rst b/Documentation/userspace-api/media/dvb/ca_high_level.rst new file mode 100644 index 000000000..a73f3691c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca_high_level.rst @@ -0,0 +1,157 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The High level CI API +===================== + +.. note:: + + This documentation is outdated. + +This document describes the high level CI API as in accordance to the +Linux DVB API. + + +With the High Level CI approach any new card with almost any random +architecture can be implemented with this style, the definitions +inside the switch statement can be easily adapted for any card, thereby +eliminating the need for any additional ioctls. + +The disadvantage is that the driver/hardware has to manage the rest. For +the application programmer it would be as simple as sending/receiving an +array to/from the CI ioctls as defined in the Linux DVB API. No changes +have been made in the API to accommodate this feature. + + +Why the need for another CI interface? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is one of the most commonly asked question. Well a nice question. +Strictly speaking this is not a new interface. + +The CI interface is defined in the DVB API in ca.h as: + +.. code-block:: c + + typedef struct ca_slot_info { + int num; /* slot number */ + + int type; /* CA interface this slot supports */ + #define CA_CI 1 /* CI high level interface */ + #define CA_CI_LINK 2 /* CI link layer level interface */ + #define CA_CI_PHYS 4 /* CI physical layer level interface */ + #define CA_DESCR 8 /* built-in descrambler */ + #define CA_SC 128 /* simple smart card interface */ + + unsigned int flags; + #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ + #define CA_CI_MODULE_READY 2 + } ca_slot_info_t; + +This CI interface follows the CI high level interface, which is not +implemented by most applications. Hence this area is revisited. + +This CI interface is quite different in the case that it tries to +accommodate all other CI based devices, that fall into the other categories. + +This means that this CI interface handles the EN50221 style tags in the +Application layer only and no session management is taken care of by the +application. The driver/hardware will take care of all that. + +This interface is purely an EN50221 interface exchanging APDU's. This +means that no session management, link layer or a transport layer do +exist in this case in the application to driver communication. It is +as simple as that. The driver/hardware has to take care of that. + +With this High Level CI interface, the interface can be defined with the +regular ioctls. + +All these ioctls are also valid for the High level CI interface + +#define CA_RESET _IO('o', 128) +#define CA_GET_CAP _IOR('o', 129, ca_caps_t) +#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t) +#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t) +#define CA_GET_MSG _IOR('o', 132, ca_msg_t) +#define CA_SEND_MSG _IOW('o', 133, ca_msg_t) +#define CA_SET_DESCR _IOW('o', 134, ca_descr_t) + + +On querying the device, the device yields information thus: + +.. code-block:: none + + CA_GET_SLOT_INFO + ---------------------------- + Command = [info] + APP: Number=[1] + APP: Type=[1] + APP: flags=[1] + APP: CI High level interface + APP: CA/CI Module Present + + CA_GET_CAP + ---------------------------- + Command = [caps] + APP: Slots=[1] + APP: Type=[1] + APP: Descrambler keys=[16] + APP: Type=[1] + + CA_SEND_MSG + ---------------------------- + Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1] + Found CA descriptor @ program level + + (20) ES type=[2] ES pid=[201] ES length =[0 (0x0)] + (25) ES type=[4] ES pid=[301] ES length =[0 (0x0)] + ca_message length is 25 (0x19) bytes + EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00] + + +Not all ioctl's are implemented in the driver from the API, the other +features of the hardware that cannot be implemented by the API are achieved +using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is +used to exchange the data to maintain compatibility with other hardware. + +.. code-block:: c + + /* a message to/from a CI-CAM */ + typedef struct ca_msg { + unsigned int index; + unsigned int type; + unsigned int length; + unsigned char msg[256]; + } ca_msg_t; + + +The flow of data can be described thus, + +.. code-block:: none + + App (User) + ----- + parse + | + | + v + en50221 APDU (package) + -------------------------------------- + | | | High Level CI driver + | | | + | v | + | en50221 APDU (unpackage) | + | | | + | | | + | v | + | sanity checks | + | | | + | | | + | v | + | do (H/W dep) | + -------------------------------------- + | Hardware + | + v + +The High Level CI interface uses the EN50221 DVB standard, following a +standard ensures futureproofness. diff --git a/Documentation/userspace-api/media/dvb/demux.rst b/Documentation/userspace-api/media/dvb/demux.rst new file mode 100644 index 000000000..ef05abcf1 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/demux.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_demux: + +####################### +Digital TV Demux Device +####################### + +The Digital TV demux device controls the MPEG-TS filters for the +digital TV. If the driver and hardware supports, those filters are +implemented at the hardware. Otherwise, the Kernel provides a software +emulation. + +It can be accessed through ``/dev/adapter?/demux?``. Data types and +ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in +your application. + + +.. toctree:: + :maxdepth: 1 + + dmx_types + dmx_fcalls diff --git a/Documentation/userspace-api/media/dvb/dmx-add-pid.rst b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst new file mode 100644 index 000000000..ea0c7dd91 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_ADD_PID: + +=========== +DMX_ADD_PID +=========== + +Name +---- + +DMX_ADD_PID + +Synopsis +-------- + +.. c:macro:: DMX_ADD_PID + +``int ioctl(fd, DMX_ADD_PID, __u16 *pid)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``pid`` + PID number to be filtered. + +Description +----------- + +This ioctl call allows to add multiple PIDs to a transport stream filter +previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to +:c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-expbuf.rst b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst new file mode 100644 index 000000000..5cdc2035e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_EXPBUF: + +**************** +ioctl DMX_EXPBUF +**************** + +Name +==== + +DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. + +.. warning:: this API is still experimental + +Synopsis +======== + +.. c:macro:: DMX_EXPBUF + +``int ioctl(int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dmx_exportbuffer`. + +Description +=========== + +This ioctl is an extension to the memory mapping I/O method. +It can be used to export a buffer as a DMABUF file at any time after +buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. + +To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. +Applications must set the ``index`` field. Valid index numbers +range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dmx_requestbuffers` ``count``) minus one. +Additional flags may be posted in the ``flags`` field. Refer to a manual +for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, +and O_RDWR are supported. +All other fields must be set to zero. In the +case of multi-planar API, every plane is exported separately using +multiple :ref:`DMX_EXPBUF` calls. + +After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a +driver, on success. This is a DMABUF file descriptor. The application may +pass it to other DMABUF-aware devices. It is recommended to close a DMABUF +file when it is no longer used to allow the associated memory to be reclaimed. + +Examples +======== + +.. code-block:: c + + int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) + { + struct dmx_exportbuffer expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) { + perror("DMX_EXPBUF"); + return -1; + } + + *dmafd = expbuf.fd; + + return 0; + } + +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. + +EINVAL + A queue is not in MMAP mode or DMABUF exporting is not supported or + ``flags`` or ``index`` fields are invalid. diff --git a/Documentation/userspace-api/media/dvb/dmx-fclose.rst b/Documentation/userspace-api/media/dvb/dmx-fclose.rst new file mode 100644 index 000000000..719ac1d4f --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-fclose.rst @@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_fclose: + +======================== +Digital TV demux close() +======================== + +Name +---- + +Digital TV demux close() + +Synopsis +-------- + +.. c:function:: int close(int fd) + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to + :c:func:`open()`. + +Description +----------- + +This system call deactivates and deallocates a filter that was +previously allocated via the :c:func:`open()` call. + +Return Value +------------ + +On success 0 is returned. + +On error, -1 is returned and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fopen.rst b/Documentation/userspace-api/media/dvb/dmx-fopen.rst new file mode 100644 index 000000000..50b36eb43 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-fopen.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_fopen: + +======================= +Digital TV demux open() +======================= + +Name +---- + +Digital TV demux open() + +Synopsis +-------- + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +--------- + +``name`` + Name of specific Digital TV demux device. + +``flags`` + A bit-wise OR of the following flags: + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - + - ``O_RDONLY`` + - read-only access + + - + - ``O_RDWR`` + - read/write access + + - + - ``O_NONBLOCK`` + - open in non-blocking mode + (blocking mode is the default) + +Description +----------- + +This system call, used with a device name of ``/dev/dvb/adapter?/demux?``, +allocates a new filter and returns a handle which can be used for +subsequent control of that filter. This call has to be made for each +filter to be used, i.e. every returned file descriptor is a reference to +a single filter. ``/dev/dvb/adapter?/dvr?`` is a logical device to be used +for retrieving Transport Streams for digital video recording. When +reading from this device a transport stream containing the packets from +all PES filters set in the corresponding demux device +(``/dev/dvb/adapter?/demux?``) having the output set to ``DMX_OUT_TS_TAP``. +A recorded Transport Stream is replayed by writing to this device. + +The significance of blocking or non-blocking mode is described in the +documentation for functions where there is a difference. It does not +affect the semantics of the ``open()`` call itself. A device opened +in blocking mode can later be put into non-blocking mode (and vice versa) +using the ``F_SETFL`` command of the fcntl system call. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EMFILE`` + - "Too many open files", i.e. no more filters available. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fread.rst b/Documentation/userspace-api/media/dvb/dmx-fread.rst new file mode 100644 index 000000000..88c4cddf7 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-fread.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_fread: + +======================= +Digital TV demux read() +======================= + +Name +---- + +Digital TV demux read() + +Synopsis +-------- + +.. c:function:: size_t read(int fd, void *buf, size_t count) + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + + ``buf`` + Buffer to be filled + +``count`` + Max number of bytes to read + +Description +----------- + +This system call returns filtered data, which might be section or Packetized +Elementary Stream (PES) data. The filtered data is transferred from +the driver's internal circular buffer to ``buf``. The maximum amount of data +to be transferred is implied by count. + +.. note:: + + if a section filter created with + :c:type:`DMX_CHECK_CRC <dmx_sct_filter_params>` flag set, + data that fails on CRC check will be silently ignored. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EWOULDBLOCK`` + - No data to return and ``O_NONBLOCK`` was specified. + + - - ``EOVERFLOW`` + - The filtered data was not read from the buffer in due time, + resulting in non-read data being lost. The buffer is flushed. + + - - ``ETIMEDOUT`` + - The section was not loaded within the stated timeout period. + See ioctl :ref:`DMX_SET_FILTER` for how to set a timeout. + + - - ``EFAULT`` + - The driver failed to write to the callers buffer due to an + invalid \*buf pointer. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fwrite.rst b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst new file mode 100644 index 000000000..e11ee0ba8 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_fwrite: + +======================== +Digital TV demux write() +======================== + +Name +---- + +Digital TV demux write() + +Synopsis +-------- + +.. c:function:: ssize_t write(int fd, const void *buf, size_t count) + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``buf`` + Buffer with data to be written + +``count`` + Number of bytes at the buffer + +Description +----------- + +This system call is only provided by the logical device +``/dev/dvb/adapter?/dvr?``, associated with the physical demux device that +provides the actual DVR functionality. It is used for replay of a +digitally recorded Transport Stream. Matching filters have to be defined +in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``. +The amount of data to be transferred is implied by count. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EWOULDBLOCK`` + - No data was written. This might happen if ``O_NONBLOCK`` was + specified and there is no more buffer space available (if + ``O_NONBLOCK`` is not specified the function will block until buffer + space is available). + + - - ``EBUSY`` + - This error code indicates that there are conflicting requests. The + corresponding demux device is setup to receive data from the + front- end. Make sure that these filters are stopped and that the + filters with input set to ``DMX_IN_DVR`` are started. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst new file mode 100644 index 000000000..4f5f0505c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_GET_PES_PIDS: + +================ +DMX_GET_PES_PIDS +================ + +Name +---- + +DMX_GET_PES_PIDS + +Synopsis +-------- + +.. c:macro:: DMX_GET_PES_PIDS + +``int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5])`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``pids`` + Array used to store 5 Program IDs. + +Description +----------- + +This ioctl allows to query a DVB device to return the first PID used +by audio, video, textext, subtitle and PCR programs on a given service. +They're stored as: + +======================= ======== ======================================= +PID element position content +======================= ======== ======================================= +pids[DMX_PES_AUDIO] 0 first audio PID +pids[DMX_PES_VIDEO] 1 first video PID +pids[DMX_PES_TELETEXT] 2 first teletext PID +pids[DMX_PES_SUBTITLE] 3 first subtitle PID +pids[DMX_PES_PCR] 4 first Program Clock Reference PID +======================= ======== ======================================= + +.. note:: + + A value equal to 0xffff means that the PID was not filled by the + Kernel. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-get-stc.rst b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst new file mode 100644 index 000000000..6ada74f6e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_GET_STC: + +=========== +DMX_GET_STC +=========== + +Name +---- + +DMX_GET_STC + +Synopsis +-------- + +.. c:macro:: DMX_GET_STC + +``int ioctl(int fd, DMX_GET_STC, struct dmx_stc *stc)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``stc`` + Pointer to :c:type:`dmx_stc` where the stc data is to be stored. + +Description +----------- + +This ioctl call returns the current value of the system time counter +(which is driven by a PES filter of type :c:type:`DMX_PES_PCR <dmx_ts_pes>`). +Some hardware supports more than one STC, so you must specify which one by +setting the :c:type:`num <dmx_stc>` field of stc before the ioctl (range 0...n). +The result is returned in form of a ratio with a 64 bit numerator +and a 32 bit denominator, so the real 90kHz STC value is +``stc->stc / stc->base``. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - .. row 1 + + - ``EINVAL`` + + - Invalid stc number. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-mmap.rst b/Documentation/userspace-api/media/dvb/dmx-mmap.rst new file mode 100644 index 000000000..8826c6226 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-mmap.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx-mmap: + +***************** +Digital TV mmap() +***************** + +Name +==== + +dmx-mmap - Map device memory into application address space + +.. warning:: this API is still experimental + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + #include <sys/mman.h> + +.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) + +Arguments +========= + +``start`` + Map the buffer to this address in the application's address space. + When the ``MAP_FIXED`` flag is specified, ``start`` must be a + multiple of the pagesize and mmap will fail when the specified + address cannot be used. Use of this option is discouraged; + applications should just specify a ``NULL`` pointer here. + +``length`` + Length of the memory area to map. This must be a multiple of the + DVB packet length (188, on most drivers). + +``prot`` + The ``prot`` argument describes the desired memory protection. + Regardless of the device type and the direction of data exchange it + should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read + and write access to image buffers. Drivers should support at least + this combination of flags. + +``flags`` + The ``flags`` parameter specifies the type of the mapped object, + mapping options and whether modifications made to the mapped copy of + the page are private to the process or are to be shared with other + references. + + ``MAP_FIXED`` requests that the driver selects no other address than + the one specified. If the specified address cannot be used, + :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified, + ``start`` must be a multiple of the pagesize. Use of this option is + discouraged. + + One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. + ``MAP_SHARED`` allows applications to share the mapped memory with + other (e. g. child-) processes. + + .. note:: + + The Linux Digital TV applications should not set the + ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` + flags. + +``fd`` + File descriptor returned by :c:func:`open()`. + +``offset`` + Offset of the buffer in device memory, as returned by + :ref:`DMX_QUERYBUF` ioctl. + +Description +=========== + +The :c:func:`mmap()` function asks to map ``length`` bytes starting at +``offset`` in the memory of the device specified by ``fd`` into the +application address space, preferably at address ``start``. This latter +address is a hint only, and is usually specified as 0. + +Suitable length and offset parameters are queried with the +:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the +:ref:`DMX_REQBUFS` ioctl before they can be queried. + +To unmap buffers the :c:func:`munmap()` function is used. + +Return Value +============ + +On success :c:func:`mmap()` returns a pointer to the mapped buffer. On +error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set +appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid file descriptor. + +EACCES + ``fd`` is not open for reading and writing. + +EINVAL + The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. + they are too large, or not aligned on a ``PAGESIZE`` boundary.) + + The ``flags`` or ``prot`` value is not supported. + + No buffers have been allocated with the + :ref:`DMX_REQBUFS` ioctl. + +ENOMEM + Not enough physical or virtual memory was available to complete the + request. diff --git a/Documentation/userspace-api/media/dvb/dmx-munmap.rst b/Documentation/userspace-api/media/dvb/dmx-munmap.rst new file mode 100644 index 000000000..66bbc11e5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-munmap.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx-munmap: + +************ +DVB munmap() +************ + +Name +==== + +dmx-munmap - Unmap device memory + +.. warning:: This API is still experimental. + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + #include <sys/mman.h> + +.. c:function:: int munmap( void *start, size_t length ) + +Arguments +========= + +``start`` + Address of the mapped buffer as returned by the + :c:func:`mmap()` function. + +``length`` + Length of the mapped buffer. This must be the same value as given to + :c:func:`mmap()`. + +Description +=========== + +Unmaps a previously with the :c:func:`mmap()` function mapped +buffer and frees it, if possible. + +Return Value +============ + +On success :c:func:`munmap()` returns 0, on failure -1 and the +``errno`` variable is set appropriately: + +EINVAL + The ``start`` or ``length`` is incorrect, or no buffers have been + mapped yet. diff --git a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst new file mode 100644 index 000000000..1a13a3383 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_QBUF: + +************************* +ioctl DMX_QBUF, DMX_DQBUF +************************* + +Name +==== + +DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver + +.. warning:: this API is still experimental + +Synopsis +======== + +.. c:macro:: DMX_QBUF + +``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)`` + +.. c:macro:: DMX_DQBUF + +``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dmx_buffer`. + +Description +=========== + +Applications call the ``DMX_QBUF`` ioctl to enqueue an empty +(capturing) or filled (output) buffer in the driver's incoming queue. +The semantics depend on the selected I/O method. + +To enqueue a buffer applications set the ``index`` field. Valid index +numbers range from zero to the number of buffers allocated with +:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus +one. The contents of the struct :c:type:`dmx_buffer` returned +by a :ref:`DMX_QUERYBUF` ioctl will do as well. + +When ``DMX_QBUF`` is called with a pointer to this structure, it locks the +memory pages of the buffer in physical memory, so they cannot be swapped +out to disk. Buffers remain locked until dequeued, until the +device is closed. + +Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled +(capturing) buffer from the driver's outgoing queue. +They just set the ``index`` field with the buffer ID to be queued. +When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, +the driver fills the remaining fields or returns an error code. + +By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing +queue. When the ``O_NONBLOCK`` flag was given to the +:c:func:`open()` function, ``DMX_DQBUF`` returns +immediately with an ``EAGAIN`` error code when no buffer is available. + +The struct :c:type:`dmx_buffer` structure is specified in +:ref:`buffer`. + +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. + +EAGAIN + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no + buffer was in the outgoing queue. + +EINVAL + The ``index`` is out of bounds, or no buffers have been allocated yet. + +EIO + ``DMX_DQBUF`` failed due to an internal error. Can also indicate + temporary problems like signal loss or CRC errors. diff --git a/Documentation/userspace-api/media/dvb/dmx-querybuf.rst b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst new file mode 100644 index 000000000..08ee9853d --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_QUERYBUF: + +****************** +ioctl DMX_QUERYBUF +****************** + +Name +==== + +DMX_QUERYBUF - Query the status of a buffer + +.. warning:: this API is still experimental + +Synopsis +======== + +.. c:macro:: DMX_QUERYBUF + +``int ioctl(int fd, DMX_QUERYBUF, struct dvb_buffer *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dvb_buffer`. + +Description +=========== + +This ioctl is part of the mmap streaming I/O method. It can +be used to query the status of a buffer at any time after buffers have +been allocated with the :ref:`DMX_REQBUFS` ioctl. + +Applications set the ``index`` field. Valid index numbers range from zero +to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dvb_requestbuffers` ``count``) minus one. + +After calling :ref:`DMX_QUERYBUF` with a pointer to this structure, +drivers return an error code or fill the rest of the structure. + +On success, the ``offset`` will contain the offset of the buffer from the +start of the device memory, the ``length`` field its size, and the +``bytesused`` the number of bytes occupied by data in the buffer (payload). + +Return Value +============ + +On success 0 is returned, the ``offset`` will contain the offset of the +buffer from the start of the device memory, the ``length`` field its size, +and the ``bytesused`` the number of bytes occupied by data in the buffer +(payload). + +On error it returns -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EINVAL + The ``index`` is out of bounds. diff --git a/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst new file mode 100644 index 000000000..f75b33e5e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_REMOVE_PID: + +============== +DMX_REMOVE_PID +============== + +Name +---- + +DMX_REMOVE_PID + +Synopsis +-------- + +.. c:macro:: DMX_REMOVE_PID + +``int ioctl(fd, DMX_REMOVE_PID, __u16 *pid)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``pid`` + PID of the PES filter to be removed. + +Description +----------- + +This ioctl call allows to remove a PID when multiple PIDs are set on a +transport stream filter, e. g. a filter previously set up with output +equal to :c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`, created via either +:ref:`DMX_SET_PES_FILTER` or :ref:`DMX_ADD_PID`. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst new file mode 100644 index 000000000..d2bb1909e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_REQBUFS: + +***************** +ioctl DMX_REQBUFS +***************** + +Name +==== + +DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O + +.. warning:: this API is still experimental + +Synopsis +======== + +.. c:macro:: DMX_REQBUFS + +``int ioctl(int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dmx_requestbuffers`. + +Description +=========== + +This ioctl is used to initiate a memory mapped or DMABUF based demux I/O. + +Memory mapped buffers are located in device memory and must be allocated +with this ioctl before they can be mapped into the application's address +space. User buffers are allocated by applications themselves, and this +ioctl is merely used to switch the driver into user pointer I/O mode and +to setup some internal structures. Similarly, DMABUF buffers are +allocated by applications through a device driver, and this ioctl only +configures the driver into DMABUF I/O mode without performing any direct +allocation. + +To allocate device buffers applications initialize all fields of the +struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field +to the desired number of buffers, and ``size`` to the size of each +buffer. + +When the ioctl is called with a pointer to this structure, the driver will +attempt to allocate the requested number of buffers and it stores the actual +number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger +number is also possible when the driver requires more buffers to +function correctly. The actual allocated buffer size can is returned +at ``size``, and can be smaller than what's requested. + +When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP`` +error code. + +Applications can call :ref:`DMX_REQBUFS` again to change the number of +buffers, however this cannot succeed when any buffers are still mapped. +A ``count`` value of zero frees all buffers, after aborting or finishing +any DMA in progress. + +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. + +EOPNOTSUPP + The the requested I/O method is not supported. diff --git a/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst new file mode 100644 index 000000000..13ce4092c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_SET_BUFFER_SIZE: + +=================== +DMX_SET_BUFFER_SIZE +=================== + +Name +---- + +DMX_SET_BUFFER_SIZE + +Synopsis +-------- + +.. c:macro:: DMX_SET_BUFFER_SIZE + +``int ioctl(int fd, DMX_SET_BUFFER_SIZE, unsigned long size)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``size`` + Unsigned long size + +Description +----------- + +This ioctl call is used to set the size of the circular buffer used for +filtered data. The default size is two maximum sized sections, i.e. if +this function is not called a buffer size of ``2 * 4096`` bytes will be +used. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-set-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst new file mode 100644 index 000000000..1b8c8071b --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_SET_FILTER: + +============== +DMX_SET_FILTER +============== + +Name +---- + +DMX_SET_FILTER + +Synopsis +-------- + +.. c:macro:: DMX_SET_FILTER + +``int ioctl(int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``params`` + + Pointer to structure containing filter parameters. + +Description +----------- + +This ioctl call sets up a filter according to the filter and mask +parameters provided. A timeout may be defined stating number of seconds +to wait for a section to be loaded. A value of 0 means that no timeout +should be applied. Finally there is a flag field where it is possible to +state whether a section should be CRC-checked, whether the filter should +be a "one-shot" filter, i.e. if the filtering operation should be +stopped after the first section is received, and whether the filtering +operation should be started immediately (without waiting for a +:ref:`DMX_START` ioctl call). If a filter was previously set-up, this +filter will be canceled, and the receive buffer will be flushed. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst new file mode 100644 index 000000000..5bb682e4a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_SET_PES_FILTER: + +================== +DMX_SET_PES_FILTER +================== + +Name +---- + +DMX_SET_PES_FILTER + +Synopsis +-------- + +.. c:macro:: DMX_SET_PES_FILTER + +``int ioctl(int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``params`` + Pointer to structure containing filter parameters. + +Description +----------- + +This ioctl call sets up a PES filter according to the parameters +provided. By a PES filter is meant a filter that is based just on the +packet identifier (PID), i.e. no PES header or payload filtering +capability is supported. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - .. row 1 + + - ``EBUSY`` + + - This error code indicates that there are conflicting requests. + There are active filters filtering data from another input source. + Make sure that these filters are stopped before starting this + filter. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-start.rst b/Documentation/userspace-api/media/dvb/dmx-start.rst new file mode 100644 index 000000000..aedccf952 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-start.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_START: + +========= +DMX_START +========= + +Name +---- + +DMX_START + +Synopsis +-------- + +.. c:macro:: DMX_START + +``int ioctl(int fd, DMX_START)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +----------- + +This ioctl call is used to start the actual filtering operation defined +via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. row 1 + + - ``EINVAL`` + + - Invalid argument, i.e. no filtering parameters provided via the + :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` ioctls. + + - .. row 2 + + - ``EBUSY`` + + - This error code indicates that there are conflicting requests. + There are active filters filtering data from another input source. + Make sure that these filters are stopped before starting this + filter. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-stop.rst b/Documentation/userspace-api/media/dvb/dmx-stop.rst new file mode 100644 index 000000000..8661e6772 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-stop.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_STOP: + +======== +DMX_STOP +======== + +Name +---- + +DMX_STOP + +Synopsis +-------- + +.. c:macro:: DMX_STOP + +``int ioctl(int fd, DMX_STOP)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +----------- + +This ioctl call is used to stop the actual filtering operation defined +via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and +started via the :ref:`DMX_START` command. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions b/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions new file mode 100644 index 000000000..2c219388d --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx.h.rst.exceptions @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: GPL-2.0 + +# All symbols belone to this namespace +namespace DTV.dmx + +# Ignore header name +ignore define _UAPI_DVBDMX_H_ + +# Ignore limit constants +ignore define DMX_FILTER_SIZE + +# dmx_ts_pes_type_t enum symbols +replace symbol DMX_PES_AUDIO0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_VIDEO0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_TELETEXT0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_SUBTITLE0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_PCR0 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_AUDIO1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_VIDEO1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_TELETEXT1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_SUBTITLE1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_PCR1 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_AUDIO2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_VIDEO2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_TELETEXT2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_SUBTITLE2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_PCR2 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_AUDIO3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_VIDEO3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_TELETEXT3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_SUBTITLE3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_PCR3 :c:type:`DTV.dmx.dmx_ts_pes` +replace symbol DMX_PES_OTHER :c:type:`DTV.dmx.dmx_ts_pes` + +# Ignore obsolete symbols +ignore define DMX_PES_AUDIO +ignore define DMX_PES_VIDEO +ignore define DMX_PES_TELETEXT +ignore define DMX_PES_SUBTITLE +ignore define DMX_PES_PCR + +# dmx_input_t symbols +replace symbol DMX_IN_FRONTEND :c:enum:`DTV.dmx.dmx_input` +replace symbol DMX_IN_DVR :c:enum:`DTV.dmx.dmx_input` + +# Flags for struct dmx_sct_filter_params +replace define DMX_CHECK_CRC :c:type:`DTV.dmx.dmx_sct_filter_params` +replace define DMX_ONESHOT :c:type:`DTV.dmx.dmx_sct_filter_params` +replace define DMX_IMMEDIATE_START :c:type:`DTV.dmx.dmx_sct_filter_params` + +replace symbol DMX_BUFFER_FLAG_HAD_CRC32_DISCARD :c:type:`DTV.dmx.dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_TEI :c:type:`DTV.dmx.dmx_buffer_flags` +replace symbol DMX_BUFFER_PKT_COUNTER_MISMATCH :c:type:`DTV.dmx.dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_DETECTED :c:type:`DTV.dmx.dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR :c:type:`DTV.dmx.dmx_buffer_flags` + +replace symbol DMX_OUT_DECODER :c:type:`DTV.dmx.dmx_output` +replace symbol DMX_OUT_TAP :c:type:`DTV.dmx.dmx_output` +replace symbol DMX_OUT_TS_TAP :c:type:`DTV.dmx.dmx_output` +replace symbol DMX_OUT_TSDEMUX_TAP :c:type:`DTV.dmx.dmx_output` + +replace ioctl DMX_DQBUF dmx_qbuf diff --git a/Documentation/userspace-api/media/dvb/dmx_fcalls.rst b/Documentation/userspace-api/media/dvb/dmx_fcalls.rst new file mode 100644 index 000000000..a14e7a61f --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx_fcalls.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dmx_fcalls: + +******************** +Demux Function Calls +******************** + +.. toctree:: + :maxdepth: 1 + + dmx-fopen + dmx-fclose + dmx-fread + dmx-fwrite + dmx-mmap + dmx-munmap + dmx-start + dmx-stop + dmx-set-filter + dmx-set-pes-filter + dmx-set-buffer-size + dmx-get-stc + dmx-get-pes-pids + dmx-add-pid + dmx-remove-pid + dmx-reqbufs + dmx-querybuf + dmx-expbuf + dmx-qbuf diff --git a/Documentation/userspace-api/media/dvb/dmx_types.rst b/Documentation/userspace-api/media/dvb/dmx_types.rst new file mode 100644 index 000000000..dd7601069 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx_types.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_types: + +**************** +Demux Data Types +**************** + +.. kernel-doc:: include/uapi/linux/dvb/dmx.h diff --git a/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst b/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst new file mode 100644 index 000000000..fbd0548f5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb-fe-read-status: + +*************************************** +Querying frontend status and statistics +*************************************** + +Once :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` is called, the +frontend will run a kernel thread that will periodically check for the +tuner lock status and provide statistics about the quality of the +signal. + +The information about the frontend tuner locking status can be queried +using :ref:`FE_READ_STATUS`. + +Signal statistics are provided via +:ref:`FE_GET_PROPERTY`. + +.. note:: + + Most statistics require the demodulator to be fully locked + (e. g. with :c:type:`FE_HAS_LOCK <fe_status>` bit set). See + :ref:`Frontend statistics indicators <frontend-stat-properties>` for + more details. diff --git a/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst b/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst new file mode 100644 index 000000000..0e2fd3a0a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. c:type:: dvb_frontend_event + +*************** +frontend events +*************** + + +.. code-block:: c + + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; diff --git a/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst b/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst new file mode 100644 index 000000000..9dd2f5424 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. c:type:: dvb_frontend_parameters + +******************* +frontend parameters +******************* + +The kind of parameters passed to the frontend device for tuning depend +on the kind of hardware you are using. + +The struct ``dvb_frontend_parameters`` uses a union with specific +per-system parameters. However, as newer delivery systems required more +data, the structure size weren't enough to fit, and just extending its +size would break the existing applications. So, those parameters were +replaced by the usage of +:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>` +ioctl's. The new API is flexible enough to add new parameters to +existing delivery systems, and to add newer delivery systems. + +So, newer applications should use +:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>` +instead, in order to be able to support the newer System Delivery like +DVB-S2, DVB-T2, DVB-C2, ISDB, etc. + +All kinds of parameters are combined as a union in the +``dvb_frontend_parameters`` structure: + + +.. code-block:: c + + struct dvb_frontend_parameters { + uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */ + /* intermediate frequency in kHz for QPSK */ + fe_spectral_inversion_t inversion; + union { + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; + struct dvb_vsb_parameters vsb; + } u; + }; + +In the case of QPSK frontends the ``frequency`` field specifies the +intermediate frequency, i.e. the offset which is effectively added to +the local oscillator frequency (LOF) of the LNB. The intermediate +frequency has to be specified in units of kHz. For QAM and OFDM +frontends the ``frequency`` specifies the absolute frequency and is +given in Hz. + + +.. c:type:: dvb_qpsk_parameters + +QPSK parameters +=============== + +For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters`` +structure: + + +.. code-block:: c + + struct dvb_qpsk_parameters { + uint32_t symbol_rate; /* symbol rate in Symbols per second */ + fe_code_rate_t fec_inner; /* forward error correction (see above) */ + }; + + +.. c:type:: dvb_qam_parameters + +QAM parameters +============== + +for cable QAM frontend you use the ``dvb_qam_parameters`` structure: + + +.. code-block:: c + + struct dvb_qam_parameters { + uint32_t symbol_rate; /* symbol rate in Symbols per second */ + fe_code_rate_t fec_inner; /* forward error correction (see above) */ + fe_modulation_t modulation; /* modulation type (see above) */ + }; + + +.. c:type:: dvb_vsb_parameters + +VSB parameters +============== + +ATSC frontends are supported by the ``dvb_vsb_parameters`` structure: + + +.. code-block:: c + + struct dvb_vsb_parameters { + fe_modulation_t modulation; /* modulation type (see above) */ + }; + + +.. c:type:: dvb_ofdm_parameters + +OFDM parameters +=============== + +DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure: + + +.. code-block:: c + + struct dvb_ofdm_parameters { + fe_bandwidth_t bandwidth; + fe_code_rate_t code_rate_HP; /* high priority stream code rate */ + fe_code_rate_t code_rate_LP; /* low priority stream code rate */ + fe_modulation_t constellation; /* modulation type (see above) */ + fe_transmit_mode_t transmission_mode; + fe_guard_interval_t guard_interval; + fe_hierarchy_t hierarchy_information; + }; diff --git a/Documentation/userspace-api/media/dvb/dvbapi.rst b/Documentation/userspace-api/media/dvb/dvbapi.rst new file mode 100644 index 000000000..4ac0c1bc5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvbapi.rst @@ -0,0 +1,113 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. include:: <isonum.txt> + +.. _dvbapi: + +######################## +Part II - Digital TV API +######################## + +.. note:: + + This API is also known as Linux **DVB API**. + + It it was originally written to support the European digital TV + standard (DVB), and later extended to support all digital TV standards. + + In order to avoid confusion, within this document, it was opted to refer to + it, and to associated hardware as **Digital TV**. + + The word **DVB** is reserved to be used for: + + - the Digital TV API version + (e. g. DVB API version 3 or DVB API version 5); + - digital TV data types (enums, structs, defines, etc); + - digital TV device nodes (``/dev/dvb/...``); + - the European DVB standard. + +**Version 5.10** + +.. toctree:: + :caption: Table of Contents + :maxdepth: 5 + :numbered: + + intro + frontend + demux + ca + net + legacy_dvb_apis + examples + headers + + +********************** +Revision and Copyright +********************** + +Authors: + +- J. K. Metzler, Ralph <rjkm@metzlerbros.de> + + - Original author of the Digital TV API documentation. + +- O. C. Metzler, Marcus <rjkm@metzlerbros.de> + + - Original author of the Digital TV API documentation. + +- Carvalho Chehab, Mauro <mchehab+samsung@kernel.org> + + - Ported document to Docbook XML, addition of DVBv5 API, documentation gaps fix. + +**Copyright** |copy| 2002-2003 : Convergence GmbH + +**Copyright** |copy| 2009-2017 : Mauro Carvalho Chehab + +**************** +Revision History +**************** + +:revision: 2.2.0 / 2017-09-01 (*mcc*) + +Most gaps between the uAPI document and the Kernel implementation +got fixed for the non-legacy API. + +:revision: 2.1.0 / 2015-05-29 (*mcc*) + +DocBook improvements and cleanups, in order to document the system calls +on a more standard way and provide more description about the current +Digital TV API. + +:revision: 2.0.4 / 2011-05-06 (*mcc*) + +Add more information about DVBv5 API, better describing the frontend +GET/SET props ioctl's. + + +:revision: 2.0.3 / 2010-07-03 (*mcc*) + +Add some frontend capabilities flags, present on kernel, but missing at +the specs. + + +:revision: 2.0.2 / 2009-10-25 (*mcc*) + +documents FE_SET_FRONTEND_TUNE_MODE and +FE_DISHETWORK_SEND_LEGACY_CMD ioctls. + + +:revision: 2.0.1 / 2009-09-16 (*mcc*) + +Added ISDB-T test originally written by Patrick Boettcher + + +:revision: 2.0.0 / 2009-09-06 (*mcc*) + +Conversion from LaTex to DocBook XML. The contents is the same as the +original LaTex version. + + +:revision: 1.0.0 / 2003-07-24 (*rjkm*) + +Initial revision on LaTEX. diff --git a/Documentation/userspace-api/media/dvb/dvbproperty.rst b/Documentation/userspace-api/media/dvb/dvbproperty.rst new file mode 100644 index 000000000..981da20af --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvbproperty.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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, +the demodulator, the Linear Low-noise Amplifier (LNA) and to set the +antenna subsystem via Satellite Equipment Control - SEC (on satellite +systems). The actual parameters are specific to each particular digital +TV standards, and may change as the digital TV specs evolves. + +In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a +union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and +ATSC delivery systems grouped there. The problem is that, as the second +generation standards appeared, the size of such union was not big +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. 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 supports all digital TV delivery systems. + +.. note:: + + 1. On Linux DVB API version 3, setting a frontend was done via + struct :c:type:`dvb_frontend_parameters`. + + 2. Don't use DVB API version 3 calls on hardware with supports + newer standards. Such API provides no support or a very limited + support to new standards and/or new hardware. + + 3. Nowadays, most frontends support multiple delivery systems. + Only with DVB API version 5 calls it is possible to switch between + the multiple delivery systems supported by a frontend. + + 4. DVB API version 5 is also called *S2API*, as the first + new standard added to it was DVB-S2. + +**Example**: in order to set the hardware to tune into a DVB-C channel +at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217 +Mbauds, those properties should be sent to +:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl: + + :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` = SYS_DVBC_ANNEX_A + + :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000 + + :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256 + + :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO + + :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000 + + :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4 + + :ref:`DTV_TUNE <DTV-TUNE>` + +The code that would that would do the above is show in +:ref:`dtv-prop-example`. + +.. code-block:: c + :caption: Example: Setting digital TV frontend properties + :name: dtv-prop-example + + #include <stdio.h> + #include <fcntl.h> + #include <sys/ioctl.h> + #include <linux/dvb/frontend.h> + + static struct dtv_property props[] = { + { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A }, + { .cmd = DTV_FREQUENCY, .u.data = 651000000 }, + { .cmd = DTV_MODULATION, .u.data = QAM_256 }, + { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO }, + { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 }, + { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 }, + { .cmd = DTV_TUNE } + }; + + static struct dtv_properties dtv_prop = { + .num = 6, .props = props + }; + + int main(void) + { + int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR); + + if (!fd) { + perror ("open"); + return -1; + } + if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) { + perror("ioctl"); + return -1; + } + printf("Frontend set\\n"); + return 0; + } + +.. attention:: While it is possible to directly call the Kernel code like the + above example, it is strongly recommended to use + `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it + provides abstraction to work with the supported digital TV standards and + provides methods for usual operations like program scanning and to + read/write channel descriptor files. + +.. toctree:: + :maxdepth: 1 + + fe_property_parameters + frontend-stat-properties + frontend-property-terrestrial-systems + frontend-property-cable-systems + frontend-property-satellite-systems + frontend-header diff --git a/Documentation/userspace-api/media/dvb/dvbstb.svg b/Documentation/userspace-api/media/dvb/dvbstb.svg new file mode 100644 index 000000000..6f0ba98f9 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvbstb.svg @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later --> +<svg id="svg2" width="15.847cm" height="8.4187cm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 23770.123 12628.122" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><defs id="defs142"><marker id="Arrow1Lend" overflow="visible" orient="auto"><path id="path954" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker><marker id="marker1243" overflow="visible" orient="auto"><path id="path1241" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker></defs><metadata id="metadata519"><rdf:RDF><cc:Work +rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><rect id="rect197" class="BoundingBox" x="5355.1" y="13.122" width="18403" height="9603" fill="none"/><path id="path199" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="#fff"/><path id="path201" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="none" stroke="#000"/><rect id="rect206" class="BoundingBox" x="13.122" y="4013.1" width="4544" height="2403" fill="none"/><path id="path208" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path210" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text212" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan214" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan216" class="TextPosition" +x="1013.1317" y="5435.1221"><tspan id="tspan218" fill="#000000">Antenna</tspan></tspan></tspan></text> +<rect id="rect223" class="BoundingBox" x="6213.1" y="1813.1" width="4544" height="2403" fill="none"/><path id="path225" d="m8485.1 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path227" d="m8485.1 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text229" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan231" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan233" class="TextPosition" x="7217.1221" y="3235.1221"><tspan id="tspan235" fill="#000000">Frontend</tspan></tspan></tspan></text> +<rect id="rect240" class="BoundingBox" x="12113" y="1813.1" width="4544" height="2403" fill="none"/><path id="path242" d="m14385 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path244" d="m14385 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text246" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan248" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan250" class="TextPosition" x="13944.122" y="3235.1221"><tspan id="tspan252" fill="#000000">CA</tspan></tspan></tspan></text> +<rect id="rect257" class="BoundingBox" x="18113" y="1813.1" width="4544" height="2403" fill="none"/><path id="path259" d="m20385 4214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path261" d="m20385 4214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text263" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan265" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan267" class="TextPosition" x="19384.123" y="3235.1221"><tspan id="tspan269" fill="#000000">Demux</tspan></tspan></tspan></text> +<rect id="rect274" class="BoundingBox" x="6113.1" y="5813.1" width="4544" height="2403" fill="none"/><path id="path276" d="m8385.1 8214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path278" d="m8385.1 8214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text280" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan282" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan284" class="TextPosition" x="7733.1221" y="7235.1221"><tspan id="tspan286" fill="#000000">SEC</tspan></tspan></tspan></text> +<rect id="rect291" class="BoundingBox" x="12213" y="5813.1" width="4544" height="2403" fill="none"/><path id="path293" d="m14485 8214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path295" d="m14485 8214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><text id="text297" class="TextShape" x="-2443.8779" y="-4903.3779"><tspan id="tspan299" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan301" class="TextPosition" x="13676.122" y="6917.6221"><tspan id="tspan303" fill="#000000">Audio</tspan></tspan></tspan></text> +<rect id="rect308" class="BoundingBox" x="18113" y="5813.1" width="4544" height="2403" fill="none"/><path id="path310" d="m20385 8214.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path312" d="m20385 8214.1h-2271v-2400h4541v2400z" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><text id="text314" class="TextShape" x="-2443.8779" y="-4903.3779"><tspan id="tspan316" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan318" class="TextPosition" x="19583.123" y="6917.6221"><tspan id="tspan320" fill="#000000">Video</tspan></tspan></tspan></text> +<rect id="rect325" class="BoundingBox" x="15213" y="10213" width="4544" height="2403" fill="none"/><path id="path327" d="m17485 12614h-2271v-2400h4541v2400z" fill="#fff"/><path id="path329" d="m17485 12614h-2271v-2400h4541v2400z" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><text id="text331" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan333" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan335" class="TextPosition" x="17076.123" y="11635.122"><tspan id="tspan337" fill="#000000">TV</tspan></tspan></tspan></text> +<rect id="rect342" class="BoundingBox" x="4555.1" y="3014.1" width="1661" height="2202" fill="none"/><path id="path344" d="m4556.1 5214.1 1400-1857" fill="none" stroke="#000"/><path id="path346" d="m6215.1 3014.1-391 269 240 181z"/><rect id="rect351" class="BoundingBox" x="4555.1" y="5213.1" width="1561" height="1802" fill="none"/><path id="path353" d="m4556.1 5214.1 1277 1475" fill="none" stroke="#000"/><path id="path355" d="m6115.1 7014.1-181-438-227 196z"/><rect id="rect360" class="BoundingBox" x="10755" y="2864.1" width="1361" height="301" fill="none"/><path id="path362" d="m10756 3014.1h929" fill="none" stroke="#000"/><path id="path364" d="m12115 3014.1-450-150v300z"/><rect id="rect369" class="BoundingBox" x="16655" y="2864.1" width="1461" height="301" fill="none"/><path id="path371" d="m16656 3014.1h1029" fill="none" stroke="#000"/><path id="path373" d="m18115 +3014.1-450-150v300z"/><rect id="rect378" class="BoundingBox" x="20235" y="4213.1" width="301" height="1602" fill="none"/><rect id="rect387" class="BoundingBox" x="17485" y="8213.1" width="2902" height="2002" fill="none"/><path id="path389" d="m20385 8214.1-2546 1756" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><path id="path391" d="m17485 10214 456-132-171-247z"/><rect id="rect396" class="BoundingBox" x="14484" y="8213.1" width="3002" height="2002" fill="none"/><path id="path398" d="m14485 8214.1 2642 1761" fill="none" stroke="#000" stroke-dasharray="28.22200113,56.44400226" stroke-width="28.222"/><path id="path400" d="m17485 10214-291-374-167 249z"/><rect id="rect405" class="BoundingBox" x="14485" y="4213.1" width="5902" height="1629" fill="none"/><path id="path949" d="m20387 4213.1v1629" fill="none" marker-end="url(#Arrow1Lend)" +stroke="#000" stroke-dasharray="26.45879596, 52.91759192999999328" stroke-linejoin="miter" stroke-width="26.459"/><path id="path1233" d="m20385 4214.1-3628 1599" fill="none" marker-end="url(#marker1243)" stroke="#000" stroke-dasharray="26.45879596, 52.91759193" stroke-linejoin="miter" stroke-width="26.459"/><text id="text297-3" class="TextShape" x="-2911.9202" y="-4257.2061" font-size="12px" stroke-width="1"><tspan id="tspan299-6" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400" stroke-width="1"><tspan id="tspan301-7" class="TextPosition" x="13208.079" y="7563.793" stroke-width="1"><tspan id="tspan303-5" fill="#000000" stroke-width="1">Decoder</tspan></tspan></tspan></text> +<text id="text297-3-3" class="TextShape" x="2950.9287" y="-4259.5928" font-size="12px" stroke-width="1"><tspan id="tspan299-6-5" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400" stroke-width="1"><tspan id="tspan301-7-6" class="TextPosition" x="19070.928" y="7561.4053" stroke-width="1"><tspan id="tspan303-5-2" fill="#000000" stroke-width="1">Decoder</tspan></tspan></tspan></text> +</svg> diff --git a/Documentation/userspace-api/media/dvb/examples.rst b/Documentation/userspace-api/media/dvb/examples.rst new file mode 100644 index 000000000..086587c65 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/examples.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_examples: + +******** +Examples +******** + +In the past, we used to have a set of examples here. However, those +examples got out of date and doesn't even compile nowadays. + +Also, nowadays, the best is to use the libdvbv5 DVB API nowadays, +with is fully documented. + +Please refer to the `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__ +for updated/recommended examples. diff --git a/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst b/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst new file mode 100644 index 000000000..904b0c33a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +****************** +Frontend bandwidth +****************** + +.. c:type:: fe_bandwidth + +.. flat-table:: enum fe_bandwidth + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _BANDWIDTH-AUTO: + + ``BANDWIDTH_AUTO`` + + - Autodetect bandwidth (if supported) + + - .. row 3 + + - .. _BANDWIDTH-1-712-MHZ: + + ``BANDWIDTH_1_712_MHZ`` + + - 1.712 MHz + + - .. row 4 + + - .. _BANDWIDTH-5-MHZ: + + ``BANDWIDTH_5_MHZ`` + + - 5 MHz + + - .. row 5 + + - .. _BANDWIDTH-6-MHZ: + + ``BANDWIDTH_6_MHZ`` + + - 6 MHz + + - .. row 6 + + - .. _BANDWIDTH-7-MHZ: + + ``BANDWIDTH_7_MHZ`` + + - 7 MHz + + - .. row 7 + + - .. _BANDWIDTH-8-MHZ: + + ``BANDWIDTH_8_MHZ`` + + - 8 MHz + + - .. row 8 + + - .. _BANDWIDTH-10-MHZ: + + ``BANDWIDTH_10_MHZ`` + + - 10 MHz diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst new file mode 100644 index 000000000..d9be817f0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISEQC_RECV_SLAVE_REPLY: + +******************************** +ioctl FE_DISEQC_RECV_SLAVE_REPLY +******************************** + +Name +==== + +FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command + +Synopsis +======== + +.. c:macro:: FE_DISEQC_RECV_SLAVE_REPLY + +``int ioctl(int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + pointer to struct :c:type:`dvb_diseqc_slave_reply`. + +Description +=========== + +Receives reply from a DiSEqC 2.0 command. + +The received message is stored at the buffer pointed by ``argp``. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst new file mode 100644 index 000000000..d36f7d115 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISEQC_RESET_OVERLOAD: + +****************************** +ioctl FE_DISEQC_RESET_OVERLOAD +****************************** + +Name +==== + +FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload. + +Synopsis +======== + +.. c:macro:: FE_DISEQC_RESET_OVERLOAD + +``int ioctl(int fd, FE_DISEQC_RESET_OVERLOAD, NULL)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +=========== + +If the bus has been automatically powered off due to power overload, +this ioctl call restores the power to the bus. The call requires +read/write access to the device. This call has no effect if the device +is manually powered off. Not all Digital TV adapters support this ioctl. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst new file mode 100644 index 000000000..6ac1e5cd5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISEQC_SEND_BURST: + +************************** +ioctl FE_DISEQC_SEND_BURST +************************** + +Name +==== + +FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection. + +Synopsis +======== + +.. c:macro:: FE_DISEQC_SEND_BURST + +``int ioctl(int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``tone`` + An integer enumerated value described at :c:type:`fe_sec_mini_cmd`. + +Description +=========== + +This ioctl is used to set the generation of a 22kHz tone burst for mini +DiSEqC satellite selection for 2x1 switches. This call requires +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>`__ + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst new file mode 100644 index 000000000..c97029def --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISEQC_SEND_MASTER_CMD: + +******************************* +ioctl FE_DISEQC_SEND_MASTER_CMD +******************************* + +Name +==== + +FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command + +Synopsis +======== + +.. c:macro:: FE_DISEQC_SEND_MASTER_CMD + +``int ioctl(int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + pointer to struct + :c:type:`dvb_diseqc_master_cmd` + +Description +=========== + +Sends the DiSEqC command pointed by :c:type:`dvb_diseqc_master_cmd` +to the antenna subsystem. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + diff --git a/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst new file mode 100644 index 000000000..d1dba74c5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISHNETWORK_SEND_LEGACY_CMD: + +****************************** +FE_DISHNETWORK_SEND_LEGACY_CMD +****************************** + +Name +==== + +FE_DISHNETWORK_SEND_LEGACY_CMD + +Synopsis +======== + +.. c:macro:: FE_DISHNETWORK_SEND_LEGACY_CMD + +``int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``cmd`` + Sends the specified raw cmd to the dish via DISEqC. + +Description +=========== + +.. warning:: + This is a very obscure legacy command, used only at stv0299 + driver. Should not be used on newer drivers. + +It provides a non-standard method for selecting Diseqc voltage on the +frontend, for Dish Network legacy switches. + +As support for this ioctl were added in 2004, this means that such +dishes were already legacy in 2004. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst new file mode 100644 index 000000000..40d7320f8 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_ENABLE_HIGH_LNB_VOLTAGE: + +******************************** +ioctl FE_ENABLE_HIGH_LNB_VOLTAGE +******************************** + +Name +==== + +FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages. + +Synopsis +======== + +.. c:macro:: FE_ENABLE_HIGH_LNB_VOLTAGE + +``int ioctl(int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``high`` + Valid flags: + + - 0 - normal 13V and 18V. + + - >0 - enables slightly higher voltages instead of 13/18V, in order + to compensate for long antenna cables. + +Description +=========== + +Select output DC level between normal LNBf voltages or higher LNBf +voltages between 0 (normal) or a value grater than 0 for higher +voltages. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-get-event.rst b/Documentation/userspace-api/media/dvb/fe-get-event.rst new file mode 100644 index 000000000..f63029eca --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-get-event.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_GET_EVENT: + +************ +FE_GET_EVENT +************ + +Name +==== + +FE_GET_EVENT + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_GET_EVENT + +``int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``ev`` + Points to the location where the event, if any, is to be stored. + +Description +=========== + +This ioctl call returns a frontend 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 is returned, and the ``errno`` variable is set +appropriately. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. row 1 + + - ``EWOULDBLOCK`` + + - There is no event pending, and the device is in non-blocking mode. + + - .. row 2 + + - ``EOVERFLOW`` + + - Overflow in event queue - one or more events were lost. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-get-frontend.rst b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst new file mode 100644 index 000000000..40700533e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_GET_FRONTEND: + +*************** +FE_GET_FRONTEND +*************** + +Name +==== + +FE_GET_FRONTEND + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_GET_FRONTEND + +``int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``p`` + Points to parameters for tuning operation. + +Description +=========== + +This ioctl call queries the currently effective frontend parameters. For +this command, read-only access to the device is sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. row 1 + + - ``EINVAL`` + + - Maximum supported symbol rate reached. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-get-info.rst b/Documentation/userspace-api/media/dvb/fe-get-info.rst new file mode 100644 index 000000000..2e5f02098 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-get-info.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_GET_INFO: + +***************** +ioctl FE_GET_INFO +***************** + +Name +==== + +FE_GET_INFO - Query Digital TV frontend capabilities and returns information +about the - front-end. This call only requires read-only access to the device. + +Synopsis +======== + +.. c:macro:: FE_GET_INFO + +``int ioctl(int fd, FE_GET_INFO, struct dvb_frontend_info *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + pointer to struct :c:type:`dvb_frontend_info` + +Description +=========== + +All Digital TV frontend devices support the :ref:`FE_GET_INFO` ioctl. It is +used to identify kernel devices compatible with this specification and to +obtain information about driver and hardware capabilities. The ioctl +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. + +frontend capabilities +===================== + +Capabilities describe what a frontend can do. Some capabilities are +supported only on some specific frontend types. + +The frontend capabilities are described at :c:type:`fe_caps`. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-get-property.rst b/Documentation/userspace-api/media/dvb/fe-get-property.rst new file mode 100644 index 000000000..29363dc4a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-get-property.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_GET_PROPERTY: + +************************************** +ioctl FE_SET_PROPERTY, FE_GET_PROPERTY +************************************** + +Name +==== + +FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties. + +Synopsis +======== + +.. c:macro:: FE_GET_PROPERTY + +``int ioctl(int fd, FE_GET_PROPERTY, struct dtv_properties *argp)`` + +.. c:macro:: FE_SET_PROPERTY + +``int ioctl(int fd, FE_SET_PROPERTY, struct dtv_properties *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dtv_properties`. + +Description +=========== + +All Digital TV frontend devices support the ``FE_SET_PROPERTY`` and +``FE_GET_PROPERTY`` ioctls. The supported properties and statistics +depends on the delivery system and on the device: + +- ``FE_SET_PROPERTY:`` + + - This ioctl is used to set one or more frontend properties. + + - This is the basic command to request the frontend to tune into + some frequency and to start decoding the digital TV signal. + + - This call requires read/write access to the device. + +.. note:: + + At return, the values aren't updated to reflect the actual + parameters used. If the actual parameters are needed, an explicit + call to ``FE_GET_PROPERTY`` is needed. + +- ``FE_GET_PROPERTY:`` + + - This ioctl is used to get properties and statistics from the + frontend. + + - No properties are changed, and statistics aren't reset. + + - This call only requires read-only access to the device. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-ber.rst b/Documentation/userspace-api/media/dvb/fe-read-ber.rst new file mode 100644 index 000000000..f33f1dd20 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-ber.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_BER: + +*********** +FE_READ_BER +*********** + +Name +==== + +FE_READ_BER + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_READ_BER + +``int ioctl(int fd, FE_READ_BER, uint32_t *ber)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``ber`` + The bit error rate is stored into \*ber. + +Description +=========== + +This ioctl call returns the bit error rate for the signal currently +received/demodulated by the front-end. For this command, read-only +access to the device is sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst new file mode 100644 index 000000000..2b7d06145 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_SIGNAL_STRENGTH: + +*********************** +FE_READ_SIGNAL_STRENGTH +*********************** + +Name +==== + +FE_READ_SIGNAL_STRENGTH + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_READ_SIGNAL_STRENGTH + +``int ioctl(int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``strength`` + The signal strength value is stored into \*strength. + +Description +=========== + +This ioctl call returns the signal strength value for the signal +currently received by the front-end. For this command, read-only access +to the device is sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-snr.rst b/Documentation/userspace-api/media/dvb/fe-read-snr.rst new file mode 100644 index 000000000..e44e559ab --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-snr.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_SNR: + +*********** +FE_READ_SNR +*********** + +Name +==== + +FE_READ_SNR + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_READ_SNR + +``int ioctl(int fd, FE_READ_SNR, int16_t *snr)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``snr`` + The signal-to-noise ratio is stored into \*snr. + +Description +=========== + +This ioctl call returns the signal-to-noise ratio for the signal +currently received by the front-end. For this command, read-only access +to the device is sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-status.rst b/Documentation/userspace-api/media/dvb/fe-read-status.rst new file mode 100644 index 000000000..75c6ee60a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-status.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_STATUS: + +******************** +ioctl FE_READ_STATUS +******************** + +Name +==== + +FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device + +Synopsis +======== + +.. c:macro:: FE_READ_STATUS + +``int ioctl(int fd, FE_READ_STATUS, unsigned int *status)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``status`` + pointer to a bitmask integer filled with the values defined by enum + :c:type:`fe_status`. + +Description +=========== + +All Digital TV frontend devices support the ``FE_READ_STATUS`` ioctl. It is +used to check about the locking status of the frontend after being +tuned. The ioctl takes a pointer to an integer where the status will be +written. + +.. note:: + + The size of status is actually sizeof(enum fe_status), with + varies according with the architecture. This needs to be fixed in the + future. + +int fe_status +============= + +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 + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst new file mode 100644 index 000000000..653cd99a6 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_UNCORRECTED_BLOCKS: + +************************** +FE_READ_UNCORRECTED_BLOCKS +************************** + +Name +==== + +FE_READ_UNCORRECTED_BLOCKS + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_READ_UNCORRECTED_BLOCKS + +``int ioctl(int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``ublocks`` + The total number of uncorrected blocks seen by the driver so far. + +Description +=========== + +This ioctl call returns the number of uncorrected blocks detected by the +device driver during its lifetime. For meaningful measurements, the +increment in block count during a specific time interval should be +calculated. For this command, read-only access to the device is +sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst new file mode 100644 index 000000000..56923c1a6 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_SET_FRONTEND_TUNE_MODE: + +******************************* +ioctl FE_SET_FRONTEND_TUNE_MODE +******************************* + +Name +==== + +FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend. + +Synopsis +======== + +.. c:macro:: FE_SET_FRONTEND_TUNE_MODE + +``int ioctl(int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``flags`` + Valid flags: + + - 0 - normal tune mode + + - ``FE_TUNE_MODE_ONESHOT`` - 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. + +Description +=========== + +Allow setting tuner mode flags to the frontend, between 0 (normal) or +``FE_TUNE_MODE_ONESHOT`` mode + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst new file mode 100644 index 000000000..d1b857632 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst @@ -0,0 +1,68 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_SET_FRONTEND: + +*************** +FE_SET_FRONTEND +*************** + +.. attention:: This ioctl is deprecated. + +Name +==== + +FE_SET_FRONTEND + +Synopsis +======== + +.. c:macro:: FE_SET_FRONTEND + +``int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``p`` + Points to parameters for tuning operation. + +Description +=========== + +This ioctl call starts a tuning operation using specified parameters. +The result of this call will be successful if the parameters were valid +and the tuning could be initiated. The result of the tuning operation in +itself, however, will arrive asynchronously as an event (see +documentation for :ref:`FE_GET_EVENT` and +FrontendEvent.) If a new :ref:`FE_SET_FRONTEND` +operation is initiated before the previous one was completed, the +previous operation will be aborted in favor of the new one. This command +requires read/write access to the device. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - .. row 1 + + - ``EINVAL`` + + - Maximum supported symbol rate reached. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-tone.rst b/Documentation/userspace-api/media/dvb/fe-set-tone.rst new file mode 100644 index 000000000..41cd7111a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-set-tone.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_SET_TONE: + +***************** +ioctl FE_SET_TONE +***************** + +Name +==== + +FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone. + +Synopsis +======== + +.. c:macro:: FE_SET_TONE + +``int ioctl(int fd, FE_SET_TONE, enum fe_sec_tone_mode tone)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``tone`` + An integer enumerated value described at :c:type:`fe_sec_tone_mode` + +Description +=========== + +This ioctl is used to set the generation of the continuous 22kHz tone. +This call requires read/write permissions. + +Usually, satellite antenna subsystems require that the digital TV device +to send a 22kHz tone in order to select between high/low band on some +dual-band LNBf. It is also used to send signals to DiSEqC equipment, but +this is done using the DiSEqC ioctls. + +.. attention:: If more than one device is connected to the same antenna, + setting a tone may interfere on other devices, as they may lose the + capability of selecting the band. So, it is recommended that applications + would change to SEC_TONE_OFF when the device is not used. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-voltage.rst b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst new file mode 100644 index 000000000..4d09ca587 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_SET_VOLTAGE: + +******************** +ioctl FE_SET_VOLTAGE +******************** + +Name +==== + +FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem. + +Synopsis +======== + +.. c:macro:: FE_SET_VOLTAGE + +``int ioctl(int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``voltage`` + An integer enumerated value described at :c:type:`fe_sec_voltage` + +Description +=========== + +This ioctl allows to set the DC voltage level sent through the antenna +cable to 13V, 18V or off. + +Usually, a satellite antenna subsystems require that the digital TV +device to send a DC voltage to feed power to the LNBf. Depending on the +LNBf type, the polarization or the intermediate frequency (IF) of the +LNBf can controlled by the voltage level. Other devices (for example, +the ones that implement DISEqC and multipoint LNBf's don't need to +control the voltage level, provided that either 13V or 18V is sent to +power up the LNBf. + +.. attention:: if more than one device is connected to the same antenna, + setting a voltage level may interfere on other devices, as they may lose + the capability of setting polarization or IF. So, on those cases, setting + the voltage to SEC_VOLTAGE_OFF while the device is not is used is + recommended. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-type-t.rst b/Documentation/userspace-api/media/dvb/fe-type-t.rst new file mode 100644 index 000000000..e89862548 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-type-t.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +************* +Frontend type +************* + +For historical reasons, frontend types are named by the type of +modulation used in transmission. The fontend types are given by +fe_type_t type, defined as: + + +.. c:type:: fe_type + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. flat-table:: Frontend types + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - fe_type + + - Description + + - :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` equivalent + type + + - .. row 2 + + - .. _FE-QPSK: + + ``FE_QPSK`` + + - For DVB-S standard + + - ``SYS_DVBS`` + + - .. row 3 + + - .. _FE-QAM: + + ``FE_QAM`` + + - For DVB-C annex A standard + + - ``SYS_DVBC_ANNEX_A`` + + - .. row 4 + + - .. _FE-OFDM: + + ``FE_OFDM`` + + - For DVB-T standard + + - ``SYS_DVBT`` + + - .. row 5 + + - .. _FE-ATSC: + + ``FE_ATSC`` + + - For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used + in US. + + - ``SYS_ATSC`` (terrestrial) or ``SYS_DVBC_ANNEX_B`` (cable) + + +Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described +at the above, as they're supported via the new +:ref:`FE_GET_PROPERTY/FE_GET_SET_PROPERTY <FE_GET_PROPERTY>` +ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` +parameter. + +In the old days, struct :c:type:`dvb_frontend_info` +used to contain ``fe_type_t`` field to indicate the delivery systems, +filled with either ``FE_QPSK, FE_QAM, FE_OFDM`` or ``FE_ATSC``. While this +is still filled to keep backward compatibility, the usage of this field +is deprecated, as it can report just one delivery system, but some +devices support multiple delivery systems. Please use +:ref:`DTV_ENUM_DELSYS <DTV-ENUM-DELSYS>` instead. + +On devices that support multiple delivery systems, struct +:c:type:`dvb_frontend_info`::``fe_type_t`` is +filled with the currently standard, as selected by the last call to +:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` using the +:ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` property. diff --git a/Documentation/userspace-api/media/dvb/fe_property_parameters.rst b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst new file mode 100644 index 000000000..ce962d4a0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst @@ -0,0 +1,1013 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _fe_property_parameters: + +****************************** +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: + +DTV_UNDEFINED +============= + +Used internally. A GET/SET operation for it won't change or return +anything. + + +.. _DTV-TUNE: + +DTV_TUNE +======== + +Interpret the cache of data, build either a traditional frontend +tunerequest so we can pass validation in the ``FE_SET_FRONTEND`` ioctl. + + +.. _DTV-CLEAR: + +DTV_CLEAR +========= + +Reset a cache of data specific to the frontend here. This does not +effect hardware. + + +.. _DTV-FREQUENCY: + +DTV_FREQUENCY +============= + +Frequency of the digital TV transponder/channel. + +.. note:: + + #. For satellite delivery systems, the frequency is in kHz. + + #. For cable and terrestrial delivery systems, the frequency is in + Hz. + + #. On most delivery systems, the frequency is the center frequency + of the transponder/channel. The exception is for ISDB-T, where + the main carrier has a 1/7 offset from the center. + + #. For ISDB-T, the channels are usually transmitted with an offset of + about 143kHz. E.g. a valid frequency could be 474,143 kHz. The + stepping is bound to the bandwidth of the channel which is + typically 6MHz. + + #. In ISDB-Tsb, the channel consists of only one or three segments the + frequency step is 429kHz, 3*429 respectively. + + +.. _DTV-MODULATION: + +DTV_MODULATION +============== + +Specifies the frontend modulation type for delivery systems that +support multiple modulations. + +The modulation can be one of the types defined by enum :c:type:`fe_modulation`. + +Most of the digital TV standards offer 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-C2 QPSK, 16-QAM, 64-QAM, 256-QAM, 1024-QAM and 4096-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. +DVB-S2X 8-APSK-L, 16-APSK-L, 32-APSK-L, 64-APSK and 64-APSK-L. +ISDB-T QPSK, DQPSK, 16-QAM and 64-QAM. +ISDB-S 8-PSK, QPSK and BPSK. +======================= ======================================================= + +.. note:: + + As DVB-S2X specifies extensions to the DVB-S2 standard, the same + delivery system enum value is used (SYS_DVBS2). + + 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: + +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``. + +======================= ======================================================= +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:: + + + #. For ISDB-Tsb, the bandwidth can vary depending on the number of + connected segments. + + 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. The kernel will silently ignore any :ref:`DTV-BANDWIDTH-HZ` + setting and overwrites it with 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: + +DTV_INVERSION +============= + +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 +================= + +Currently not implemented. + + +.. _DTV-SYMBOL-RATE: + +DTV_SYMBOL_RATE +=============== + +Used on cable and satellite delivery systems. + +Digital TV symbol rate, in bauds (symbols/second). + + +.. _DTV-INNER-FEC: + +DTV_INNER_FEC +============= + +Used on cable and satellite delivery systems. + +The acceptable values are defined by :c:type:`fe_code_rate`. + + +.. _DTV-VOLTAGE: + +DTV_VOLTAGE +=========== + +Used on satellite delivery systems. + +The voltage is usually used with non-DiSEqC capable LNBs to switch the +polarization (horizontal/vertical). When using DiSEqC equipment this +voltage has to be switched consistently to the DiSEqC commands as +described in the DiSEqC spec. + +The acceptable values are defined by :c:type:`fe_sec_voltage`. + + +.. _DTV-TONE: + +DTV_TONE +======== + +Currently not used. + + +.. _DTV-PILOT: + +DTV_PILOT +========= + +Used on DVB-S2. + +Sets DVB-S2 pilot. + +The acceptable values are defined by :c:type:`fe_pilot`. + + +.. _DTV-ROLLOFF: + +DTV_ROLLOFF +=========== + +Used on DVB-S2. + +Sets DVB-S2 rolloff. + +The acceptable values are defined by :c:type:`fe_rolloff`. + + +.. _DTV-DISEQC-SLAVE-REPLY: + +DTV_DISEQC_SLAVE_REPLY +====================== + +Currently not implemented. + + +.. _DTV-FE-CAPABILITY-COUNT: + +DTV_FE_CAPABILITY_COUNT +======================= + +Currently not implemented. + + +.. _DTV-FE-CAPABILITY: + +DTV_FE_CAPABILITY +================= + +Currently not implemented. + + +.. _DTV-DELIVERY-SYSTEM: + +DTV_DELIVERY_SYSTEM +=================== + +Specifies the type of the delivery system. + +The acceptable values are defined by :c:type:`fe_delivery_system`. + + +.. _DTV-ISDBT-PARTIAL-RECEPTION: + +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. + +If '1' ``DTV_ISDBT_LAYERA_*`` values are assigned to the center segment +and ``DTV_ISDBT_LAYERA_SEGMENT_COUNT`` has to be '1'. + +If in addition ``DTV_ISDBT_SOUND_BROADCASTING`` is '1' +``DTV_ISDBT_PARTIAL_RECEPTION`` represents whether this ISDB-Tsb channel +is consisting of one segment and layer or three segments and two layers. + +Possible values: 0, 1, -1 (AUTO) + + +.. _DTV-ISDBT-SOUND-BROADCASTING: + +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``). + +Possible values: 0, 1, -1 (AUTO) + + +.. _DTV-ISDBT-SB-SUBCHANNEL-ID: + +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 +``SUBCHANNEL-ID`` in all details, but it is my understanding of the +technical background needed to program a device) + +An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a +set of connected ISDB-Tsb channels. In this set of channels every +channel can be received independently. The number of connected ISDB-Tsb +segment can vary, e.g. depending on the frequency spectrum bandwidth +available. + +Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The +broadcaster has several possibilities to put those channels in the air: +Assuming a normal 13-segment ISDB-T spectrum he can align the 8 segments +from position 1-8 to 5-13 or anything in between. + +The underlying layer of segments are sub-channels: each segment is +consisting of several sub-channels with a predefined IDs. A sub-channel +is used to help the demodulator to synchronize on the channel. + +An ISDB-T channel is always centered over all sub-channels. As for the +example above, in ISDB-Tsb it is no longer as simple as that. + +``The DTV_ISDBT_SB_SUBCHANNEL_ID`` parameter is used to give the +sub-channel ID of the segment to be demodulated. + +Possible values: 0 .. 41, -1 (AUTO) + + +.. _DTV-ISDBT-SB-SEGMENT-IDX: + +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 +demodulated for an ISDB-Tsb channel where several of them are +transmitted in the connected manner. + +Possible values: 0 .. ``DTV_ISDBT_SB_SEGMENT_COUNT`` - 1 + +Note: This value cannot be determined by an automatic channel search. + + +.. _DTV-ISDBT-SB-SEGMENT-COUNT: + +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 +ISDB-Tsb channels. + +Possible values: 1 .. 13 + +Note: This value cannot be determined by an automatic channel search. + + +.. _isdb-hierq-layers: + +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. + +ISDB-T has 3 hierarchical layers which each can use a part of the +available segments. The total number of segments over all layers has to +13 in ISDB-T. + +There are 3 parameter sets, for Layers A, B and C. + + +.. _DTV-ISDBT-LAYER-ENABLED: + +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 +be demodulated. This is the default. + +If the channel is in the partial reception mode +(``DTV_ISDBT_PARTIAL_RECEPTION`` = 1) the central segment can be decoded +independently of the other 12 segments. In that mode layer A has to have +a ``SEGMENT_COUNT`` of 1. + +In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb according +to ``DTV_ISDBT_PARTIAL_RECEPTION``. ``SEGMENT_COUNT`` must be filled +accordingly. + +Only the values of the first 3 bits are used. Other bits will be silently ignored: + +``DTV_ISDBT_LAYER_ENABLED`` bit 0: layer A enabled + +``DTV_ISDBT_LAYER_ENABLED`` bit 1: layer B enabled + +``DTV_ISDBT_LAYER_ENABLED`` bit 2: layer C enabled + +``DTV_ISDBT_LAYER_ENABLED`` bits 3-31: unused + + +.. _DTV-ISDBT-LAYER-FEC: + +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`. + + +Possible values are: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``, +``FEC_5_6``, ``FEC_7_8`` + + +.. _DTV-ISDBT-LAYER-MODULATION: + +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`. + +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: + +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 +``DTV_ISDBT_PARTIAL_RECEPTION`` and ``LAYER[A-C]_SEGMENT_COUNT`` + +.. _isdbt-layer_seg-cnt-table: + +.. flat-table:: Truth table for ISDB-T Sound Broadcasting + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Partial Reception + + - Sound Broadcasting + + - Layer A width + + - Layer B width + + - Layer C width + + - total width + + - .. row 2 + + - 0 + + - 0 + + - 1 .. 13 + + - 1 .. 13 + + - 1 .. 13 + + - 13 + + - .. row 3 + + - 1 + + - 0 + + - 1 + + - 1 .. 13 + + - 1 .. 13 + + - 13 + + - .. row 4 + + - 0 + + - 1 + + - 1 + + - 0 + + - 0 + + - 1 + + - .. row 5 + + - 1 + + - 1 + + - 1 + + - 2 + + - 0 + + - 13 + + + +.. _DTV-ISDBT-LAYER-TIME-INTERLEAVING: + +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. + +Note: The real time interleaving length depends on the mode (fft-size). +The values here are referring to what can be found in the +TMCC-structure, as shown in the table below. + + +.. c:type:: isdbt_layer_interleaving_table + +.. flat-table:: ISDB-T time interleaving modes + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ``DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING`` + + - Mode 1 (2K FFT) + + - Mode 2 (4K FFT) + + - Mode 3 (8K FFT) + + - .. row 2 + + - 0 + + - 0 + + - 0 + + - 0 + + - .. row 3 + + - 1 + + - 4 + + - 2 + + - 1 + + - .. row 4 + + - 2 + + - 8 + + - 4 + + - 2 + + - .. row 5 + + - 4 + + - 16 + + - 8 + + - 4 + + + +.. _DTV-ATSCMH-FIC-VER: + +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 +by the receiver. + +Possible values: 0, 1, 2, 3, ..., 30, 31 + + +.. _DTV-ATSCMH-PARADE-ID: + +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 +ensembles. + +Possible values: 0, 1, 2, 3, ..., 126, 127 + + +.. _DTV-ATSCMH-NOG: + +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 + + +.. _DTV-ATSCMH-TNOG: + +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. + +Possible values: 0, 1, 2, 3, ..., 30, 31 + + +.. _DTV-ATSCMH-SGN: + +DTV_ATSCMH_SGN +-------------- + +Used only on ATSC-MH. + +Start group number. + +Possible values: 0, 1, 2, 3, ..., 14, 15 + + +.. _DTV-ATSCMH-PRC: + +DTV_ATSCMH_PRC +-------------- + +Used only on ATSC-MH. + +Parade repetition cycle. + +Possible values: 1, 2, 3, 4, 5, 6, 7, 8 + + +.. _DTV-ATSCMH-RS-FRAME-MODE: + +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`. + + +.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE: + +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`. + + +.. _DTV-ATSCMH-RS-CODE-MODE-PRI: + +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`. + + +.. _DTV-ATSCMH-RS-CODE-MODE-SEC: + +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`. + + +.. _DTV-ATSCMH-SCCC-BLOCK-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`. + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-A: + +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`. + +.. _DTV-ATSCMH-SCCC-CODE-MODE-B: + +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 +:c:type:`atscmh_sccc_code_mode`. + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-C: + +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 +:c:type:`atscmh_sccc_code_mode`. + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-D: + +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 +:c:type:`atscmh_sccc_code_mode`. + + +.. _DTV-API-VERSION: + +DTV_API_VERSION +=============== + +Returns the major/minor version of the Digital TV API + + +.. _DTV-CODE-RATE-HP: + +DTV_CODE_RATE_HP +================ + +Used on terrestrial transmissions. + +The acceptable values are defined by :c:type:`fe_transmit_mode`. + + +.. _DTV-CODE-RATE-LP: + +DTV_CODE_RATE_LP +================ + +Used on terrestrial transmissions. + +The acceptable values are defined by :c:type:`fe_transmit_mode`. + + +.. _DTV-GUARD-INTERVAL: + +DTV_GUARD_INTERVAL +================== + +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. + #. Interval ``GUARD_INTERVAL_1_64`` is used only for DVB-C2. + #. Interval ``GUARD_INTERVAL_1_128`` is used for both DVB-C2 and DVB_T2. + #. Intervals ``GUARD_INTERVAL_19_128`` and ``GUARD_INTERVAL_19_256`` are + used only for DVB-T2. + #. 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 +===================== + + +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. + +The acceptable values are defined by :c:type:`fe_transmit_mode`. + +.. note:: + + #. ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called + **mode** on such standard, and are numbered from 1 to 3: + + ==== ======== ======================== + Mode FFT size Transmission mode + ==== ======== ======================== + 1 2K ``TRANSMISSION_MODE_2K`` + 2 4K ``TRANSMISSION_MODE_4K`` + 3 8K ``TRANSMISSION_MODE_8K`` + ==== ======== ======================== + + #. 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. + + #. DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K. + + #. DTMB specifies C1 and C3780. + + +.. _DTV-HIERARCHY: + +DTV_HIERARCHY +============= + +Used only on DVB-T and DVB-T2. + +Frontend hierarchy. + +The acceptable values are defined by :c:type:`fe_hierarchy`. + + +.. _DTV-STREAM-ID: + +DTV_STREAM_ID +============= + +Used on DVB-C2, DVB-S2, DVB-T2 and ISDB-S. + +DVB-C2, DVB-S2, DVB-T2 and ISDB-S support the transmission of several +streams on a single transport stream. This property enables the digital +TV driver to handle substream filtering, when supported by the hardware. +By default, substream filtering is disabled. + +For DVB-C2, DVB-S2 and DVB-T2, the valid substream id range is from 0 to +255. + +For ISDB, the valid substream id range is from 1 to 65535. + +To disable it, you should use the special macro NO_STREAM_ID_FILTER. + +Note: any value outside the id range also disables filtering. + + +.. _DTV-DVBT2-PLP-ID-LEGACY: + +DTV_DVBT2_PLP_ID_LEGACY +======================= + +Obsolete, replaced with DTV_STREAM_ID. + + +.. _DTV-ENUM-DELSYS: + +DTV_ENUM_DELSYS +=============== + +A Multi standard frontend needs to advertise the delivery systems +provided. Applications need to enumerate the provided delivery systems, +before using any other operation with the frontend. Prior to its +introduction, FE_GET_INFO was used to determine a frontend type. A +frontend which provides more than a single delivery system, +FE_GET_INFO doesn't help much. Applications which intends to use a +multistandard frontend must enumerate the delivery systems associated +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. + +The acceptable values are defined by :c:type:`fe_interleaving`. + + +.. _DTV-LNA: + +DTV_LNA +======= + +Low-noise amplifier. + +Hardware might offer controllable LNA which can be set manually using +that parameter. Usually LNA could be found only from terrestrial devices +if at all. + +Possible values: 0, 1, LNA_AUTO + +0, LNA off + +1, LNA on + +use the special macro LNA_AUTO to set LNA auto + + +.. _DTV-SCRAMBLING-SEQUENCE-INDEX: + +DTV_SCRAMBLING_SEQUENCE_INDEX +============================= + +Used on DVB-S2. + +This 18 bit field, when present, carries the index of the DVB-S2 physical +layer scrambling sequence as defined in clause 5.5.4 of EN 302 307. +There is no explicit signalling method to convey scrambling sequence index +to the receiver. If S2 satellite delivery system descriptor is available +it can be used to read the scrambling sequence index (EN 300 468 table 41). + +By default, gold scrambling sequence index 0 is used. + +The valid scrambling sequence index range is from 0 to 262142. diff --git a/Documentation/userspace-api/media/dvb/frontend-header.rst b/Documentation/userspace-api/media/dvb/frontend-header.rst new file mode 100644 index 000000000..77f403361 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-header.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +Frontend uAPI data types +======================== + +.. kernel-doc:: include/uapi/linux/dvb/frontend.h diff --git a/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst new file mode 100644 index 000000000..92ef98964 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend-property-cable-systems: + +***************************************** +Properties used on cable delivery systems +***************************************** + + +.. _dvbc-params: + +DVB-C delivery system +===================== + +The DVB-C Annex-A is the widely used cable standard. Transmission uses +QAM modulation. + +The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It +supports a subset of the Annex A modulation types, and a roll-off of +0.13, instead of 0.15 + +The following parameters are valid for DVB-C Annex A/C: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_MODULATION <DTV-MODULATION>` + +- :ref:`DTV_INVERSION <DTV-INVERSION>` + +- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` + +- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` + +- :ref:`DTV_LNA <DTV-LNA>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. + + +.. _dvbc-annex-b-params: + +DVB-C Annex B delivery system +============================= + +The DVB-C Annex-B is only used on a few Countries like the United +States. + +The following parameters are valid for DVB-C Annex B: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_MODULATION <DTV-MODULATION>` + +- :ref:`DTV_INVERSION <DTV-INVERSION>` + +- :ref:`DTV_LNA <DTV-LNA>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. diff --git a/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst new file mode 100644 index 000000000..13b344b28 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst @@ -0,0 +1,105 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend-property-satellite-systems: + +********************************************* +Properties used on satellite delivery systems +********************************************* + + +.. _dvbs-params: + +DVB-S delivery system +===================== + +The following parameters are valid for DVB-S: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_INVERSION <DTV-INVERSION>` + +- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` + +- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` + +- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>` + +- :ref:`DTV_TONE <DTV-TONE>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. + +Future implementations might add those two missing parameters: + +- :ref:`DTV_DISEQC_MASTER <DTV-DISEQC-MASTER>` + +- :ref:`DTV_DISEQC_SLAVE_REPLY <DTV-DISEQC-SLAVE-REPLY>` + + +.. _dvbs2-params: + +DVB-S2 delivery system +====================== + +In addition to all parameters valid for DVB-S, DVB-S2 supports the +following parameters: + +- :ref:`DTV_MODULATION <DTV-MODULATION>` + +- :ref:`DTV_PILOT <DTV-PILOT>` + +- :ref:`DTV_ROLLOFF <DTV-ROLLOFF>` + +- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>` + +- :ref:`DTV_SCRAMBLING_SEQUENCE_INDEX <DTV-SCRAMBLING-SEQUENCE-INDEX>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. + + +.. _turbo-params: + +Turbo code delivery system +========================== + +In addition to all parameters valid for DVB-S, turbo code supports the +following parameters: + +- :ref:`DTV_MODULATION <DTV-MODULATION>` + + +.. _isdbs-params: + +ISDB-S delivery system +====================== + +The following parameters are valid for ISDB-S: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_INVERSION <DTV-INVERSION>` + +- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` + +- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` + +- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>` + +- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>` diff --git a/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst new file mode 100644 index 000000000..8aad9ea81 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst @@ -0,0 +1,294 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend-property-terrestrial-systems: + +*********************************************** +Properties used on terrestrial delivery systems +*********************************************** + + +.. _dvbt-params: + +DVB-T delivery system +===================== + +The following parameters are valid for DVB-T: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_MODULATION <DTV-MODULATION>` + +- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>` + +- :ref:`DTV_INVERSION <DTV-INVERSION>` + +- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>` + +- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>` + +- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>` + +- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>` + +- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>` + +- :ref:`DTV_LNA <DTV-LNA>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. + + +.. _dvbt2-params: + +DVB-T2 delivery system +====================== + +DVB-T2 support is currently in the early stages of development, so +expect that this section may grow and become more detailed with time. + +The following parameters are valid for DVB-T2: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_MODULATION <DTV-MODULATION>` + +- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>` + +- :ref:`DTV_INVERSION <DTV-INVERSION>` + +- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>` + +- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>` + +- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>` + +- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>` + +- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>` + +- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>` + +- :ref:`DTV_LNA <DTV-LNA>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. + + +.. _isdbt: + +ISDB-T delivery system +====================== + +This ISDB-T/ISDB-Tsb API extension should reflect all information needed +to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some +very sophisticated devices won't need certain parameters to tune. + +The information given here should help application writers to know how +to handle ISDB-T and ISDB-Tsb hardware using the Linux Digital TV API. + +The details given here about ISDB-T and ISDB-Tsb are just enough to +basically show the dependencies between the needed parameter values, but +surely some information is left out. For more detailed information see +the following documents: + +ARIB STD-B31 - "Transmission System for Digital Terrestrial Television +Broadcasting" and + +ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television +Broadcasting". + +In order to understand the ISDB specific parameters, one has to have +some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has +to be known to the reader that an ISDB-T channel consists of 13 +segments, that it can have up to 3 layer sharing those segments, and +things like that. + +The following parameters are valid for ISDB-T: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>` + +- :ref:`DTV_INVERSION <DTV-INVERSION>` + +- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>` + +- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>` + +- :ref:`DTV_ISDBT_LAYER_ENABLED <DTV-ISDBT-LAYER-ENABLED>` + +- :ref:`DTV_ISDBT_PARTIAL_RECEPTION <DTV-ISDBT-PARTIAL-RECEPTION>` + +- :ref:`DTV_ISDBT_SOUND_BROADCASTING <DTV-ISDBT-SOUND-BROADCASTING>` + +- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID <DTV-ISDBT-SB-SUBCHANNEL-ID>` + +- :ref:`DTV_ISDBT_SB_SEGMENT_IDX <DTV-ISDBT-SB-SEGMENT-IDX>` + +- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT <DTV-ISDBT-SB-SEGMENT-COUNT>` + +- :ref:`DTV_ISDBT_LAYERA_FEC <DTV-ISDBT-LAYER-FEC>` + +- :ref:`DTV_ISDBT_LAYERA_MODULATION <DTV-ISDBT-LAYER-MODULATION>` + +- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>` + +- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>` + +- :ref:`DTV_ISDBT_LAYERB_FEC <DTV-ISDBT-LAYER-FEC>` + +- :ref:`DTV_ISDBT_LAYERB_MODULATION <DTV-ISDBT-LAYER-MODULATION>` + +- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>` + +- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>` + +- :ref:`DTV_ISDBT_LAYERC_FEC <DTV-ISDBT-LAYER-FEC>` + +- :ref:`DTV_ISDBT_LAYERC_MODULATION <DTV-ISDBT-LAYER-MODULATION>` + +- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>` + +- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. + + +.. _atsc-params: + +ATSC delivery system +==================== + +The following parameters are valid for ATSC: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_MODULATION <DTV-MODULATION>` + +- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. + + +.. _atscmh-params: + +ATSC-MH delivery system +======================= + +The following parameters are valid for ATSC-MH: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>` + +- :ref:`DTV_ATSCMH_FIC_VER <DTV-ATSCMH-FIC-VER>` + +- :ref:`DTV_ATSCMH_PARADE_ID <DTV-ATSCMH-PARADE-ID>` + +- :ref:`DTV_ATSCMH_NOG <DTV-ATSCMH-NOG>` + +- :ref:`DTV_ATSCMH_TNOG <DTV-ATSCMH-TNOG>` + +- :ref:`DTV_ATSCMH_SGN <DTV-ATSCMH-SGN>` + +- :ref:`DTV_ATSCMH_PRC <DTV-ATSCMH-PRC>` + +- :ref:`DTV_ATSCMH_RS_FRAME_MODE <DTV-ATSCMH-RS-FRAME-MODE>` + +- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE <DTV-ATSCMH-RS-FRAME-ENSEMBLE>` + +- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI <DTV-ATSCMH-RS-CODE-MODE-PRI>` + +- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC <DTV-ATSCMH-RS-CODE-MODE-SEC>` + +- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE <DTV-ATSCMH-SCCC-BLOCK-MODE>` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A <DTV-ATSCMH-SCCC-CODE-MODE-A>` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B <DTV-ATSCMH-SCCC-CODE-MODE-B>` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C <DTV-ATSCMH-SCCC-CODE-MODE-C>` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D <DTV-ATSCMH-SCCC-CODE-MODE-D>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. + + +.. _dtmb-params: + +DTMB delivery system +==================== + +The following parameters are valid for DTMB: + +- :ref:`DTV_API_VERSION <DTV-API-VERSION>` + +- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` + +- :ref:`DTV_TUNE <DTV-TUNE>` + +- :ref:`DTV_CLEAR <DTV-CLEAR>` + +- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` + +- :ref:`DTV_MODULATION <DTV-MODULATION>` + +- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>` + +- :ref:`DTV_INVERSION <DTV-INVERSION>` + +- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` + +- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>` + +- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>` + +- :ref:`DTV_INTERLEAVING <DTV-INTERLEAVING>` + +- :ref:`DTV_LNA <DTV-LNA>` + +In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>` +are also valid. diff --git a/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst b/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst new file mode 100644 index 000000000..223c1c56c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst @@ -0,0 +1,245 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend-stat-properties: + +****************************** +Frontend statistics indicators +****************************** + +The values are returned via ``dtv_property.stat``. If the property is +supported, ``dtv_property.stat.len`` is bigger than zero. + +For most delivery systems, ``dtv_property.stat.len`` will be 1 if the +stats is supported, and the properties will return a single value for +each parameter. + +It should be noted, however, that new OFDM delivery systems like ISDB +can use different modulation types for each group of carriers. On such +standards, up to 3 groups of statistics can be provided, and +``dtv_property.stat.len`` is updated to reflect the "global" metrics, +plus one metric per each carrier group (called "layer" on ISDB). + +So, in order to be consistent with other delivery systems, the first +value at :c:type:`dtv_property.stat.dtv_stats <dtv_stats>` array refers +to the global metric. The other elements of the array represent each +layer, starting from layer A(index 1), layer B (index 2) and so on. + +The number of filled elements are stored at ``dtv_property.stat.len``. + +Each element of the ``dtv_property.stat.dtv_stats`` array consists on +two elements: + +- ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of + the measure (dB measures) and ``uvalue`` is for unsigned values + (counters, relative scale) + +- ``scale`` - Scale for the value. It can be: + + - ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the + frontend, but it was not possible to collect it (could be a + transitory or permanent condition) + + - ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in + 1/1000 dB + + - ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0 + means 0% and 65535 means 100%. + + - ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts + the occurrence of an event, like bit error, block error, or lapsed + time. + + +.. _DTV-STAT-SIGNAL-STRENGTH: + +DTV_STAT_SIGNAL_STRENGTH +======================== + +Indicates the signal strength level at the analog part of the tuner or +of the demod. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power + measured in miliwatts. This value is generally negative. + +- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100% + measurement for power (actually, 0 to 65535). + + +.. _DTV-STAT-CNR: + +DTV_STAT_CNR +============ + +Indicates the Signal to Noise ratio for the main carrier. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units. + +- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100% + measurement for Signal/Noise (actually, 0 to 65535). + + +.. _DTV-STAT-PRE-ERROR-BIT-COUNT: + +DTV_STAT_PRE_ERROR_BIT_COUNT +============================ + +Measures the number of bit errors before the forward error correction +(FEC) on the inner coding block (before Viterbi, LDPC or other inner +code). + +This measure is taken during the same interval as +``DTV_STAT_PRE_TOTAL_BIT_COUNT``. + +In order to get the BER (Bit Error Rate) measurement, it should be +divided by +:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`. + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner + coding. + + +.. _DTV-STAT-PRE-TOTAL-BIT-COUNT: + +DTV_STAT_PRE_TOTAL_BIT_COUNT +============================ + +Measures the amount of bits received before the inner code block, during +the same period as +:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>` +measurement was taken. + +It should be noted that this measurement can be smaller than the total +amount of bits on the transport stream, as the frontend may need to +manually restart the measurement, losing some data between each +measurement interval. + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring + :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`. + + +.. _DTV-STAT-POST-ERROR-BIT-COUNT: + +DTV_STAT_POST_ERROR_BIT_COUNT +============================= + +Measures the number of bit errors after the forward error correction +(FEC) done by inner code block (after Viterbi, LDPC or other inner +code). + +This measure is taken during the same interval as +``DTV_STAT_POST_TOTAL_BIT_COUNT``. + +In order to get the BER (Bit Error Rate) measurement, it should be +divided by +:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`. + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner + coding. + + +.. _DTV-STAT-POST-TOTAL-BIT-COUNT: + +DTV_STAT_POST_TOTAL_BIT_COUNT +============================= + +Measures the amount of bits received after the inner coding, during the +same period as +:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>` +measurement was taken. + +It should be noted that this measurement can be smaller than the total +amount of bits on the transport stream, as the frontend may need to +manually restart the measurement, losing some data between each +measurement interval. + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring + :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`. + + +.. _DTV-STAT-ERROR-BLOCK-COUNT: + +DTV_STAT_ERROR_BLOCK_COUNT +========================== + +Measures the number of block errors after the outer forward error +correction coding (after Reed-Solomon or other outer code). + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer + coding. + + +.. _DTV-STAT-TOTAL-BLOCK-COUNT: + +DTV-STAT_TOTAL_BLOCK_COUNT +========================== + +Measures the total number of blocks received during the same period as +:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` +measurement was taken. + +It can be used to calculate the PER indicator, by dividing +:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` by +:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring + :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`. diff --git a/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions b/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions new file mode 100644 index 000000000..cecd4087d --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend.h.rst.exceptions @@ -0,0 +1,247 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _DVBFRONTEND_H_ + +# Group layer A-C symbols together +replace define DTV_ISDBT_LAYERA_FEC dtv-isdbt-layer-fec +replace define DTV_ISDBT_LAYERB_FEC dtv-isdbt-layer-fec +replace define DTV_ISDBT_LAYERC_FEC dtv-isdbt-layer-fec +replace define DTV_ISDBT_LAYERA_MODULATION dtv-isdbt-layer-modulation +replace define DTV_ISDBT_LAYERB_MODULATION dtv-isdbt-layer-modulation +replace define DTV_ISDBT_LAYERC_MODULATION dtv-isdbt-layer-modulation +replace define DTV_ISDBT_LAYERA_SEGMENT_COUNT dtv-isdbt-layer-segment-count +replace define DTV_ISDBT_LAYERB_SEGMENT_COUNT dtv-isdbt-layer-segment-count +replace define DTV_ISDBT_LAYERC_SEGMENT_COUNT dtv-isdbt-layer-segment-count +replace define DTV_ISDBT_LAYERA_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving +replace define DTV_ISDBT_LAYERB_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving +replace define DTV_ISDBT_LAYERC_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving + +# Ignore legacy defines +ignore define DTV_ISDBS_TS_ID_LEGACY +ignore define SYS_DVBC_ANNEX_AC +ignore define SYS_DMBTH + +# Ignore limits +ignore define DTV_MAX_COMMAND +ignore define MAX_DTV_STATS +ignore define DTV_IOCTL_MAX_MSGS + +# the same reference is used for both get and set ioctls +replace ioctl FE_SET_PROPERTY :ref:`FE_GET_PROPERTY` +replace ioctl FE_GET_PROPERTY :ref:`FE_GET_PROPERTY` + +# Typedefs that use the enum reference +replace typedef fe_sec_voltage_t :c:type:`fe_sec_voltage` + +# Replaces for flag constants +replace define FE_TUNE_MODE_ONESHOT :ref:`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 QAM_1024 +ignore symbol QAM_4096 +ignore symbol APSK_8_L +ignore symbol APSK_16_L +ignore symbol APSK_32_L +ignore symbol APSK_64 +ignore symbol APSK_64_L + +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 FEC_1_3 +ignore symbol FEC_1_4 +ignore symbol FEC_5_9 +ignore symbol FEC_7_9 +ignore symbol FEC_8_15 +ignore symbol FEC_11_15 +ignore symbol FEC_13_18 +ignore symbol FEC_9_20 +ignore symbol FEC_11_20 +ignore symbol FEC_23_36 +ignore symbol FEC_25_36 +ignore symbol FEC_13_45 +ignore symbol FEC_26_45 +ignore symbol FEC_28_45 +ignore symbol FEC_32_45 +ignore symbol FEC_77_90 +ignore symbol FEC_11_45 +ignore symbol FEC_4_15 +ignore symbol FEC_14_45 +ignore symbol FEC_7_15 + +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 GUARD_INTERVAL_1_64 + +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 ROLLOFF_15 +ignore symbol ROLLOFF_10 +ignore symbol ROLLOFF_5 + +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 SYS_DVBC2 + +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/userspace-api/media/dvb/frontend.rst b/Documentation/userspace-api/media/dvb/frontend.rst new file mode 100644 index 000000000..1df68730f --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_frontend: + +####################### +Digital TV Frontend API +####################### + +The Digital TV frontend API was designed to support three groups of delivery +systems: Terrestrial, cable and Satellite. Currently, the following +delivery systems are supported: + +- Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, + DTMB, CMMB + +- Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B) + +- Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS + +The Digital TV frontend controls several sub-devices including: + +- Tuner + +- Digital TV demodulator + +- Low noise amplifier (LNA) + +- Satellite Equipment Control (SEC) [#f1]_. + +The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``. +Data types and ioctl definitions can be accessed by including +``linux/dvb/frontend.h`` in your application. + +.. note:: + + Transmission via the internet (DVB-IP) and MMT (MPEG Media Transport) + is not yet handled by this API but a future extension is possible. + +.. [#f1] + + On Satellite systems, the API support for the Satellite Equipment + Control (SEC) allows to power control and to send/receive signals to + control the antenna subsystem, selecting the polarization and choosing + the Intermediate Frequency IF) of the Low Noise Block Converter Feed + Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC + (digital SEC) specification is available at + `Eutelsat <http://www.eutelsat.com/satellites/4_5_5.html>`__. + + +.. toctree:: + :maxdepth: 1 + + query-dvb-frontend-info + dvb-fe-read-status + dvbproperty + frontend_fcalls diff --git a/Documentation/userspace-api/media/dvb/frontend_f_close.rst b/Documentation/userspace-api/media/dvb/frontend_f_close.rst new file mode 100644 index 000000000..52c323a85 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_f_close.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _frontend_f_close: + +*************************** +Digital TV frontend close() +*************************** + +Name +==== + +fe-close - Close a frontend device + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + +.. c:function:: int close( int fd ) + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +=========== + +This system call closes a previously opened front-end device. After +closing a front-end device, its corresponding hardware might be powered +down automatically. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/frontend_f_open.rst b/Documentation/userspace-api/media/dvb/frontend_f_open.rst new file mode 100644 index 000000000..70e169b8f --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_f_open.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _frontend_f_open: + +*************************** +Digital TV frontend open() +*************************** + +Name +==== + +fe-open - Open a frontend device + +Synopsis +======== + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open( const char *device_name, int flags ) + +Arguments +========= + +``device_name`` + Device to be opened. + +``flags`` + Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``. + + Multiple opens are allowed with ``O_RDONLY``. In this mode, only + query and read ioctls are allowed. + + Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are + allowed. + + When the ``O_NONBLOCK`` flag is given, the system calls may return + ``EAGAIN`` error code when no data is available or when the device + driver is temporarily busy. + + Other flags have no effect. + +Description +=========== + +This system call opens a named frontend device +(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first +thing to do after a successful open is to find out the frontend type +with :ref:`FE_GET_INFO`. + +The device can be opened in read-only mode, which only allows monitoring +of device status and statistics, or read/write mode, which allows any +kind of use (e.g. performing tuning operations.) + +In a system with multiple front-ends, it is usually the case that +multiple devices cannot be open in read/write mode simultaneously. As +long as a front-end device is opened in read/write mode, other open() +calls in read/write mode will either fail or block, depending on whether +non-blocking or blocking mode was specified. A front-end device opened +in blocking mode can later be put into non-blocking mode (and vice +versa) using the F_SETFL command of the fcntl system call. This is a +standard system call, documented in the Linux manual page for fcntl. +When an open() call has succeeded, the device will be ready for use in +the specified mode. This implies that the corresponding hardware is +powered up, and that other front-ends may have been powered down to make +that possible. + +Return Value +============ + +On success :c:func:`open()` returns the new file descriptor. +On error, -1 is returned, and the ``errno`` variable is set appropriately. + +Possible error codes are: + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EPERM`` + - The caller has no permission to access the device. + + - - ``EBUSY`` + - The device driver is already in use. + + - - ``EMFILE`` + - The process already has the maximum number of files open. + + - - ``ENFILE`` + - The limit on the total number of files open on the system has been + reached. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/frontend_fcalls.rst b/Documentation/userspace-api/media/dvb/frontend_fcalls.rst new file mode 100644 index 000000000..1df27b6e8 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_fcalls.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend_fcalls: + +####################### +Frontend Function Calls +####################### + +.. toctree:: + :maxdepth: 1 + + frontend_f_open + frontend_f_close + fe-get-info + fe-read-status + fe-get-property + fe-diseqc-reset-overload + fe-diseqc-send-master-cmd + fe-diseqc-recv-slave-reply + fe-diseqc-send-burst + fe-set-tone + fe-set-voltage + fe-enable-high-lnb-voltage + fe-set-frontend-tune-mode diff --git a/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst b/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst new file mode 100644 index 000000000..535828c00 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend_legacy_types: + +Frontend Legacy Data Types +========================== + + +.. toctree:: + :maxdepth: 1 + + fe-type-t + fe-bandwidth-t + dvb-frontend-parameters + dvb-frontend-event + + +.. _frontend_legacy_fcalls: + +Frontend Legacy Function Calls +============================== + +Those functions are defined at DVB version 3. The support is kept in the +kernel due to compatibility issues only. Their usage is strongly not +recommended + + +.. toctree:: + :maxdepth: 1 + + fe-read-ber + fe-read-snr + fe-read-signal-strength + fe-read-uncorrected-blocks + fe-set-frontend + fe-get-frontend + fe-get-event + fe-dishnetwork-send-legacy-cmd diff --git a/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst b/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst new file mode 100644 index 000000000..09de723c2 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend_legacy_dvbv3_api: + +*********************************************** +Digital TV Frontend legacy API (a. k. a. DVBv3) +*********************************************** + +The usage of this API is deprecated, as it doesn't support all digital +TV standards, doesn't provide good statistics measurements and provides +incomplete information. This is kept only to support legacy +applications. + + +.. toctree:: + :maxdepth: 1 + + frontend_legacy_api diff --git a/Documentation/userspace-api/media/dvb/headers.rst b/Documentation/userspace-api/media/dvb/headers.rst new file mode 100644 index 000000000..6d69622bf --- /dev/null +++ b/Documentation/userspace-api/media/dvb/headers.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +*********************** +Digital TV uAPI symbols +*********************** + +.. contents:: Table of Contents + :depth: 2 + :local: + +Frontend +======== + +.. kernel-include:: include/uapi/linux/dvb/frontend.h + :generate-cross-refs: + :exception-file: frontend.h.rst.exceptions + :toc: + :warn-broken: + +Demux +===== + +.. kernel-include:: include/uapi/linux/dvb/dmx.h + :generate-cross-refs: + :exception-file: dmx.h.rst.exceptions + :toc: + :warn-broken: + +Conditional Access +================== + +.. kernel-include:: include/uapi/linux/dvb/ca.h + :generate-cross-refs: + :exception-file: ca.h.rst.exceptions + :toc: + :warn-broken: + +Network +======= + +.. kernel-include:: include/uapi/linux/dvb/net.h + :generate-cross-refs: + :exception-file: net.h.rst.exceptions + :toc: + :warn-broken: + diff --git a/Documentation/userspace-api/media/dvb/intro.rst b/Documentation/userspace-api/media/dvb/intro.rst new file mode 100644 index 000000000..854c2073e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/intro.rst @@ -0,0 +1,183 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_introduction: + +************ +Introduction +************ + + +.. _requisites: + +What you need to know +===================== + +The reader of this document is required to have some knowledge in the +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. + +Various Digital TV standards documents are available for download at: + +- 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++. + + +.. _history: + +History +======= + +The first API for Digital TV cards we used at Convergence in late 1999 was an +extension of the Video4Linux API which was primarily developed for frame +grabber cards. As such it was not really well suited to be used for Digital +TV cards and their new features like recording MPEG streams and filtering +several section and PES data streams at the same time. + +In early 2000, Convergence was approached by Nokia with a proposal for a new +standard Linux Digital TV 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. With the Linux driver for the Siemens/Hauppauge DVB PCI card, +Convergence provided a first implementation of the Linux Digital TV API. +Convergence was the maintainer of the Linux Digital TV 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: + +Overview +======== + + +.. _stb_components: + +.. kernel-figure:: dvbstb.svg + :alt: dvbstb.svg + :align: center + + Components of a Digital TV card/STB + +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 + 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 + 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 + 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. + + .. note:: + + Not every digital TV hardware provides conditional access hardware. + +Demultiplexer which filters the incoming Digital TV MPEG-TS 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. + +Audio and video decoder + The main targets of the demultiplexer are audio and video + decoders. After decoding, they pass on the uncompressed audio and + video to the computer screen or 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. + + + +.. _dvb_devices: + +Linux Digital TV Devices +======================== + +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 +the Digital TV demodulator. The demux device gives you control over the PES +and section filters of the hardware. If the hardware does not support +filtering, these filters can be implemented in software. Finally, the CA +device controls all the conditional access capabilities of the hardware. +It can depend on the individual security requirements of the platform, +if and how many of the CA functions are made available to the +application through this device. + +All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The +individual devices are called: + +- ``/dev/dvb/adapterN/audioM``, + +- ``/dev/dvb/adapterN/videoM``, + +- ``/dev/dvb/adapterN/frontendM``, + +- ``/dev/dvb/adapterN/netM``, + +- ``/dev/dvb/adapterN/demuxM``, + +- ``/dev/dvb/adapterN/dvrM``, + +- ``/dev/dvb/adapterN/caM``, + +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. + +More details about the data structures and function calls of all the +devices are described in the following chapters. + + +.. _include_files: + +API include files +================= + +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: + + +.. code-block:: c + + #include <linux/dvb/ca.h> + + #include <linux/dvb/dmx.h> + + #include <linux/dvb/frontend.h> + + #include <linux/dvb/net.h> + + +To enable applications to support different API version, an additional +include file ``linux/dvb/version.h`` exists, which defines the constant +``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst new file mode 100644 index 000000000..ffe832574 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _legacy_dvb_apis: + +*************************** +Digital TV Deprecated APIs +*************************** + +The APIs described here **should not** be used on new drivers or applications. + +The DVBv3 frontend API has issues with new delivery systems, including +DVB-S2, DVB-T2, ISDB, etc. + +.. attention:: + + The APIs described here doesn't necessarily reflect the current + code implementation, as this section of the document was written + for DVB version 1, while the code reflects DVB version 3 + implementation. + + +.. toctree:: + :maxdepth: 1 + + frontend_legacy_dvbv3_api + legacy_dvb_decoder_api diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst new file mode 100644 index 000000000..99ffda355 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst @@ -0,0 +1,1642 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.audio + +.. _dvb_audio: + +================ +DVB Audio Device +================ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB audio device controls the MPEG2 audio decoder of the DVB +hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data +types and ioctl definitions can be accessed by including +``linux/dvb/audio.h`` in your application. + +Please note that most DVB cards don’t have their own MPEG decoder, which +results in the omission of the audio and video device. + +These ioctls were also used by V4L2 to control MPEG decoders implemented +in V4L2. The use of these ioctls for that purpose has been made obsolete +and proper V4L2 ioctls or controls have been created to replace that +functionality. Use :ref:`V4L2 ioctls<audio>` for new drivers! + + +Audio Data Types +================ + +This section describes the structures, data types and defines used when +talking to the audio device. + + +----- + + +audio_stream_source_t +--------------------- + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_stream_source_t + +.. code-block:: c + + typedef enum { + AUDIO_SOURCE_DEMUX, + AUDIO_SOURCE_MEMORY + } audio_stream_source_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_SOURCE_DEMUX`` + + - :cspan:`1` Selects the demultiplexer (fed either by the frontend + or the DVR device) as the source of the video stream. + + - .. + + - ``AUDIO_SOURCE_MEMORY`` + + - Selects the stream from the application that comes through + the `write()`_ system call. + +Description +~~~~~~~~~~~ + +The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call +and can take the following values, depending on whether we are replaying +from an internal (demux) or external (user write) source. + +The data fed to the decoder is also controlled by the PID-filter. +Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``. + + +----- + + +audio_play_state_t +------------------ + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_play_state_t + +.. code-block:: c + + typedef enum { + AUDIO_STOPPED, + AUDIO_PLAYING, + AUDIO_PAUSED + } audio_play_state_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_STOPPED`` + + - Audio is stopped. + + - .. + + - ``AUDIO_PLAYING`` + + - Audio is currently playing. + + - .. + + - ``AUDIO_PAUSE`` + + - Audio is frozen. + +Description +~~~~~~~~~~~ + +This values can be returned by the `AUDIO_GET_STATUS`_ call +representing the state of audio playback. + + +----- + + +audio_channel_select_t +---------------------- + +Synopsis +~~~~~~~~ + +.. c:enum:: audio_channel_select_t + +.. code-block:: c + + typedef enum { + AUDIO_STEREO, + AUDIO_MONO_LEFT, + AUDIO_MONO_RIGHT, + AUDIO_MONO, + AUDIO_STEREO_SWAPPED + } audio_channel_select_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_STEREO`` + + - Stereo. + + - .. + + - ``AUDIO_MONO_LEFT`` + + - Mono, select left stereo channel as source. + + - .. + + - ``AUDIO_MONO_RIGHT`` + + - Mono, select right stereo channel as source. + + - .. + + - ``AUDIO_MONO`` + + - Mono source only. + + - .. + + - ``AUDIO_STEREO_SWAPPED`` + + - Stereo, swap L & R. + +Description +~~~~~~~~~~~ + +The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by +this value. + + +----- + + +audio_mixer_t +------------- + +Synopsis +~~~~~~~~ + +.. c:struct:: audio_mixer + +.. code-block:: c + + typedef struct audio_mixer { + unsigned int volume_left; + unsigned int volume_right; + } audio_mixer_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``unsigned int volume_left`` + + - Volume left channel. + Valid range: 0 ... 255 + + - .. + + - ``unsigned int volume_right`` + + - Volume right channel. + Valid range: 0 ... 255 + +Description +~~~~~~~~~~~ + +This structure is used by the `AUDIO_SET_MIXER`_ call to set the +audio volume. + + +----- + + +audio_status +------------ + +Synopsis +~~~~~~~~ + +.. c:struct:: audio_status + +.. code-block:: c + + typedef struct audio_status { + int AV_sync_state; + int mute_state; + audio_play_state_t play_state; + audio_stream_source_t stream_source; + audio_channel_select_t channel_select; + int bypass_mode; + audio_mixer_t mixer_state; + } audio_status_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`2` ``int AV_sync_state`` + + - :cspan:`1` Shows if A/V synchronization is ON or OFF. + + - .. + + - TRUE ( != 0 ) + + - AV-sync ON. + + - .. + + - FALSE ( == 0 ) + + - AV-sync OFF. + + - .. + + - :rspan:`2` ``int mute_state`` + + - :cspan:`1` Indicates if audio is muted or not. + + - .. + + - TRUE ( != 0 ) + + - mute audio + + - .. + + - FALSE ( == 0 ) + + - unmute audio + + - .. + + - `audio_play_state_t`_ ``play_state`` + + - Current playback state. + + - .. + + - `audio_stream_source_t`_ ``stream_source`` + + - Current source of the data. + + - .. + + - :rspan:`2` ``int bypass_mode`` + + - :cspan:`1` Is the decoding of the current Audio stream in + the DVB subsystem enabled or disabled. + + - .. + + - TRUE ( != 0 ) + + - Bypass disabled. + + - .. + + - FALSE ( == 0 ) + + - Bypass enabled. + + - .. + + - `audio_mixer_t`_ ``mixer_state`` + + - Current volume settings. + +Description +~~~~~~~~~~~ + +The `AUDIO_GET_STATUS`_ call returns this structure as information +about various states of the playback operation. + + +----- + + +audio encodings +--------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define AUDIO_CAP_DTS 1 + #define AUDIO_CAP_LPCM 2 + #define AUDIO_CAP_MP1 4 + #define AUDIO_CAP_MP2 8 + #define AUDIO_CAP_MP3 16 + #define AUDIO_CAP_AAC 32 + #define AUDIO_CAP_OGG 64 + #define AUDIO_CAP_SDDS 128 + #define AUDIO_CAP_AC3 256 + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``AUDIO_CAP_DTS`` + + - :cspan:`1` The hardware accepts DTS audio tracks. + + - .. + + - ``AUDIO_CAP_LPCM`` + + - The hardware accepts uncompressed audio with + Linear Pulse-Code Modulation (LPCM) + + - .. + + - ``AUDIO_CAP_MP1`` + + - The hardware accepts MPEG-1 Audio Layer 1. + + - .. + + - ``AUDIO_CAP_MP2`` + + - The hardware accepts MPEG-1 Audio Layer 2. + Also known as MUSICAM. + + - .. + + - ``AUDIO_CAP_MP3`` + + - The hardware accepts MPEG-1 Audio Layer III. + Commonly known as .mp3. + + - .. + + - ``AUDIO_CAP_AAC`` + + - The hardware accepts AAC (Advanced Audio Coding). + + - .. + + - ``AUDIO_CAP_OGG`` + + - The hardware accepts Vorbis audio tracks. + + - .. + + - ``AUDIO_CAP_SDDS`` + + - The hardware accepts Sony Dynamic Digital Sound (SDDS). + + - .. + + - ``AUDIO_CAP_AC3`` + + - The hardware accepts Dolby Digital ATSC A/52 audio. + Also known as AC-3. + +Description +~~~~~~~~~~~ + +A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the +following bits set according to the hardware's capabilities. + + +----- + + +Audio Function Calls +==================== + + +AUDIO_STOP +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_STOP + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_STOP) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - File descriptor returned by a previous call to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_STOP`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to stop playing the current +stream. + +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. + + +----- + + +AUDIO_PLAY +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_PLAY + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_PLAY) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - File descriptor returned by a previous call to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_PLAY`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to start playing an audio stream +from the selected source. + +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. + + +----- + + +AUDIO_PAUSE +----------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_PAUSE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_PAUSE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_PAUSE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call suspends the audio stream being played. Decoding and +playing are paused. It is then possible to restart again decoding and +playing process of the audio stream using `AUDIO_CONTINUE`_ command. + +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. + + +----- + + +AUDIO_CONTINUE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CONTINUE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CONTINUE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CONTINUE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl restarts the decoding and playing process previously paused +with `AUDIO_PAUSE`_ command. + +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. + + +----- + + +AUDIO_SELECT_SOURCE +------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SELECT_SOURCE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, + audio_stream_source_t source) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SELECT_SOURCE`` for this command. + + - .. + + - `audio_stream_source_t`_ ``source`` + + - Indicates the source that shall be used for the Audio stream. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call informs the audio device which source shall be used for +the input data. The possible sources are demux or memory. If +``AUDIO_SOURCE_MEMORY`` is selected, the data is fed to the Audio Device +through the write command. If ``AUDIO_SOURCE_DEMUX`` is selected, the data +is directly transferred from the onboard demux-device to the decoder. +Note: This only supports DVB-devices with one demux and one decoder so far. + +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. + + +----- + + +AUDIO_SET_MUTE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_MUTE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_MUTE, int state) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_SET_MUTE`` for this command. + + - .. + + - :rspan:`2` ``int state`` + + - :cspan:`1` Indicates if audio device shall mute or not. + + - .. + + - TRUE ( != 0 ) + + - mute audio + + - .. + + - FALSE ( == 0 ) + + - unmute audio + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To control a V4L2 decoder use the +V4L2 :ref:`VIDIOC_DECODER_CMD` with the +``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead. + +This ioctl call asks the audio device to mute the stream that is +currently being played. + +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. + + +----- + + +AUDIO_SET_AV_SYNC +----------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_AV_SYNC + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, int state) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_AV_SYNC`` for this command. + + - .. + + - :rspan:`2` ``int state`` + + - :cspan:`1` Tells the DVB subsystem if A/V synchronization + shall be ON or OFF. + + - .. + + - TRUE ( != 0 ) + + - AV-sync ON. + + - .. + + - FALSE ( == 0 ) + + - AV-sync OFF. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to turn ON or OFF A/V +synchronization. + +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. + + +----- + + +AUDIO_SET_BYPASS_MODE +--------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_BYPASS_MODE + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``AUDIO_SET_BYPASS_MODE`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Enables or disables the decoding of the current + Audio stream in the DVB subsystem. + - .. + + - TRUE ( != 0 ) + + - Disable bypass + + - .. + + - FALSE ( == 0 ) + + - Enable bypass + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to bypass the Audio decoder and +forward the stream without decoding. This mode shall be used if streams +that can’t be handled by the DVB system shall be decoded. Dolby +DigitalTM streams are automatically forwarded by the DVB subsystem if +the hardware can handle it. + +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. + + +----- + + +AUDIO_CHANNEL_SELECT +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CHANNEL_SELECT + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, + audio_channel_select_t) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CHANNEL_SELECT`` for this command. + + - .. + + - `audio_channel_select_t`_ ``ch`` + + - Select the output format of the audio (mono left/right, stereo). + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To control a V4L2 decoder use the +V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead. + +This ioctl call asks the Audio Device to select the requested channel if +possible. + +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. + + +----- + + +AUDIO_GET_STATUS +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_GET_STATUS + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_GET_STATUS, + struct audio_status *status) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals AUDIO_GET_STATUS for this command. + + - .. + + - ``struct`` `audio_status`_ ``*status`` + + - Returns the current state of Audio Device. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to return the current state of the +Audio Device. + +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. + + +----- + + +AUDIO_GET_CAPABILITIES +---------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_GET_CAPABILITIES + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, + unsigned int *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_GET_CAPABILITIES`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Returns a bit array of supported sound formats. + Bits are defined in `audio encodings`_. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to tell us about the decoding +capabilities of the audio hardware. + +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. + + +----- + + +AUDIO_CLEAR_BUFFER +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_CLEAR_BUFFER + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_CLEAR_BUFFER`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Audio Device to clear all software and hardware +buffers of the audio decoder device. + +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. + + +----- + + +AUDIO_SET_ID +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_ID + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_ID, int id) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_ID`` for this command. + + - .. + + - ``int id`` + + - Audio sub-stream id. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl selects which sub-stream is to be decoded if a program or +system stream is sent to the video device. + +If no audio stream type is set the id has to be in range [0xC0,0xDF] +for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] for LPCM. +See ITU-T H.222.0 | ISO/IEC 13818-1 for further description. + +If the stream type is set with `AUDIO_SET_STREAMTYPE`_, specifies the +id just the sub-stream id of the audio stream and only the first 5 bits +(& 0x1F) are recognized. + +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. + + +----- + + +AUDIO_SET_MIXER +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_MIXER + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_MIXER`` for this command. + + - .. + + - ``audio_mixer_t *mix`` + + - Mixer settings. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl lets you adjust the mixer settings of the audio decoder. + +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. + + +----- + + +AUDIO_SET_STREAMTYPE +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_SET_STREAMTYPE + +.. code-block:: c + + int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_SET_STREAMTYPE`` for this command. + + - .. + + - ``int type`` + + - Stream type. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl tells the driver which kind of audio stream to expect. This +is useful if the stream offers several audio sub-streams like LPCM and +AC3. + +Stream types defined in ITU-T H.222.0 | ISO/IEC 13818-1 are used. + + +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 + + - .. + + - ``EINVAL`` + + - Type is not a valid or supported stream type. + + +----- + + +AUDIO_BILINGUAL_CHANNEL_SELECT +------------------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT + +.. code-block:: c + + int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, + audio_channel_select_t) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``AUDIO_BILINGUAL_CHANNEL_SELECT`` for this command. + + - .. + + - ``audio_channel_select_t ch`` + + - Select the output format of the audio (mono left/right, stereo). + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl has been replaced by the V4L2 +``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control +for MPEG decoders controlled through V4L2. + +This ioctl call asks the Audio Device to select the requested channel +for bilingual streams if possible. + +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. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific audio device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named audio device (e.g. +``/dev/dvb/adapter0/audio0``) for subsequent use. When an open() call has +succeeded, the device will be ready for use. The significance of +blocking or non-blocking mode is described in the documentation for +functions where there is a difference. It does not affect the semantics +of the open() call itself. A device opened in blocking mode can later be +put into non-blocking mode (and vice versa) using the F_SETFL command +of the fcntl system call. This is a standard system call, documented in +the Linux manual page for fcntl. Only one user can open the Audio Device +in O_RDWR mode. All other attempts to open the device in this mode will +fail, and an error code will be returned. If the Audio Device is opened +in O_RDONLY mode, the only ioctl call that can be used is +`AUDIO_GET_STATUS`_. All other call will return with an error code. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - Device driver not loaded/available. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + +Description +~~~~~~~~~~~ + +This system call closes a previously opened audio device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - Fd is not a valid open file descriptor. + +----- + + +write() +------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + size_t write(int fd, const void *buf, size_t count) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``void *buf`` + + - Pointer to the buffer containing the PES data. + + - .. + + - ``size_t count`` + + - Size of buf. + +Description +~~~~~~~~~~~ + +This system call can only be used if ``AUDIO_SOURCE_MEMORY`` is selected +in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in +PES format. If ``O_NONBLOCK`` is not specified the function will block +until buffer space is available. The amount of data to be transferred is +implied by count. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - :cspan:`1` Mode ``AUDIO_SOURCE_MEMORY`` not selected. + + - .. + + - ``ENOMEM`` + + - Attempted to write more data than the internal buffer can hold. + + - .. + + - ``EBADF`` + + - Fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst new file mode 100644 index 000000000..f58985a6e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_decoder_api.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. _legacy_dvb_decoder_api: + +============================ +Legacy DVB MPEG Decoder APIs +============================ + +.. _legacy_dvb_decoder_notes: + +General Notes +============= + +This API has originally been designed for DVB only and is therefore limited to +the :ref:`legacy_dvb_decoder_formats` used in such digital TV-broadcastsystems. + +To circumvent this limitations the more versatile :ref:`V4L2 <v4l2spec>` API has +been designed. Which replaces this part of the DVB API. + +Nevertheless there have been projects build around this API. +To ensure compatibility this API is kept as it is. + +.. attention:: Do **not** use this API in new drivers! + + For audio and video use the :ref:`V4L2 <v4l2spec>` and ALSA APIs. + + Pipelines should be set up using the :ref:`Media Controller API<media_controller>`. + +Practically the decoders seem to be treated differently. The application typically +knows which decoder is in use or it is specially written for one decoder type. +Querying capabilities are rarely used because they are already known. + + +.. _legacy_dvb_decoder_formats: + +Data Formats +============ + +The API has been designed for DVB and compatible broadcastsystems. +Because of that fact the only supported data formats are ISO/IEC 13818-1 +compatible MPEG streams. The supported payloads may vary depending on the +used decoder. + +Timestamps are always MPEG PTS as defined in ITU T-REC-H.222.0 / +ISO/IEC 13818-1, if not otherwise noted. + +For storing recordings typically TS streams are used, in lesser extent PES. +Both variants are commonly accepted for playback, but it may be driver dependent. + + + + +Table of Contents +================= + +.. toctree:: + :maxdepth: 2 + + legacy_dvb_video + legacy_dvb_audio + legacy_dvb_osd diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst new file mode 100644 index 000000000..179b66a80 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_osd.rst @@ -0,0 +1,883 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.osd + +.. _dvb_osd: + +============== +DVB OSD Device +============== + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB OSD device controls the OnScreen-Display of the AV7110 based +DVB-cards with hardware MPEG2 decoder. It can be accessed through +``/dev/dvb/adapter?/osd0``. +Data types and ioctl definitions can be accessed by including +``linux/dvb/osd.h`` in your application. + +The OSD is not a frame-buffer like on many other cards. +It is a kind of canvas one can draw on. +The color-depth is limited depending on the memory size installed. +An appropriate palette of colors has to be set up. +The installed memory size can be identified with the `OSD_GET_CAPABILITY`_ +ioctl. + +OSD Data Types +============== + +OSD_Command +----------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + /* All functions return -2 on "not open" */ + OSD_Close = 1, + OSD_Open, + OSD_Show, + OSD_Hide, + OSD_Clear, + OSD_Fill, + OSD_SetColor, + OSD_SetPalette, + OSD_SetTrans, + OSD_SetPixel, + OSD_GetPixel, + OSD_SetRow, + OSD_SetBlock, + OSD_FillRow, + OSD_FillBlock, + OSD_Line, + OSD_Query, + OSD_Test, + OSD_Text, + OSD_SetWindow, + OSD_MoveWindow, + OSD_OpenRaw, + } OSD_Command; + +Commands +~~~~~~~~ + +.. note:: All functions return -2 on "not open" + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + - .. + + - Command + + - | Used variables of ``struct`` `osd_cmd_t`_. + | Usage{variable} if alternative use. + + - :cspan:`2` Description + + + + - .. + + - ``OSD_Close`` + + - - + + - | Disables OSD and releases the buffers. + | Returns 0 on success. + + - .. + + - ``OSD_Open`` + + - | x0,y0,x1,y1, + | BitPerPixel[2/4/8]{color&0x0F}, + | mix[0..15]{color&0xF0} + + - | Opens OSD with this size and bit depth + | Returns 0 on success, + | -1 on DRAM allocation error, + | -2 on "already open". + + - .. + + - ``OSD_Show`` + + - - + + - | Enables OSD mode. + | Returns 0 on success. + + - .. + + - ``OSD_Hide`` + + - - + + - | Disables OSD mode. + | Returns 0 on success. + + - .. + + - ``OSD_Clear`` + + - - + + - | Sets all pixel to color 0. + | Returns 0 on success. + + - .. + + - ``OSD_Fill`` + + - color + + - | Sets all pixel to color <color>. + | Returns 0 on success. + + - .. + + - ``OSD_SetColor`` + + - | color, + | R{x0},G{y0},B{x1}, + | opacity{y1} + + - | Set palette entry <num> to <r,g,b>, <mix> and <trans> apply + | R,G,B: 0..255 + | R=Red, G=Green, B=Blue + | opacity=0: pixel opacity 0% (only video pixel shows) + | opacity=1..254: pixel opacity as specified in header + | opacity=255: pixel opacity 100% (only OSD pixel shows) + | Returns 0 on success, -1 on error. + + - .. + + - ``OSD_SetPalette`` + + - | firstcolor{color}, + | lastcolor{x0},data + + - | Set a number of entries in the palette. + | Sets the entries "firstcolor" through "lastcolor" from the + array "data". + | Data has 4 byte for each color: + | R,G,B, and a opacity value: 0->transparent, 1..254->mix, + 255->pixel + + - .. + + - ``OSD_SetTrans`` + + - transparency{color} + + - | Sets transparency of mixed pixel (0..15). + | Returns 0 on success. + + - .. + + - ``OSD_SetPixel`` + + - x0,y0,color + + - | Sets pixel <x>,<y> to color number <color>. + | Returns 0 on success, -1 on error. + + - .. + + - ``OSD_GetPixel`` + + - x0,y0 + + - | Returns color number of pixel <x>,<y>, or -1. + | Command currently not supported by the AV7110! + + - .. + + - ``OSD_SetRow`` + + - x0,y0,x1,data + + - | Fills pixels x0,y through x1,y with the content of data[]. + | Returns 0 on success, -1 on clipping all pixel (no pixel + drawn). + + - .. + + - ``OSD_SetBlock`` + + - | x0,y0,x1,y1, + | increment{color}, + | data + + - | Fills pixels x0,y0 through x1,y1 with the content of data[]. + | Inc contains the width of one line in the data block, + | inc<=0 uses block width as line width. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_FillRow`` + + - x0,y0,x1,color + + - | Fills pixels x0,y through x1,y with the color <color>. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_FillBlock`` + + - x0,y0,x1,y1,color + + - | Fills pixels x0,y0 through x1,y1 with the color <color>. + | Returns 0 on success, -1 on clipping all pixel. + + - .. + + - ``OSD_Line`` + + - x0,y0,x1,y1,color + + - | Draw a line from x0,y0 to x1,y1 with the color <color>. + | Returns 0 on success. + + - .. + + - ``OSD_Query`` + + - | x0,y0,x1,y1, + | xasp{color}; yasp=11 + + - | Fills parameters with the picture dimensions and the pixel + aspect ratio. + | Returns 0 on success. + | Command currently not supported by the AV7110! + + - .. + + - ``OSD_Test`` + + - - + + - | Draws a test picture. + | For debugging purposes only. + | Returns 0 on success. + - .. + + - ``OSD_Text`` + + - x0,y0,size,color,text + + - Draws a text at position x0,y0 with the color <color>. + + - .. + + - ``OSD_SetWindow`` + + - x0 + + - Set window with number 0<x0<8 as current. + + - .. + + - ``OSD_MoveWindow`` + + - x0,y0 + + - Move current window to (x0, y0). + + - .. + + - ``OSD_OpenRaw`` + + - | x0,y0,x1,y1, + | `osd_raw_window_t`_ {color} + + - Open other types of OSD windows. + +Description +~~~~~~~~~~~ + +The ``OSD_Command`` data type is used with the `OSD_SEND_CMD`_ ioctl to +tell the driver which OSD_Command to execute. + + +----- + +osd_cmd_t +--------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct osd_cmd_s { + OSD_Command cmd; + int x0; + int y0; + int x1; + int y1; + int color; + void __user *data; + } osd_cmd_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_Command cmd`` + + - `OSD_Command`_ to be executed. + + - .. + + - ``int x0`` + + - First horizontal position. + + - .. + + - ``int y0`` + + - First vertical position. + + - .. + + - ``int x1`` + + - Second horizontal position. + + - .. + + - ``int y1`` + + - Second vertical position. + + - .. + + - ``int color`` + + - Number of the color in the palette. + + - .. + + - ``void __user *data`` + + - Command specific Data. + +Description +~~~~~~~~~~~ + +The ``osd_cmd_t`` data type is used with the `OSD_SEND_CMD`_ ioctl. +It contains the data for the OSD_Command and the `OSD_Command`_ itself. +The structure has to be passed to the driver and the components may be +modified by it. + + +----- + + +osd_raw_window_t +---------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + OSD_BITMAP1, + OSD_BITMAP2, + OSD_BITMAP4, + OSD_BITMAP8, + OSD_BITMAP1HR, + OSD_BITMAP2HR, + OSD_BITMAP4HR, + OSD_BITMAP8HR, + OSD_YCRCB422, + OSD_YCRCB444, + OSD_YCRCB444HR, + OSD_VIDEOTSIZE, + OSD_VIDEOHSIZE, + OSD_VIDEOQSIZE, + OSD_VIDEODSIZE, + OSD_VIDEOTHSIZE, + OSD_VIDEOTQSIZE, + OSD_VIDEOTDSIZE, + OSD_VIDEONSIZE, + OSD_CURSOR + } osd_raw_window_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_BITMAP1`` + + - :cspan:`1` 1 bit bitmap + + - .. + + - ``OSD_BITMAP2`` + + - 2 bit bitmap + + - .. + + - ``OSD_BITMAP4`` + + - 4 bit bitmap + + - .. + + - ``OSD_BITMAP8`` + + - 8 bit bitmap + + - .. + + - ``OSD_BITMAP1HR`` + + - 1 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP2HR`` + + - 2 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP4HR`` + + - 4 Bit bitmap half resolution + + - .. + + - ``OSD_BITMAP8HR`` + + - 8 Bit bitmap half resolution + + - .. + + - ``OSD_YCRCB422`` + + - 4:2:2 YCRCB Graphic Display + + - .. + + - ``OSD_YCRCB444`` + + - 4:4:4 YCRCB Graphic Display + + - .. + + - ``OSD_YCRCB444HR`` + + - 4:4:4 YCRCB graphic half resolution + + - .. + + - ``OSD_VIDEOTSIZE`` + + - True Size Normal MPEG Video Display + + - .. + + - ``OSD_VIDEOHSIZE`` + + - MPEG Video Display Half Resolution + + - .. + + - ``OSD_VIDEOQSIZE`` + + - MPEG Video Display Quarter Resolution + + - .. + + - ``OSD_VIDEODSIZE`` + + - MPEG Video Display Double Resolution + + - .. + + - ``OSD_VIDEOTHSIZE`` + + - True Size MPEG Video Display Half Resolution + + - .. + + - ``OSD_VIDEOTQSIZE`` + + - True Size MPEG Video Display Quarter Resolution + + - .. + + - ``OSD_VIDEOTDSIZE`` + + - True Size MPEG Video Display Double Resolution + + - .. + + - ``OSD_VIDEONSIZE`` + + - Full Size MPEG Video Display + + - .. + + - ``OSD_CURSOR`` + + - Cursor + +Description +~~~~~~~~~~~ + +The ``osd_raw_window_t`` data type is used with the `OSD_Command`_ +OSD_OpenRaw to tell the driver which type of OSD to open. + + +----- + + +osd_cap_t +--------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct osd_cap_s { + int cmd; + #define OSD_CAP_MEMSIZE 1 + long val; + } osd_cap_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int cmd`` + + - Capability to query. + + - .. + + - ``long val`` + + - Used to store the Data. + +Supported capabilities +~~~~~~~~~~~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``OSD_CAP_MEMSIZE`` + + - Memory size installed on the card. + +Description +~~~~~~~~~~~ + +This structure of data used with the `OSD_GET_CAPABILITY`_ call. + + +----- + + +OSD Function Calls +================== + +OSD_SEND_CMD +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: OSD_SEND_CMD + +.. code-block:: c + + int ioctl(int fd, int request = OSD_SEND_CMD, enum osd_cmd_t *cmd) + + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Pointer to the location of the structure `osd_cmd_t`_ for this + command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl sends the `OSD_Command`_ to the card. + +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 + + - .. + + - ``EINVAL`` + + - Command is out of range. + + +----- + + +OSD_GET_CAPABILITY +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: OSD_GET_CAPABILITY + +.. code-block:: c + + int ioctl(int fd, int request = OSD_GET_CAPABILITY, + struct osd_cap_t *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``OSD_GET_CAPABILITY`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Pointer to the location of the structure `osd_cap_t`_ for this + command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is used to get the capabilities of the OSD of the AV7110 based +DVB-decoder-card in use. + +.. note:: + The structure osd_cap_t has to be setup by the user and passed to the + driver. + +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 + + + - .. + + - ``EINVAL`` + + - Unsupported capability. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific OSD device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named OSD device (e.g. +``/dev/dvb/adapter?/osd0``) for subsequent use. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - Device driver not loaded/available. + + - .. + + - ``EINTERNAL`` + + - Internal error. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_ . + +Description +~~~~~~~~~~~ + +This system call closes a previously opened OSD device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst new file mode 100644 index 000000000..71d044605 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_video.rst @@ -0,0 +1,2430 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.video + +.. _dvb_video: + +================ +DVB Video Device +================ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB video device controls the MPEG2 video decoder of the DVB +hardware. It can be accessed through ``/dev/dvb/adapter0/video0``. Data +types and ioctl definitions can be accessed by including +``linux/dvb/video.h`` in your application. + +Note that the DVB video device only controls decoding of the MPEG video +stream, not its presentation on the TV or computer screen. On PCs this +is typically handled by an associated video4linux device, e.g. +``/dev/video``, which allows scaling and defining output windows. + +Most DVB cards don’t have their own MPEG decoder, which results in the +omission of the audio and video device as well as the video4linux +device. + +These ioctls were also used by V4L2 to control MPEG decoders implemented +in V4L2. The use of these ioctls for that purpose has been made obsolete +and proper V4L2 ioctls or controls have been created to replace that +functionality. Use :ref:`V4L2 ioctls<video>` for new drivers! + + +Video Data Types +================ + + + +video_format_t +-------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_FORMAT_4_3, + VIDEO_FORMAT_16_9, + VIDEO_FORMAT_221_1 + } video_format_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_FORMAT_4_3`` + + - Select 4:3 format. + + - .. + + - ``VIDEO_FORMAT_16_9`` + + - Select 16:9 format. + + - .. + + - ``VIDEO_FORMAT_221_1`` + + - Select 2.21:1 format. + +Description +~~~~~~~~~~~ + +The ``video_format_t`` data type +is used in the `VIDEO_SET_FORMAT`_ function to tell the driver which +aspect ratio the output hardware (e.g. TV) has. It is also used in the +data structures `video_status`_ returned by `VIDEO_GET_STATUS`_ +and `video_event`_ returned by `VIDEO_GET_EVENT`_ which report +about the display format of the current video stream. + + +----- + + +video_displayformat_t +--------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_PAN_SCAN, + VIDEO_LETTER_BOX, + VIDEO_CENTER_CUT_OUT + } video_displayformat_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_PAN_SCAN`` + + - Use pan and scan format. + + - .. + + - ``VIDEO_LETTER_BOX`` + + - Use letterbox format. + + - .. + + - ``VIDEO_CENTER_CUT_OUT`` + + - Use center cut out format. + +Description +~~~~~~~~~~~ + +In case the display format of the video stream and of the display +hardware differ the application has to specify how to handle the +cropping of the picture. This can be done using the +`VIDEO_SET_DISPLAY_FORMAT`_ call which accepts this enum as argument. + + +----- + + +video_size_t +------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef struct { + int w; + int h; + video_format_t aspect_ratio; + } video_size_t; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int w`` + + - Video width in pixels. + + - .. + + - ``int h`` + + - Video height in pixels. + + - .. + + - `video_format_t`_ ``aspect_ratio`` + + - Aspect ratio. + +Description +~~~~~~~~~~~ + +Used in the struct `video_event`_. It stores the resolution and +aspect ratio of the video. + + +----- + + +video_stream_source_t +--------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_SOURCE_DEMUX, + VIDEO_SOURCE_MEMORY + } video_stream_source_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_SOURCE_DEMUX`` + + - :cspan:`1` Select the demux as the main source. + + - .. + + - ``VIDEO_SOURCE_MEMORY`` + + - If this source is selected, the stream + comes from the user through the write + system call. + +Description +~~~~~~~~~~~ + +The video stream source is set through the `VIDEO_SELECT_SOURCE`_ call +and can take the following values, depending on whether we are replaying +from an internal (demuxer) or external (user write) source. +VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the +frontend or the DVR device) as the source of the video stream. If +VIDEO_SOURCE_MEMORY is selected the stream comes from the application +through the `write()`_ system call. + + +----- + + +video_play_state_t +------------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + typedef enum { + VIDEO_STOPPED, + VIDEO_PLAYING, + VIDEO_FREEZED + } video_play_state_t; + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_STOPPED`` + + - Video is stopped. + + - .. + + - ``VIDEO_PLAYING`` + + - Video is currently playing. + + - .. + + - ``VIDEO_FREEZED`` + + - Video is frozen. + +Description +~~~~~~~~~~~ + +This values can be returned by the `VIDEO_GET_STATUS`_ call +representing the state of video playback. + + +----- + + +struct video_command +-------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_command { + __u32 cmd; + __u32 flags; + union { + struct { + __u64 pts; + } stop; + + struct { + __s32 speed; + __u32 format; + } play; + + struct { + __u32 data[16]; + } raw; + }; + }; + + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``__u32 cmd`` + + - `Decoder command`_ + + - .. + + - ``__u32 flags`` + + - Flags for the `Decoder command`_. + + - .. + + - ``struct stop`` + + - ``__u64 pts`` + + - MPEG PTS + + - .. + + - :rspan:`5` ``struct play`` + + - :rspan:`4` ``__s32 speed`` + + - 0 or 1000 specifies normal speed, + + - .. + + - 1: specifies forward single stepping, + + - .. + + - -1: specifies backward single stepping, + + - .. + + - >1: playback at speed / 1000 of the normal speed + + - .. + + - <-1: reverse playback at ( -speed / 1000 ) of the normal speed. + + - .. + + - ``__u32 format`` + + - `Play input formats`_ + + - .. + + - ``__u32 data[16]`` + + - Reserved + +Description +~~~~~~~~~~~ + +The structure must be zeroed before use by the application. This ensures +it can be extended safely in the future. + + +----- + + +Predefined decoder commands and flags +------------------------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define VIDEO_CMD_PLAY (0) + #define VIDEO_CMD_STOP (1) + #define VIDEO_CMD_FREEZE (2) + #define VIDEO_CMD_CONTINUE (3) + + #define VIDEO_CMD_FREEZE_TO_BLACK (1 << 0) + + #define VIDEO_CMD_STOP_TO_BLACK (1 << 0) + #define VIDEO_CMD_STOP_IMMEDIATELY (1 << 1) + + #define VIDEO_PLAY_FMT_NONE (0) + #define VIDEO_PLAY_FMT_GOP (1) + + #define VIDEO_VSYNC_FIELD_UNKNOWN (0) + #define VIDEO_VSYNC_FIELD_ODD (1) + #define VIDEO_VSYNC_FIELD_EVEN (2) + #define VIDEO_VSYNC_FIELD_PROGRESSIVE (3) + +Constants +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`3` _`Decoder command` + + - ``VIDEO_CMD_PLAY`` + + - Start playback. + + - .. + + - ``VIDEO_CMD_STOP`` + + - Stop playback. + + - .. + + - ``VIDEO_CMD_FREEZE`` + + - Freeze playback. + + - .. + + - ``VIDEO_CMD_CONTINUE`` + + - Continue playback after freeze. + + - .. + + - Flags for ``VIDEO_CMD_FREEZE`` + + - ``VIDEO_CMD_FREEZE_TO_BLACK`` + + - Show black picture on freeze. + + - .. + + - :rspan:`1` Flags for ``VIDEO_CMD_STOP`` + + - ``VIDEO_CMD_STOP_TO_BLACK`` + + - Show black picture on stop. + + - .. + + - ``VIDEO_CMD_STOP_IMMEDIATELY`` + + - Stop immediately, without emptying buffers. + + - .. + + - :rspan:`1` _`Play input formats` + + - ``VIDEO_PLAY_FMT_NONE`` + + - The decoder has no special format requirements + + - .. + + - ``VIDEO_PLAY_FMT_GOP`` + + - The decoder requires full GOPs + + - .. + + - :rspan:`3` Field order + + - ``VIDEO_VSYNC_FIELD_UNKNOWN`` + + - FIELD_UNKNOWN can be used if the hardware does not know + whether the Vsync is for an odd, even or progressive + (i.e. non-interlaced) field. + + - .. + + - ``VIDEO_VSYNC_FIELD_ODD`` + + - Vsync is for an odd field. + + - .. + + - ``VIDEO_VSYNC_FIELD_EVEN`` + + - Vsync is for an even field. + + - .. + + - ``VIDEO_VSYNC_FIELD_PROGRESSIVE`` + + - progressive (i.e. non-interlaced) + + +----- + + +video_event +----------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_event { + __s32 type; + #define VIDEO_EVENT_SIZE_CHANGED 1 + #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 + #define VIDEO_EVENT_DECODER_STOPPED 3 + #define VIDEO_EVENT_VSYNC 4 + long timestamp; + union { + video_size_t size; + unsigned int frame_rate; + unsigned char vsync_field; + } u; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`4` ``__s32 type`` + + - :cspan:`1` Event type. + + - .. + + - ``VIDEO_EVENT_SIZE_CHANGED`` + + - Size changed. + + - .. + + - ``VIDEO_EVENT_FRAME_RATE_CHANGED`` + + - Framerate changed. + + - .. + + - ``VIDEO_EVENT_DECODER_STOPPED`` + + - Decoder stopped. + + - .. + + - ``VIDEO_EVENT_VSYNC`` + + - Vsync occurred. + + - .. + + - ``long timestamp`` + + - :cspan:`1` MPEG PTS at occurrence. + + - .. + + - :rspan:`2` ``union u`` + + - `video_size_t`_ size + + - Resolution and aspect ratio of the video. + + - .. + + - ``unsigned int frame_rate`` + + - in frames per 1000sec + + - .. + + - ``unsigned char vsync_field`` + + - | unknown / odd / even / progressive + | See: `Predefined decoder commands and flags`_ + +Description +~~~~~~~~~~~ + +This is the structure of a video event as it is returned by the +`VIDEO_GET_EVENT`_ call. See there for more details. + + +----- + + +video_status +------------ + +Synopsis +~~~~~~~~ + +The `VIDEO_GET_STATUS`_ call returns the following structure informing +about various states of the playback operation. + +.. code-block:: c + + struct video_status { + int video_blank; + video_play_state_t play_state; + video_stream_source_t stream_source; + video_format_t video_format; + video_displayformat_t display_format; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - :rspan:`2` ``int video_blank`` + + - :cspan:`1` Show blank video on freeze? + + - .. + + - TRUE ( != 0 ) + + - Blank screen when freeze. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + + - .. + + - `video_play_state_t`_ ``play_state`` + + - Current state of playback. + + - .. + + - `video_stream_source_t`_ ``stream_source`` + + - Current source (demux/memory). + + - .. + + - `video_format_t`_ ``video_format`` + + - Current aspect ratio of stream. + + - .. + + - `video_displayformat_t`_ ``display_format`` + + - Applied cropping mode. + +Description +~~~~~~~~~~~ + +If ``video_blank`` is set ``TRUE`` video will be blanked out if the +channel is changed or if playback is stopped. Otherwise, the last picture +will be displayed. ``play_state`` indicates if the video is currently +frozen, stopped, or being played back. The ``stream_source`` corresponds +to the selected source for the video stream. It can come either from the +demultiplexer or from memory. The ``video_format`` indicates the aspect +ratio (one of 4:3 or 16:9) of the currently played video stream. +Finally, ``display_format`` corresponds to the applied cropping mode in +case the source video format is not the same as the format of the output +device. + + +----- + + +video_still_picture +------------------- + +Synopsis +~~~~~~~~ + +.. code-block:: c + + struct video_still_picture { + char *iFrame; + int32_t size; + }; + +Variables +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``char *iFrame`` + + - Pointer to a single iframe in memory. + + - .. + + - ``int32_t size`` + + - Size of the iframe. + + +Description +~~~~~~~~~~~ + +An I-frame displayed via the `VIDEO_STILLPICTURE`_ call is passed on +within this structure. + + +----- + + +video capabilities +------------------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #define VIDEO_CAP_MPEG1 1 + #define VIDEO_CAP_MPEG2 2 + #define VIDEO_CAP_SYS 4 + #define VIDEO_CAP_PROG 8 + +Constants +~~~~~~~~~ +Bit definitions for capabilities: + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``VIDEO_CAP_MPEG1`` + + - :cspan:`1` The hardware can decode MPEG1. + + - .. + + - ``VIDEO_CAP_MPEG2`` + + - The hardware can decode MPEG2. + + - .. + + - ``VIDEO_CAP_SYS`` + + - The video device accepts system stream. + + You still have to open the video and the audio device + but only send the stream to the video device. + + - .. + + - ``VIDEO_CAP_PROG`` + + - The video device accepts program stream. + + You still have to open the video and the audio device + but only send the stream to the video device. + +Description +~~~~~~~~~~~ + +A call to `VIDEO_GET_CAPABILITIES`_ returns an unsigned integer with the +following bits set according to the hardware's capabilities. + + +----- + + +Video Function Calls +==================== + + +VIDEO_STOP +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_STOP + +.. code-block:: c + + int ioctl(fd, VIDEO_STOP, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``VIDEO_STOP`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Indicates how the screen shall be handled. + + - .. + + - TRUE ( != 0 ) + + - Blank screen when stop. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call asks the Video Device to stop playing the current +stream. Depending on the input parameter, the screen can be blanked out +or displaying the last decoded frame. + +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. + + +----- + + +VIDEO_PLAY +---------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_PLAY + +.. code-block:: c + + int ioctl(fd, VIDEO_PLAY) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_PLAY`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call asks the Video Device to start playing a video stream +from the selected source. + +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. + + +----- + + +VIDEO_FREEZE +------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_FREEZE + +.. code-block:: c + + int ioctl(fd, VIDEO_FREEZE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_FREEZE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call suspends the live video stream being played, if +VIDEO_SOURCE_DEMUX is selected. Decoding and playing are frozen. +It is then possible to restart the decoding and playing process of the +video stream using the `VIDEO_CONTINUE`_ command. +If VIDEO_SOURCE_MEMORY is selected in the ioctl call +`VIDEO_SELECT_SOURCE`_, the Digital TV subsystem will not decode any more +data until the ioctl call `VIDEO_CONTINUE`_ or `VIDEO_PLAY`_ is performed. + +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. + + +----- + + +VIDEO_CONTINUE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_CONTINUE + +.. code-block:: c + + int ioctl(fd, VIDEO_CONTINUE) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_CONTINUE`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. To control a V4L2 decoder use +the V4L2 :ref:`VIDIOC_DECODER_CMD` instead. + +This ioctl call restarts decoding and playing processes of the video +stream which was played before a call to `VIDEO_FREEZE`_ was made. + +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. + + +----- + + +VIDEO_SELECT_SOURCE +------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SELECT_SOURCE + +.. code-block:: c + + int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SELECT_SOURCE`` for this command. + + - .. + + - `video_stream_source_t`_ ``source`` + + - Indicates which source shall be used for the Video stream. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for Digital TV devices only. This ioctl was also supported +by the V4L2 ivtv driver, but that has been replaced by the ivtv-specific +``IVTV_IOC_PASSTHROUGH_MODE`` ioctl. + +This ioctl call informs the video device which source shall be used for +the input data. The possible sources are demux or memory. If memory is +selected, the data is fed to the video device through the write command +using the struct `video_stream_source_t`_. If demux is selected, the data +is directly transferred from the onboard demux-device to the decoder. + +The data fed to the decoder is also controlled by the PID-filter. +Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``. + + +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. + + +----- + + +VIDEO_SET_BLANK +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_BLANK + +.. code-block:: c + + int ioctl(fd, VIDEO_SET_BLANK, int mode) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - :cspan:`1` Equals ``VIDEO_SET_BLANK`` for this command. + + - .. + + - :rspan:`2` ``int mode`` + + - :cspan:`1` Indicates if the screen shall be blanked. + + - .. + + - TRUE ( != 0 ) + + - Blank screen when stop. + + - .. + + - FALSE ( == 0 ) + + - Show last decoded frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to blank out the picture. + +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. + + +----- + + +VIDEO_GET_STATUS +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_STATUS + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_STATUS, + struct video_status *status) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_STATUS`` for this command. + + - .. + + - ``struct`` `video_status`_ ``*status`` + + - Returns the current status of the Video Device. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to return the current status of +the device. + +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. + + +----- + + +VIDEO_GET_EVENT +--------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_EVENT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_EVENT, + struct video_event *ev) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_EVENT`` for this command. + + - .. + + - ``struct`` `video_event`_ ``*ev`` + + - Points to the location where the event, if any, is to be stored. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl is for DVB devices only. To get events from a V4L2 decoder +use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead. + +This ioctl call returns an event of type `video_event`_ if available. A +certain number of the latest events will be cued and returned in order of +occurrence. Older events may be discarded if not fetched in time. 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. The standard Linux poll() +and/or select() system calls can be used with the device file descriptor +to watch for new events. For select(), the file descriptor should be +included in the exceptfds argument, and for poll(), POLLPRI should be +specified as the wake-up condition. Read-only permissions are sufficient +for this ioctl call. + +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 + + - .. + + - ``EWOULDBLOCK`` + + - :cspan:`1` There is no event pending, and the device is in + non-blocking mode. + + - .. + + - ``EOVERFLOW`` + + - Overflow in event queue - one or more events were lost. + + +----- + + +VIDEO_SET_DISPLAY_FORMAT +------------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_DISPLAY_FORMAT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, + video_display_format_t format) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_DISPLAY_FORMAT`` for this command. + + - .. + + - `video_displayformat_t`_ ``format`` + + - Selects the video format to be used. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to select the video format to be +applied by the MPEG chip on the video. + +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. + + +----- + + +VIDEO_STILLPICTURE +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_STILLPICTURE + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_STILLPICTURE, + struct video_still_picture *sp) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_STILLPICTURE`` for this command. + + - .. + + - ``struct`` `video_still_picture`_ ``*sp`` + + - Pointer to the location where the struct with the I-frame + and size is stored. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to display a still picture +(I-frame). The input data shall be the section of an elementary video +stream containing an I-frame. Typically this section is extracted from a +TS or PES recording. Resolution and codec (see `video capabilities`_) must +be supported by the device. If the pointer is NULL, then the current +displayed still picture is blanked. + +e.g. The AV7110 supports MPEG1 and MPEG2 with the common PAL-SD +resolutions. + +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. + + +----- + + +VIDEO_FAST_FORWARD +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_FAST_FORWARD + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_FAST_FORWARD`` for this command. + + - .. + + - ``int nFrames`` + + - The number of frames to skip. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the Video Device to skip decoding of N number of +I-frames. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is +selected. + +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 + + - .. + + - ``EPERM`` + + - Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + +----- + + +VIDEO_SLOWMOTION +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SLOWMOTION + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SLOWMOTION`` for this command. + + - .. + + - ``int nFrames`` + + - The number of times to repeat each frame. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the video device to repeat decoding frames N number +of times. This call can only be used if ``VIDEO_SOURCE_MEMORY`` is +selected. + +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 + + - .. + + - ``EPERM`` + + - Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + +----- + + +VIDEO_GET_CAPABILITIES +---------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_CAPABILITIES + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_CAPABILITIES`` for this command. + + - .. + + - ``unsigned int *cap`` + + - Pointer to a location where to store the capability information. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call asks the video device about its decoding capabilities. +On success it returns an integer which has bits set according to the +defines in `video capabilities`_. + +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. + + +----- + + +VIDEO_CLEAR_BUFFER +------------------ + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_CLEAR_BUFFER + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_CLEAR_BUFFER) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_CLEAR_BUFFER`` for this command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl call clears all video buffers in the driver and in the +decoder hardware. + +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. + + +----- + + +VIDEO_SET_STREAMTYPE +-------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_STREAMTYPE + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_STREAMTYPE`` for this command. + + - .. + + - ``int type`` + + - Stream type. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl tells the driver which kind of stream to expect being written +to it. +Intelligent decoder might also not support or ignore (like the AV7110) +this call and determine the stream type themselves. + +Currently used stream types: + +.. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + - .. + + - Codec + + - Stream type + + - .. + + - MPEG2 + + - 0 + + - .. + + - MPEG4 h.264 + + - 1 + + - .. + + - VC1 + + - 3 + + - .. + + - MPEG4 Part2 + + - 4 + + - .. + + - VC1 SM + + - 5 + + - .. + + - MPEG1 + + - 6 + + - .. + + - HEVC h.265 + + - | 7 + | DREAMBOX: 22 + + - .. + + - AVS + + - 16 + + - .. + + - AVS2 + + - 40 + +Not every decoder supports all stream types. + +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. + + +----- + + +VIDEO_SET_FORMAT +---------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_SET_FORMAT + +.. code-block:: c + + int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_SET_FORMAT`` for this command. + + - .. + + - `video_format_t`_ ``format`` + + - Video format of TV as defined in section `video_format_t`_. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl sets the screen format (aspect ratio) of the connected output +device (TV) so that the output of the decoder can be adjusted +accordingly. + +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. + + +----- + + +VIDEO_GET_SIZE +-------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_SIZE + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call, + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_SIZE`` for this command. + + - .. + + - `video_size_t`_ ``*size`` + + - Returns the size and aspect ratio. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +This ioctl returns the size and aspect ratio. + +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. + + +----- + + +VIDEO_GET_PTS +------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_PTS + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_PTS`` for this command. + + - .. + + - ``__u64 *pts`` + + - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / + ISO/IEC 13818-1. + + The PTS should belong to the currently played frame if possible, + but may also be a value close to it like the PTS of the last + decoded frame or the last PTS extracted by the PES parser. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +``V4L2_CID_MPEG_VIDEO_DEC_PTS`` control. + +This ioctl call asks the Video Device to return the current PTS +timestamp. + +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. + + +----- + + +VIDEO_GET_FRAME_COUNT +--------------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_GET_FRAME_COUNT + +.. code-block:: c + + int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_GET_FRAME_COUNT`` for this command. + + - .. + + - ``__u64 *pts`` + + - Returns the number of frames displayed since the decoder was + started. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +``V4L2_CID_MPEG_VIDEO_DEC_FRAME`` control. + +This ioctl call asks the Video Device to return the number of displayed +frames since the decoder was started. + +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. + + +----- + + +VIDEO_COMMAND +------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_COMMAND + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_COMMAND, + struct video_command *cmd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_COMMAND`` for this command. + + - .. + + - `struct video_command`_ ``*cmd`` + + - Commands the decoder. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +:ref:`VIDIOC_DECODER_CMD` ioctl. + +This ioctl commands the decoder. The `struct video_command`_ is a +subset of the ``v4l2_decoder_cmd`` struct, so refer to the +:ref:`VIDIOC_DECODER_CMD` documentation for +more information. + +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. + + +----- + + +VIDEO_TRY_COMMAND +----------------- + +Synopsis +~~~~~~~~ + +.. c:macro:: VIDEO_TRY_COMMAND + +.. code-block:: c + + int ioctl(int fd, int request = VIDEO_TRY_COMMAND, + struct video_command *cmd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``int request`` + + - Equals ``VIDEO_TRY_COMMAND`` for this command. + + - .. + + - `struct video_command`_ ``*cmd`` + + - Try a decoder command. + +Description +~~~~~~~~~~~ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +For V4L2 decoders this ioctl has been replaced by the +:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl. + +This ioctl tries a decoder command. The `struct video_command`_ is a +subset of the ``v4l2_decoder_cmd`` struct, so refer to the +:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation +for more information. + +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. + + +----- + + +open() +------ + +Synopsis +~~~~~~~~ + +.. code-block:: c + + #include <fcntl.h> + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``const char *deviceName`` + + - Name of specific video device. + + - .. + + - :rspan:`3` ``int flags`` + + - :cspan:`1` A bit-wise OR of the following flags: + + - .. + + - ``O_RDONLY`` + + - read-only access + + - .. + + - ``O_RDWR`` + + - read/write access + + - .. + + - ``O_NONBLOCK`` + - | Open in non-blocking mode + | (blocking mode is the default) + +Description +~~~~~~~~~~~ + +This system call opens a named video device (e.g. +/dev/dvb/adapter?/video?) for subsequent use. + +When an open() call has succeeded, the device will be ready for use. The +significance of blocking or non-blocking mode is described in the +documentation for functions where there is a difference. It does not +affect the semantics of the open() call itself. A device opened in +blocking mode can later be put into non-blocking mode (and vice versa) +using the F_SETFL command of the fcntl system call. This is a standard +system call, documented in the Linux manual page for fcntl. Only one +user can open the Video Device in O_RDWR mode. All other attempts to +open the device in this mode will fail, and an error-code will be +returned. If the Video Device is opened in O_RDONLY mode, the only +ioctl call that can be used is `VIDEO_GET_STATUS`_. All other call will +return an error code. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``ENODEV`` + + - :cspan:`1` Device driver not loaded/available. + + - .. + + - ``EINTERNAL`` + + - Internal error. + + - .. + + - ``EBUSY`` + + - Device or resource busy. + + - .. + + - ``EINVAL`` + + - Invalid argument. + + +----- + + +close() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: int close(int fd) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + +Description +~~~~~~~~~~~ + +This system call closes a previously opened video device. + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. + + +----- + + +write() +------- + +Synopsis +~~~~~~~~ + +.. c:function:: size_t write(int fd, const void *buf, size_t count) + +Arguments +~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``int fd`` + + - :cspan:`1` File descriptor returned by a previous call + to `open()`_. + + - .. + + - ``void *buf`` + + - Pointer to the buffer containing the PES data. + + - .. + + - ``size_t count`` + + - Size of buf. + +Description +~~~~~~~~~~~ + +This system call can only be used if VIDEO_SOURCE_MEMORY is selected +in the ioctl call `VIDEO_SELECT_SOURCE`_. The data provided shall be in +PES format, unless the capability allows other formats. TS is the +most common format for storing DVB-data, it is usually supported too. +If O_NONBLOCK is not specified the function will block until buffer space +is available. The amount of data to be transferred is implied by count. + +.. note:: See: :ref:`DVB Data Formats <legacy_dvb_decoder_formats>` + +Return Value +~~~~~~~~~~~~ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. + + - ``EPERM`` + + - :cspan:`1` Mode ``VIDEO_SOURCE_MEMORY`` not selected. + + - .. + + - ``ENOMEM`` + + - Attempted to write more data than the internal buffer can hold. + + - .. + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/dvb/net-add-if.rst b/Documentation/userspace-api/media/dvb/net-add-if.rst new file mode 100644 index 000000000..022b4c626 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net-add-if.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net + +.. _NET_ADD_IF: + +**************** +ioctl NET_ADD_IF +**************** + +Name +==== + +NET_ADD_IF - Creates a new network interface for a given Packet ID. + +Synopsis +======== + +.. c:macro:: NET_ADD_IF + +``int ioctl(int fd, NET_ADD_IF, struct dvb_net_if *net_if)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``net_if`` + pointer to struct :c:type:`dvb_net_if` + +Description +=========== + +The NET_ADD_IF ioctl system call selects the Packet ID (PID) that +contains a TCP/IP traffic, the type of encapsulation to be used (MPE or +ULE) and the interface number for the new interface to be created. When +the system call successfully returns, a new virtual network interface is +created. + +The struct :c:type:`dvb_net_if`::ifnum field will be +filled with the number of the created interface. + +Return Value +============ + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/net-get-if.rst b/Documentation/userspace-api/media/dvb/net-get-if.rst new file mode 100644 index 000000000..e99696c9d --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net-get-if.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net + +.. _NET_GET_IF: + +**************** +ioctl NET_GET_IF +**************** + +Name +==== + +NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF <net>`. + +Synopsis +======== + +.. c:macro:: NET_GET_IF + +``int ioctl(int fd, NET_GET_IF, struct dvb_net_if *net_if)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``net_if`` + pointer to struct :c:type:`dvb_net_if` + +Description +=========== + +The NET_GET_IF ioctl uses the interface number given by the struct +:c:type:`dvb_net_if`::ifnum field and fills the content of +struct :c:type:`dvb_net_if` with the packet ID and +encapsulation type used on such interface. If the interface was not +created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill +the ``errno`` with ``EINVAL`` error code. + +Return Value +============ + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/net-remove-if.rst b/Documentation/userspace-api/media/dvb/net-remove-if.rst new file mode 100644 index 000000000..ac88691c0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net-remove-if.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net + +.. _NET_REMOVE_IF: + +******************* +ioctl NET_REMOVE_IF +******************* + +Name +==== + +NET_REMOVE_IF - Removes a network interface. + +Synopsis +======== + +.. c:macro:: NET_REMOVE_IF + +``int ioctl(int fd, NET_REMOVE_IF, int ifnum)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``net_if`` + number of the interface to be removed + +Description +=========== + +The NET_REMOVE_IF ioctl deletes an interface previously created via +:ref:`NET_ADD_IF <net>`. + +Return Value +============ + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. diff --git a/Documentation/userspace-api/media/dvb/net-types.rst b/Documentation/userspace-api/media/dvb/net-types.rst new file mode 100644 index 000000000..075264bc0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net-types.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _net_types: + +************** +Net Data Types +************** + +.. kernel-doc:: include/uapi/linux/dvb/net.h diff --git a/Documentation/userspace-api/media/dvb/net.h.rst.exceptions b/Documentation/userspace-api/media/dvb/net.h.rst.exceptions new file mode 100644 index 000000000..5159aa4bb --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net.h.rst.exceptions @@ -0,0 +1,13 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _DVBNET_H_ + +# Ignore old ioctls/structs +ignore ioctl __NET_ADD_IF_OLD +ignore ioctl __NET_GET_IF_OLD +ignore struct __dvb_net_if_old + +# Macros used at struct dvb_net_if +replace define DVB_NET_FEEDTYPE_MPE :c:type:`dvb_net_if` +replace define DVB_NET_FEEDTYPE_ULE :c:type:`dvb_net_if` diff --git a/Documentation/userspace-api/media/dvb/net.rst b/Documentation/userspace-api/media/dvb/net.rst new file mode 100644 index 000000000..020a023d3 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _net: + +###################### +Digital TV Network API +###################### + +The Digital TV net device controls the mapping of data packages that are part +of a transport stream to be mapped into a virtual network interface, +visible through the standard Linux network protocol stack. + +Currently, two encapsulations are supported: + +- `Multi Protocol Encapsulation (MPE) <http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation>`__ + +- `Ultra Lightweight Encapsulation (ULE) <http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation>`__ + +In order to create the Linux virtual network interfaces, an application +needs to tell to the Kernel what are the PIDs and the encapsulation +types that are present on the transport stream. This is done through +``/dev/dvb/adapter?/net?`` device node. The data will be available via +virtual ``dvb?_?`` network interfaces, and will be controlled/routed via +the standard ip tools (like ip, route, netstat, ifconfig, etc). + +Data types and ioctl definitions are defined via ``linux/dvb/net.h`` +header. + + +.. _net_fcalls: + +Digital TV net Function Calls +############################# + +.. toctree:: + :maxdepth: 1 + + net-types + net-add-if + net-remove-if + net-get-if diff --git a/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst b/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst new file mode 100644 index 000000000..f099b4935 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _query-dvb-frontend-info: + +***************************** +Querying frontend information +***************************** + +Usually, the first thing to do when the frontend is opened is to check +the frontend capabilities. This is done using +:ref:`FE_GET_INFO`. This ioctl will enumerate the +Digital TV API version and other characteristics about the frontend, and can +be opened either in read only or read/write mode. |
