Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit b6df512a authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[media] dtv-core.rst: move DTV ringbuffer notes to kAPI doc 



Instead of keeping those notes at the file on a non-structured
way, move them to dtv-core.rst, using the proper ReST tags.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent ff54c19d

Documentation/media/kapi/dtv-core.rst

+36 −2
Original line number Diff line number Diff line
@@ -6,8 +6,6 @@ Digital TV Common functions 


.. kernel-doc:: drivers/media/dvb-core/dvb_math.h



.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h



.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
@@ -18,6 +16,42 @@ Digital TV Common functions 
.. kernel-doc:: drivers/media/dvb-core/dvbdev.h

   :export: drivers/media/dvb-core/dvbdev.c



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:: drivers/media/dvb-core/dvb_ringbuffer.h





Digital TV Frontend kABI

drivers/media/dvb-core/dvb_ringbuffer.h

+0 −28
Original line number Diff line number Diff line
@@ -66,34 +66,6 @@ extern void dvb_ringbuffer_init(struct dvb_ringbuffer *rbuf, void *data, 
 *

 * @rbuf: pointer to struct dvb_ringbuffer

 */

/*

 * Notes:

 * ------

 * (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:

 *

 *     *** write @buflen: bytes ***

 *     free = dvb_ringbuffer_free(rbuf);

 *     if (free >= buflen)

 *         count = dvb_ringbuffer_write(rbuf, buffer, buflen);

 *     else

 *         ...

 *

 *     *** read min. 1000, max. @bufsize: bytes ***

 *     avail = dvb_ringbuffer_avail(rbuf);

 *     if (avail >= 1000)

 *         count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize));

 *     else

 *         ...

 *

 * (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.

 */

extern int dvb_ringbuffer_empty(struct dvb_ringbuffer *rbuf);



/**