[linux-block.git] / Documentation / media / kapi / dtv-common.rst

Digital TV Common functions
---------------------------

Math functions
~~~~~~~~~~~~~~

Provide some commonly-used math functions, usually required in order to
estimate signal strength and signal to noise measurements in dB.

.. kernel-doc:: include/media/dvb_math.h


DVB devices
~~~~~~~~~~~

Those functions are responsible for handling the DVB device nodes.

.. kernel-doc:: include/media/dvbdev.h

Digital TV Ring buffer
~~~~~~~~~~~~~~~~~~~~~~

Those routines implement ring buffers used to handle digital TV data and
copy it from/to userspace.

.. note::

  1) For performance reasons read and write routines don't check buffer sizes
     and/or number of bytes free/available. This has to be done before these
     routines are called. For example:

   .. code-block:: c

        /* write @buflen: bytes */
        free = dvb_ringbuffer_free(rbuf);
        if (free >= buflen)
                count = dvb_ringbuffer_write(rbuf, buffer, buflen);
        else
                /* do something */

        /* read min. 1000, max. @bufsize: bytes */
        avail = dvb_ringbuffer_avail(rbuf);
        if (avail >= 1000)
                count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize));
        else
                /* do something */

  2) If there is exactly one reader and one writer, there is no need
     to lock read or write operations.
     Two or more readers must be locked against each other.
     Flushing the buffer counts as a read operation.
     Resetting the buffer counts as a read and write operation.
     Two or more writers must be locked against each other.

.. kernel-doc:: include/media/dvb_ringbuffer.h

Digital TV VB2 handler
~~~~~~~~~~~~~~~~~~~~~~

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