Documentation/media/kapi/dtv-common.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Digital TV Common functions
   4 ---------------------------
   5
   6 Math functions
   7 ~~~~~~~~~~~~~~
   8
   9 Provide some commonly-used math functions, usually required in order to
  10 estimate signal strength and signal to noise measurements in dB.
  11
  12 .. kernel-doc:: include/media/dvb_math.h
  13
  14
  15 DVB devices
  16 ~~~~~~~~~~~
  17
  18 Those functions are responsible for handling the DVB device nodes.
  19
  20 .. kernel-doc:: include/media/dvbdev.h
  21
  22 Digital TV Ring buffer
  23 ~~~~~~~~~~~~~~~~~~~~~~
  24
  25 Those routines implement ring buffers used to handle digital TV data and
  26 copy it from/to userspace.
  27
  28 .. note::
  29
  30   1) For performance reasons read and write routines don't check buffer sizes
  31      and/or number of bytes free/available. This has to be done before these
  32      routines are called. For example:
  33
  34    .. code-block:: c
  35
  36         /* write @buflen: bytes */
  37         free = dvb_ringbuffer_free(rbuf);
  38         if (free >= buflen)
  39                 count = dvb_ringbuffer_write(rbuf, buffer, buflen);
  40         else
  41                 /* do something */
  42
  43         /* read min. 1000, max. @bufsize: bytes */
  44         avail = dvb_ringbuffer_avail(rbuf);
  45         if (avail >= 1000)
  46                 count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize));
  47         else
  48                 /* do something */
  49
  50   2) If there is exactly one reader and one writer, there is no need
  51      to lock read or write operations.
  52      Two or more readers must be locked against each other.
  53      Flushing the buffer counts as a read operation.
  54      Resetting the buffer counts as a read and write operation.
  55      Two or more writers must be locked against each other.
  56
  57 .. kernel-doc:: include/media/dvb_ringbuffer.h
  58
  59 Digital TV VB2 handler
  60 ~~~~~~~~~~~~~~~~~~~~~~
  61
  62 .. kernel-doc:: include/media/dvb_vb2.h