drivers/media/dvb/dvb-core/dvb_ringbuffer.h

   1 /*
   2  *
   3  * dvb_ringbuffer.h: ring buffer implementation for the dvb driver
   4  *
   5  * Copyright (C) 2003 Oliver Endriss
   6  *
   7  * based on code originally found in av7110.c:
   8  * Copyright (C) 1999-2002 Ralph Metzler & Marcus Metzler
   9  *                         for convergence integrated media GmbH
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public License
  13  * as published by the Free Software Foundation; either version 2.1
  14  * of the License, or (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * along with this program; if not, write to the Free Software
  23  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  24  */
  25
  26 #ifndef _DVB_RINGBUFFER_H_
  27 #define _DVB_RINGBUFFER_H_
  28
  29 #include <linux/spinlock.h>
  30 #include <linux/wait.h>
  31
  32 struct dvb_ringbuffer {
  33         u8               *data;
  34         ssize_t           size;
  35         ssize_t           pread;
  36         ssize_t           pwrite;
  37
  38         wait_queue_head_t queue;
  39         spinlock_t        lock;
  40 };
  41
  42
  43 /*
  44 ** Notes:
  45 ** ------
  46 ** (1) For performance reasons read and write routines don't check buffer sizes
  47 **     and/or number of bytes free/available. This has to be done before these
  48 **     routines are called. For example:
  49 **
  50 **     *** write <buflen> bytes ***
  51 **     free = dvb_ringbuffer_free(rbuf);
  52 **     if (free >= buflen)
  53 **         count = dvb_ringbuffer_write(rbuf, buffer, buflen, 0);
  54 **     else
  55 **         ...
  56 **
  57 **     *** read min. 1000, max. <bufsize> bytes ***
  58 **     avail = dvb_ringbuffer_avail(rbuf);
  59 **     if (avail >= 1000)
  60 **         count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize), 0);
  61 **     else
  62 **         ...
  63 **
  64 ** (2) If there is exactly one reader and one writer, there is no need
  65 **     to lock read or write operations.
  66 **     Two or more readers must be locked against each other.
  67 **     Flushing the buffer counts as a read operation.
  68 **     Two or more writers must be locked against each other.
  69 */
  70
  71 /* initialize ring buffer, lock and queue */
  72 extern void dvb_ringbuffer_init(struct dvb_ringbuffer *rbuf, void *data, size_t len);
  73
  74 /* test whether buffer is empty */
  75 extern int dvb_ringbuffer_empty(struct dvb_ringbuffer *rbuf);
  76
  77 /* return the number of free bytes in the buffer */
  78 extern ssize_t dvb_ringbuffer_free(struct dvb_ringbuffer *rbuf);
  79
  80 /* return the number of bytes waiting in the buffer */
  81 extern ssize_t dvb_ringbuffer_avail(struct dvb_ringbuffer *rbuf);
  82
  83
  84 /* read routines & macros */
  85 /* ---------------------- */
  86 /* flush buffer */
  87 extern void dvb_ringbuffer_flush(struct dvb_ringbuffer *rbuf);
  88
  89 /* flush buffer protected by spinlock and wake-up waiting task(s) */
  90 extern void dvb_ringbuffer_flush_spinlock_wakeup(struct dvb_ringbuffer *rbuf);
  91
  92 /* peek at byte <offs> in the buffer */
  93 #define DVB_RINGBUFFER_PEEK(rbuf,offs)  \
  94                         (rbuf)->data[((rbuf)->pread+(offs))%(rbuf)->size]
  95
  96 /* advance read ptr by <num> bytes */
  97 #define DVB_RINGBUFFER_SKIP(rbuf,num)   \
  98                         (rbuf)->pread=((rbuf)->pread+(num))%(rbuf)->size
  99
 100 /*
 101 ** read <len> bytes from ring buffer into <buf>
 102 ** <usermem> specifies whether <buf> resides in user space
 103 ** returns number of bytes transferred or -EFAULT
 104 */
 105 extern ssize_t dvb_ringbuffer_read(struct dvb_ringbuffer *rbuf, u8 *buf,
 106                                    size_t len, int usermem);
 107
 108
 109 /* write routines & macros */
 110 /* ----------------------- */
 111 /* write single byte to ring buffer */
 112 #define DVB_RINGBUFFER_WRITE_BYTE(rbuf,byte)    \
 113                         { (rbuf)->data[(rbuf)->pwrite]=(byte); \
 114                         (rbuf)->pwrite=((rbuf)->pwrite+1)%(rbuf)->size; }
 115 /*
 116 ** write <len> bytes to ring buffer
 117 ** <usermem> specifies whether <buf> resides in user space
 118 ** returns number of bytes transferred or -EFAULT
 119 */
 120 extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer *rbuf, const u8 *buf,
 121                                     size_t len, int usermem);
 122
 123 #endif /* _DVB_RINGBUFFER_H_ */