include/media/dvb_ringbuffer.h

0001 /*
0002  *
0003  * dvb_ringbuffer.h: ring buffer implementation for the dvb driver
0004  *
0005  * Copyright (C) 2003 Oliver Endriss
0006  * Copyright (C) 2004 Andrew de Quincey
0007  *
0008  * based on code originally found in av7110.c & dvb_ci.c:
0009  * Copyright (C) 1999-2003 Ralph Metzler & Marcus Metzler
0010  *                         for convergence integrated media GmbH
0011  *
0012  * This program is free software; you can redistribute it and/or
0013  * modify it under the terms of the GNU Lesser General Public License
0014  * as published by the Free Software Foundation; either version 2.1
0015  * of the License, or (at your option) any later version.
0016  *
0017  * This program is distributed in the hope that it will be useful,
0018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0020  * GNU Lesser General Public License for more details.
0021  */
0022
0023 #ifndef _DVB_RINGBUFFER_H_
0024 #define _DVB_RINGBUFFER_H_
0025
0026 #include <linux/spinlock.h>
0027 #include <linux/wait.h>
0028
0029 /**
0030  * struct dvb_ringbuffer - Describes a ring buffer used at DVB framework
0031  *
0032  * @data: Area were the ringbuffer data is written
0033  * @size: size of the ringbuffer
0034  * @pread: next position to read
0035  * @pwrite: next position to write
0036  * @error: used by ringbuffer clients to indicate that an error happened.
0037  * @queue: Wait queue used by ringbuffer clients to indicate when buffer
0038  *         was filled
0039  * @lock: Spinlock used to protect the ringbuffer
0040  */
0041 struct dvb_ringbuffer {
0042     u8               *data;
0043     ssize_t           size;
0044     ssize_t           pread;
0045     ssize_t           pwrite;
0046     int               error;
0047
0048     wait_queue_head_t queue;
0049     spinlock_t        lock;
0050 };
0051
0052 #define DVB_RINGBUFFER_PKTHDRSIZE 3
0053
0054 /**
0055  * dvb_ringbuffer_init - initialize ring buffer, lock and queue
0056  *
0057  * @rbuf: pointer to struct dvb_ringbuffer
0058  * @data: pointer to the buffer where the data will be stored
0059  * @len: bytes from ring buffer into @buf
0060  */
0061 extern void dvb_ringbuffer_init(struct dvb_ringbuffer *rbuf, void *data,
0062                 size_t len);
0063
0064 /**
0065  * dvb_ringbuffer_empty - test whether buffer is empty
0066  *
0067  * @rbuf: pointer to struct dvb_ringbuffer
0068  */
0069 extern int dvb_ringbuffer_empty(struct dvb_ringbuffer *rbuf);
0070
0071 /**
0072  * dvb_ringbuffer_free - returns the number of free bytes in the buffer
0073  *
0074  * @rbuf: pointer to struct dvb_ringbuffer
0075  *
0076  * Return: number of free bytes in the buffer
0077  */
0078 extern ssize_t dvb_ringbuffer_free(struct dvb_ringbuffer *rbuf);
0079
0080 /**
0081  * dvb_ringbuffer_avail - returns the number of bytes waiting in the buffer
0082  *
0083  * @rbuf: pointer to struct dvb_ringbuffer
0084  *
0085  * Return: number of bytes waiting in the buffer
0086  */
0087 extern ssize_t dvb_ringbuffer_avail(struct dvb_ringbuffer *rbuf);
0088
0089 /**
0090  * dvb_ringbuffer_reset - resets the ringbuffer to initial state
0091  *
0092  * @rbuf: pointer to struct dvb_ringbuffer
0093  *
0094  * Resets the read and write pointers to zero and flush the buffer.
0095  *
0096  * This counts as a read and write operation
0097  */
0098 extern void dvb_ringbuffer_reset(struct dvb_ringbuffer *rbuf);
0099
0100 /*
0101  * read routines & macros
0102  */
0103
0104 /**
0105  * dvb_ringbuffer_flush - flush buffer
0106  *
0107  * @rbuf: pointer to struct dvb_ringbuffer
0108  */
0109 extern void dvb_ringbuffer_flush(struct dvb_ringbuffer *rbuf);
0110
0111 /**
0112  * dvb_ringbuffer_flush_spinlock_wakeup- flush buffer protected by spinlock
0113  *      and wake-up waiting task(s)
0114  *
0115  * @rbuf: pointer to struct dvb_ringbuffer
0116  */
0117 extern void dvb_ringbuffer_flush_spinlock_wakeup(struct dvb_ringbuffer *rbuf);
0118
0119 /**
0120  * DVB_RINGBUFFER_PEEK - peek at byte @offs in the buffer
0121  *
0122  * @rbuf: pointer to struct dvb_ringbuffer
0123  * @offs: offset inside the ringbuffer
0124  */
0125 #define DVB_RINGBUFFER_PEEK(rbuf, offs) \
0126             ((rbuf)->data[((rbuf)->pread + (offs)) % (rbuf)->size])
0127
0128 /**
0129  * DVB_RINGBUFFER_SKIP - advance read ptr by @num bytes
0130  *
0131  * @rbuf: pointer to struct dvb_ringbuffer
0132  * @num: number of bytes to advance
0133  */
0134 #define DVB_RINGBUFFER_SKIP(rbuf, num)  {\
0135             (rbuf)->pread = ((rbuf)->pread + (num)) % (rbuf)->size;\
0136 }
0137
0138 /**
0139  * dvb_ringbuffer_read_user - Reads a buffer into a user pointer
0140  *
0141  * @rbuf: pointer to struct dvb_ringbuffer
0142  * @buf: pointer to the buffer where the data will be stored
0143  * @len: bytes from ring buffer into @buf
0144  *
0145  * This variant assumes that the buffer is a memory at the userspace. So,
0146  * it will internally call copy_to_user().
0147  *
0148  * Return: number of bytes transferred or -EFAULT
0149  */
0150 extern ssize_t dvb_ringbuffer_read_user(struct dvb_ringbuffer *rbuf,
0151                    u8 __user *buf, size_t len);
0152
0153 /**
0154  * dvb_ringbuffer_read - Reads a buffer into a pointer
0155  *
0156  * @rbuf: pointer to struct dvb_ringbuffer
0157  * @buf: pointer to the buffer where the data will be stored
0158  * @len: bytes from ring buffer into @buf
0159  *
0160  * This variant assumes that the buffer is a memory at the Kernel space
0161  *
0162  * Return: number of bytes transferred or -EFAULT
0163  */
0164 extern void dvb_ringbuffer_read(struct dvb_ringbuffer *rbuf,
0165                    u8 *buf, size_t len);
0166
0167 /*
0168  * write routines & macros
0169  */
0170
0171 /**
0172  * DVB_RINGBUFFER_WRITE_BYTE - write single byte to ring buffer
0173  *
0174  * @rbuf: pointer to struct dvb_ringbuffer
0175  * @byte: byte to write
0176  */
0177 #define DVB_RINGBUFFER_WRITE_BYTE(rbuf, byte)   \
0178             { (rbuf)->data[(rbuf)->pwrite] = (byte); \
0179             (rbuf)->pwrite = ((rbuf)->pwrite + 1) % (rbuf)->size; }
0180
0181 /**
0182  * dvb_ringbuffer_write - Writes a buffer into the ringbuffer
0183  *
0184  * @rbuf: pointer to struct dvb_ringbuffer
0185  * @buf: pointer to the buffer where the data will be read
0186  * @len: bytes from ring buffer into @buf
0187  *
0188  * This variant assumes that the buffer is a memory at the Kernel space
0189  *
0190  * return: number of bytes transferred or -EFAULT
0191  */
0192 extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer *rbuf, const u8 *buf,
0193                     size_t len);
0194
0195 /**
0196  * dvb_ringbuffer_write_user - Writes a buffer received via a user pointer
0197  *
0198  * @rbuf: pointer to struct dvb_ringbuffer
0199  * @buf: pointer to the buffer where the data will be read
0200  * @len: bytes from ring buffer into @buf
0201  *
0202  * This variant assumes that the buffer is a memory at the userspace. So,
0203  * it will internally call copy_from_user().
0204  *
0205  * Return: number of bytes transferred or -EFAULT
0206  */
0207 extern ssize_t dvb_ringbuffer_write_user(struct dvb_ringbuffer *rbuf,
0208                      const u8 __user *buf, size_t len);
0209
0210 /**
0211  * dvb_ringbuffer_pkt_write - Write a packet into the ringbuffer.
0212  *
0213  * @rbuf: Ringbuffer to write to.
0214  * @buf: Buffer to write.
0215  * @len: Length of buffer (currently limited to 65535 bytes max).
0216  *
0217  * Return: Number of bytes written, or -EFAULT, -ENOMEM, -EVINAL.
0218  */
0219 extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8 *buf,
0220                     size_t len);
0221
0222 /**
0223  * dvb_ringbuffer_pkt_read_user - Read from a packet in the ringbuffer.
0224  *
0225  * @rbuf: Ringbuffer concerned.
0226  * @idx: Packet index as returned by dvb_ringbuffer_pkt_next().
0227  * @offset: Offset into packet to read from.
0228  * @buf: Destination buffer for data.
0229  * @len: Size of destination buffer.
0230  *
0231  * Return: Number of bytes read, or -EFAULT.
0232  *
0233  * .. note::
0234  *
0235  *    unlike dvb_ringbuffer_read(), this does **NOT** update the read pointer
0236  *    in the ringbuffer. You must use dvb_ringbuffer_pkt_dispose() to mark a
0237  *    packet as no longer required.
0238  */
0239 extern ssize_t dvb_ringbuffer_pkt_read_user(struct dvb_ringbuffer *rbuf,
0240                         size_t idx,
0241                         int offset, u8 __user *buf,
0242                         size_t len);
0243
0244 /**
0245  * dvb_ringbuffer_pkt_read - Read from a packet in the ringbuffer.
0246  * Note: unlike dvb_ringbuffer_read_user(), this DOES update the read pointer
0247  * in the ringbuffer.
0248  *
0249  * @rbuf: Ringbuffer concerned.
0250  * @idx: Packet index as returned by dvb_ringbuffer_pkt_next().
0251  * @offset: Offset into packet to read from.
0252  * @buf: Destination buffer for data.
0253  * @len: Size of destination buffer.
0254  *
0255  * Return: Number of bytes read, or -EFAULT.
0256  */
0257 extern ssize_t dvb_ringbuffer_pkt_read(struct dvb_ringbuffer *rbuf, size_t idx,
0258                        int offset, u8 *buf, size_t len);
0259
0260 /**
0261  * dvb_ringbuffer_pkt_dispose - Dispose of a packet in the ring buffer.
0262  *
0263  * @rbuf: Ring buffer concerned.
0264  * @idx: Packet index as returned by dvb_ringbuffer_pkt_next().
0265  */
0266 extern void dvb_ringbuffer_pkt_dispose(struct dvb_ringbuffer *rbuf, size_t idx);
0267
0268 /**
0269  * dvb_ringbuffer_pkt_next - Get the index of the next packet in a ringbuffer.
0270  *
0271  * @rbuf: Ringbuffer concerned.
0272  * @idx: Previous packet index, or -1 to return the first packet index.
0273  * @pktlen: On success, will be updated to contain the length of the packet
0274  *          in bytes.
0275  * returns Packet index (if >=0), or -1 if no packets available.
0276  */
0277 extern ssize_t dvb_ringbuffer_pkt_next(struct dvb_ringbuffer *rbuf,
0278                        size_t idx, size_t *pktlen);
0279
0280 #endif /* _DVB_RINGBUFFER_H_ */