1 /* 2 * 3 * dvb_ringbuffer.h: ring buffer implementation for the dvb driver 4 * 5 * Copyright (C) 2003 Oliver Endriss 6 * Copyright (C) 2004 Andrew de Quincey 7 * 8 * based on code originally found in av7110.c & dvb_ci.c: 9 * Copyright (C) 1999-2003 Ralph Metzler & Marcus Metzler 10 * for convergence integrated media GmbH 11 * 12 * This program is free software; you can redistribute it and/or 13 * modify it under the terms of the GNU Lesser General Public License 14 * as published by the Free Software Foundation; either version 2.1 15 * of the License, or (at your option) any later version. 16 * 17 * This program is distributed in the hope that it will be useful, 18 * but WITHOUT ANY WARRANTY; without even the implied warranty of 19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 20 * GNU Lesser General Public License for more details. 21 */ 22 23 #ifndef _DVB_RINGBUFFER_H_ 24 #define _DVB_RINGBUFFER_H_ 25 26 #include <linux/spinlock.h> 27 #include <linux/wait.h> 28 29 /** 30 * struct dvb_ringbuffer - Describes a ring buffer used at DVB framework 31 * 32 * @data: Area were the ringbuffer data is written 33 * @size: size of the ringbuffer 34 * @pread: next position to read 35 * @pwrite: next position to write 36 * @error: used by ringbuffer clients to indicate that an error happened. 37 * @queue: Wait queue used by ringbuffer clients to indicate when buffer 38 * was filled 39 * @lock: Spinlock used to protect the ringbuffer 40 */ 41 struct dvb_ringbuffer { 42 u8 *data; 43 ssize_t size; 44 ssize_t pread; 45 ssize_t pwrite; 46 int error; 47 48 wait_queue_head_t queue; 49 spinlock_t lock; 50 }; 51 52 #define DVB_RINGBUFFER_PKTHDRSIZE 3 53 54 /** 55 * dvb_ringbuffer_init - initialize ring buffer, lock and queue 56 * 57 * @rbuf: pointer to struct dvb_ringbuffer 58 * @data: pointer to the buffer where the data will be stored 59 * @len: bytes from ring buffer into @buf 60 */ 61 extern void dvb_ringbuffer_init(struct dvb_ringbuffer *rbuf, void *data, 62 size_t len); 63 64 /** 65 * dvb_ringbuffer_empty - test whether buffer is empty 66 * 67 * @rbuf: pointer to struct dvb_ringbuffer 68 */ 69 extern int dvb_ringbuffer_empty(struct dvb_ringbuffer *rbuf); 70 71 /** 72 * dvb_ringbuffer_free - returns the number of free bytes in the buffer 73 * 74 * @rbuf: pointer to struct dvb_ringbuffer 75 * 76 * Return: number of free bytes in the buffer 77 */ 78 extern ssize_t dvb_ringbuffer_free(struct dvb_ringbuffer *rbuf); 79 80 /** 81 * dvb_ringbuffer_avail - returns the number of bytes waiting in the buffer 82 * 83 * @rbuf: pointer to struct dvb_ringbuffer 84 * 85 * Return: number of bytes waiting in the buffer 86 */ 87 extern ssize_t dvb_ringbuffer_avail(struct dvb_ringbuffer *rbuf); 88 89 /** 90 * dvb_ringbuffer_reset - resets the ringbuffer to initial state 91 * 92 * @rbuf: pointer to struct dvb_ringbuffer 93 * 94 * Resets the read and write pointers to zero and flush the buffer. 95 * 96 * This counts as a read and write operation 97 */ 98 extern void dvb_ringbuffer_reset(struct dvb_ringbuffer *rbuf); 99 100 /* 101 * read routines & macros 102 */ 103 104 /** 105 * dvb_ringbuffer_flush - flush buffer 106 * 107 * @rbuf: pointer to struct dvb_ringbuffer 108 */ 109 extern void dvb_ringbuffer_flush(struct dvb_ringbuffer *rbuf); 110 111 /** 112 * dvb_ringbuffer_flush_spinlock_wakeup- flush buffer protected by spinlock 113 * and wake-up waiting task(s) 114 * 115 * @rbuf: pointer to struct dvb_ringbuffer 116 */ 117 extern void dvb_ringbuffer_flush_spinlock_wakeup(struct dvb_ringbuffer *rbuf); 118 119 /** 120 * DVB_RINGBUFFER_PEEK - peek at byte @offs in the buffer 121 * 122 * @rbuf: pointer to struct dvb_ringbuffer 123 * @offs: offset inside the ringbuffer 124 */ 125 #define DVB_RINGBUFFER_PEEK(rbuf, offs) \ 126 ((rbuf)->data[((rbuf)->pread + (offs)) % (rbuf)->size]) 127 128 /** 129 * DVB_RINGBUFFER_SKIP - advance read ptr by @num bytes 130 * 131 * @rbuf: pointer to struct dvb_ringbuffer 132 * @num: number of bytes to advance 133 */ 134 #define DVB_RINGBUFFER_SKIP(rbuf, num) {\ 135 (rbuf)->pread = ((rbuf)->pread + (num)) % (rbuf)->size;\ 136 } 137 138 /** 139 * dvb_ringbuffer_read_user - Reads a buffer into a user pointer 140 * 141 * @rbuf: pointer to struct dvb_ringbuffer 142 * @buf: pointer to the buffer where the data will be stored 143 * @len: bytes from ring buffer into @buf 144 * 145 * This variant assumes that the buffer is a memory at the userspace. So, 146 * it will internally call copy_to_user(). 147 * 148 * Return: number of bytes transferred or -EFAULT 149 */ 150 extern ssize_t dvb_ringbuffer_read_user(struct dvb_ringbuffer *rbuf, 151 u8 __user *buf, size_t len); 152 153 /** 154 * dvb_ringbuffer_read - Reads a buffer into a pointer 155 * 156 * @rbuf: pointer to struct dvb_ringbuffer 157 * @buf: pointer to the buffer where the data will be stored 158 * @len: bytes from ring buffer into @buf 159 * 160 * This variant assumes that the buffer is a memory at the Kernel space 161 * 162 * Return: number of bytes transferred or -EFAULT 163 */ 164 extern void dvb_ringbuffer_read(struct dvb_ringbuffer *rbuf, 165 u8 *buf, size_t len); 166 167 /* 168 * write routines & macros 169 */ 170 171 /** 172 * DVB_RINGBUFFER_WRITE_BYTE - write single byte to ring buffer 173 * 174 * @rbuf: pointer to struct dvb_ringbuffer 175 * @byte: byte to write 176 */ 177 #define DVB_RINGBUFFER_WRITE_BYTE(rbuf, byte) \ 178 { (rbuf)->data[(rbuf)->pwrite] = (byte); \ 179 (rbuf)->pwrite = ((rbuf)->pwrite + 1) % (rbuf)->size; } 180 181 /** 182 * dvb_ringbuffer_write - Writes a buffer into the ringbuffer 183 * 184 * @rbuf: pointer to struct dvb_ringbuffer 185 * @buf: pointer to the buffer where the data will be read 186 * @len: bytes from ring buffer into @buf 187 * 188 * This variant assumes that the buffer is a memory at the Kernel space 189 * 190 * return: number of bytes transferred or -EFAULT 191 */ 192 extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer *rbuf, const u8 *buf, 193 size_t len); 194 195 /** 196 * dvb_ringbuffer_write_user - Writes a buffer received via a user pointer 197 * 198 * @rbuf: pointer to struct dvb_ringbuffer 199 * @buf: pointer to the buffer where the data will be read 200 * @len: bytes from ring buffer into @buf 201 * 202 * This variant assumes that the buffer is a memory at the userspace. So, 203 * it will internally call copy_from_user(). 204 * 205 * Return: number of bytes transferred or -EFAULT 206 */ 207 extern ssize_t dvb_ringbuffer_write_user(struct dvb_ringbuffer *rbuf, 208 const u8 __user *buf, size_t len); 209 210 /** 211 * dvb_ringbuffer_pkt_write - Write a packet into the ringbuffer. 212 * 213 * @rbuf: Ringbuffer to write to. 214 * @buf: Buffer to write. 215 * @len: Length of buffer (currently limited to 65535 bytes max). 216 * 217 * Return: Number of bytes written, or -EFAULT, -ENOMEM, -EINVAL. 218 */ 219 extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8 *buf, 220 size_t len); 221 222 /** 223 * dvb_ringbuffer_pkt_read_user - Read from a packet in the ringbuffer. 224 * 225 * @rbuf: Ringbuffer concerned. 226 * @idx: Packet index as returned by dvb_ringbuffer_pkt_next(). 227 * @offset: Offset into packet to read from. 228 * @buf: Destination buffer for data. 229 * @len: Size of destination buffer. 230 * 231 * Return: Number of bytes read, or -EFAULT. 232 * 233 * .. note:: 234 * 235 * unlike dvb_ringbuffer_read(), this does **NOT** update the read pointer 236 * in the ringbuffer. You must use dvb_ringbuffer_pkt_dispose() to mark a 237 * packet as no longer required. 238 */ 239 extern ssize_t dvb_ringbuffer_pkt_read_user(struct dvb_ringbuffer *rbuf, 240 size_t idx, 241 int offset, u8 __user *buf, 242 size_t len); 243 244 /** 245 * dvb_ringbuffer_pkt_read - Read from a packet in the ringbuffer. 246 * Note: unlike dvb_ringbuffer_read_user(), this DOES update the read pointer 247 * in the ringbuffer. 248 * 249 * @rbuf: Ringbuffer concerned. 250 * @idx: Packet index as returned by dvb_ringbuffer_pkt_next(). 251 * @offset: Offset into packet to read from. 252 * @buf: Destination buffer for data. 253 * @len: Size of destination buffer. 254 * 255 * Return: Number of bytes read, or -EFAULT. 256 */ 257 extern ssize_t dvb_ringbuffer_pkt_read(struct dvb_ringbuffer *rbuf, size_t idx, 258 int offset, u8 *buf, size_t len); 259 260 /** 261 * dvb_ringbuffer_pkt_dispose - Dispose of a packet in the ring buffer. 262 * 263 * @rbuf: Ring buffer concerned. 264 * @idx: Packet index as returned by dvb_ringbuffer_pkt_next(). 265 */ 266 extern void dvb_ringbuffer_pkt_dispose(struct dvb_ringbuffer *rbuf, size_t idx); 267 268 /** 269 * dvb_ringbuffer_pkt_next - Get the index of the next packet in a ringbuffer. 270 * 271 * @rbuf: Ringbuffer concerned. 272 * @idx: Previous packet index, or -1 to return the first packet index. 273 * @pktlen: On success, will be updated to contain the length of the packet 274 * in bytes. 275 * returns Packet index (if >=0), or -1 if no packets available. 276 */ 277 extern ssize_t dvb_ringbuffer_pkt_next(struct dvb_ringbuffer *rbuf, 278 size_t idx, size_t *pktlen); 279 280 #endif /* _DVB_RINGBUFFER_H_ */ 281