From b6df512a9f9580abc07cd1963ced91b5a87619ed Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 29 Aug 2016 08:39:32 -0300 Subject: [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 --- Documentation/media/kapi/dtv-core.rst | 38 +++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) (limited to 'Documentation/media/kapi') diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst index 41df9f144fcb..a3c4642eabfc 100644 --- a/Documentation/media/kapi/dtv-core.rst +++ b/Documentation/media/kapi/dtv-core.rst @@ -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 -- cgit v1.2.3