Commit 883dfe8a authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

media: dvb uAPI docs: minor editorial changes

Do minor editorial changes to improve documentation readability:

- mark literals as such;
- add table markups to hint sizes;
- define what PES means;
- instead of hardcoding devnode numbers to zero (like adapter0/) use a
  question mark, to indicate that multiple devnodes may exist;
- add cross-references where useful.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 8e319510
......@@ -28,20 +28,20 @@ Arguments
``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
- - ``O_RDONLY``
- read-only access
-
- O_RDWR
- - ``O_RDWR``
- read/write access
-
- O_NONBLOCK
- - ``O_NONBLOCK``
- open in non-blocking mode
(blocking mode is the default)
......@@ -52,15 +52,16 @@ 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
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
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.
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
......
......@@ -33,8 +33,8 @@ Description
-----------
This ioctl call allows to add multiple PIDs to a transport stream filter
previously set up with DMX_SET_PES_FILTER and output equal to
DMX_OUT_TSDEMUX_TAP.
previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to
:c:type:`DMX_OUT_TSDEMUX_TAP <dmx_output>`.
Return Value
......
......@@ -23,13 +23,14 @@ Arguments
---------
``fd``
File descriptor returned by a previous call to :c:func:`open() <dvb-ca-open>`.
File descriptor returned by a previous call to
:c:func:`open() <dvb-dmx-open>`.
Description
-----------
This system call deactivates and deallocates a filter that was
previously allocated via the open() call.
previously allocated via the :c:func:`open() <dvb-dmx-open>` call.
Return Value
......
......@@ -27,20 +27,23 @@ Arguments
``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
- ``O_RDONLY``
- read-only access
-
- O_RDWR
- ``O_RDWR``
- read/write access
-
- O_NONBLOCK
- ``O_NONBLOCK``
- open in non-blocking mode
(blocking mode is the default)
......@@ -48,22 +51,22 @@ Arguments
Description
-----------
This system call, used with a device name of /dev/dvb/adapter0/demux0,
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/adapter0/dvr0 is a logical device to be used
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/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
recorded Transport Stream is replayed by writing to this 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.
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
......
......@@ -33,10 +33,10 @@ Arguments
Description
-----------
This system call returns filtered data, which might be section or 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.
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::
......
......@@ -34,10 +34,10 @@ Description
-----------
This system call is only provided by the logical device
/dev/dvb/adapter0/dvr0, associated with the physical demux device that
``/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/adapter0/demux0.
in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``.
The amount of data to be transferred is implied by count.
......
......@@ -25,18 +25,19 @@ Arguments
File descriptor returned by :c:func:`open() <dvb-dmx-open>`.
``stc``
Pointer to the location where the stc is to be stored.
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 DMX_PES_PCR). Some hardware
supports more than one STC, so you must specify which one by setting the
num 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 .
(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
......
......@@ -34,8 +34,8 @@ 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 DMX_OUT_TSDEMUX_TAP, created via either
DMX_SET_PES_FILTER or DMX_ADD_PID.
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
......
......@@ -33,7 +33,7 @@ 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
this function is not called a buffer size of ``2 * 4096`` bytes will be
used.
......
......@@ -40,8 +40,8 @@ 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
DMX_START ioctl call). If a filter was previously set-up, this filter
will be canceled, and the receive buffer will be flushed.
: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
......
......@@ -29,8 +29,8 @@ Description
-----------
This ioctl call is used to stop the actual filtering operation defined
via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and
started via the DMX_START command.
via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and
started via the :ref:`DMX_START` command.
Return Value
......
......@@ -20,6 +20,6 @@ Signal statistics are provided via
.. note::
Most statistics require the demodulator to be fully locked
(e. g. with FE_HAS_LOCK bit set). See
(e. g. with :c:type:`FE_HAS_LOCK <fe_status>` bit set). See
:ref:`Frontend statistics indicators <frontend-stat-properties>` for
more details.
......@@ -33,7 +33,8 @@ Arguments
Description
===========
Sends the DiSEqC command pointed by ``argp`` to the antenna subsystem.
Sends the DiSEqC command pointed by :c:type:`dvb_diseqc_master_cmd`
to the antenna subsystem.
Return Value
============
......
......@@ -34,8 +34,8 @@ Arguments
Description
===========
All Digital TV frontend devices support the ``FE_GET_INFO`` ioctl. It is used
to identify kernel devices compatible with this specification and to
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
......
......@@ -30,7 +30,7 @@ Arguments
- 0 - normal tune mode
- FE_TUNE_MODE_ONESHOT - When set, this flag will disable any
- ``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
......@@ -42,7 +42,7 @@ Description
===========
Allow setting tuner mode flags to the frontend, between 0 (normal) or
FE_TUNE_MODE_ONESHOT mode
``FE_TUNE_MODE_ONESHOT`` mode
Return Value
......
......@@ -78,7 +78,7 @@ 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
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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment