[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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst
index 41df9f1..a3c4642 100644
--- a/Documentation/media/kapi/dtv-core.rst
+++ b/Documentation/media/kapi/dtv-core.rst
@@ -6,8 +6,6 @@
.. 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 @@
.. 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
diff --git a/drivers/media/dvb-core/dvb_ringbuffer.h b/drivers/media/dvb-core/dvb_ringbuffer.h
index 8209eb4..f64bd86 100644
--- a/drivers/media/dvb-core/dvb_ringbuffer.h
+++ b/drivers/media/dvb-core/dvb_ringbuffer.h
@@ -66,34 +66,6 @@
*
* @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);
/**