diff options
Diffstat (limited to 'drivers/media/dvb-core/dvb_ringbuffer.h')
| -rw-r--r-- | drivers/media/dvb-core/dvb_ringbuffer.h | 226 |
1 files changed, 149 insertions, 77 deletions
diff --git a/drivers/media/dvb-core/dvb_ringbuffer.h b/drivers/media/dvb-core/dvb_ringbuffer.h index 8af642399f1e..bbe94873d44d 100644 --- a/drivers/media/dvb-core/dvb_ringbuffer.h +++ b/drivers/media/dvb-core/dvb_ringbuffer.h @@ -18,10 +18,6 @@ * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef _DVB_RINGBUFFER_H_ @@ -30,6 +26,18 @@ #include <linux/spinlock.h> #include <linux/wait.h> +/** + * struct dvb_ringbuffer - Describes a ring buffer used at DVB framework + * + * @data: Area were the ringbuffer data is written + * @size: size of the ringbuffer + * @pread: next position to read + * @pwrite: next position to write + * @error: used by ringbuffer clients to indicate that an error happened. + * @queue: Wait queue used by ringbuffer clients to indicate when buffer + * was filled + * @lock: Spinlock used to protect the ringbuffer + */ struct dvb_ringbuffer { u8 *data; ssize_t size; @@ -43,99 +51,161 @@ struct dvb_ringbuffer { #define DVB_RINGBUFFER_PKTHDRSIZE 3 +/** + * dvb_ringbuffer_init - initialize ring buffer, lock and queue + * + * @rbuf: pointer to struct dvb_ringbuffer + * @data: pointer to the buffer where the data will be stored + * @len: bytes from ring buffer into @buf + */ +extern void dvb_ringbuffer_init(struct dvb_ringbuffer *rbuf, void *data, + size_t len); -/* - * 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. - */ - -/* initialize ring buffer, lock and queue */ -extern void dvb_ringbuffer_init(struct dvb_ringbuffer *rbuf, void *data, size_t len); - -/* test whether buffer is empty */ +/** + * dvb_ringbuffer_empty - test whether buffer is empty + * + * @rbuf: pointer to struct dvb_ringbuffer + */ extern int dvb_ringbuffer_empty(struct dvb_ringbuffer *rbuf); -/* return the number of free bytes in the buffer */ +/** + * dvb_ringbuffer_free - returns the number of free bytes in the buffer + * + * @rbuf: pointer to struct dvb_ringbuffer + * + * Return: number of free bytes in the buffer + */ extern ssize_t dvb_ringbuffer_free(struct dvb_ringbuffer *rbuf); -/* return the number of bytes waiting in the buffer */ +/** + * dvb_ringbuffer_avail - returns the number of bytes waiting in the buffer + * + * @rbuf: pointer to struct dvb_ringbuffer + * + * Return: number of bytes waiting in the buffer + */ extern ssize_t dvb_ringbuffer_avail(struct dvb_ringbuffer *rbuf); - -/* - * Reset the read and write pointers to zero and flush the buffer +/** + * dvb_ringbuffer_reset - resets the ringbuffer to initial state + * + * @rbuf: pointer to struct dvb_ringbuffer + * + * Resets the read and write pointers to zero and flush the buffer. + * * This counts as a read and write operation */ extern void dvb_ringbuffer_reset(struct dvb_ringbuffer *rbuf); +/* + * read routines & macros + */ -/* read routines & macros */ -/* ---------------------- */ -/* flush buffer */ +/** + * dvb_ringbuffer_flush - flush buffer + * + * @rbuf: pointer to struct dvb_ringbuffer + */ extern void dvb_ringbuffer_flush(struct dvb_ringbuffer *rbuf); -/* flush buffer protected by spinlock and wake-up waiting task(s) */ +/** + * dvb_ringbuffer_flush_spinlock_wakeup- flush buffer protected by spinlock + * and wake-up waiting task(s) + * + * @rbuf: pointer to struct dvb_ringbuffer + */ extern void dvb_ringbuffer_flush_spinlock_wakeup(struct dvb_ringbuffer *rbuf); -/* peek at byte @offs: in the buffer */ -#define DVB_RINGBUFFER_PEEK(rbuf,offs) \ - (rbuf)->data[((rbuf)->pread+(offs))%(rbuf)->size] +/** + * DVB_RINGBUFFER_PEEK - peek at byte @offs in the buffer + * + * @rbuf: pointer to struct dvb_ringbuffer + * @offs: offset inside the ringbuffer + */ +#define DVB_RINGBUFFER_PEEK(rbuf, offs) \ + ((rbuf)->data[((rbuf)->pread + (offs)) % (rbuf)->size]) -/* advance read ptr by @num: bytes */ -#define DVB_RINGBUFFER_SKIP(rbuf,num) \ - (rbuf)->pread=((rbuf)->pread+(num))%(rbuf)->size +/** + * DVB_RINGBUFFER_SKIP - advance read ptr by @num bytes + * + * @rbuf: pointer to struct dvb_ringbuffer + * @num: number of bytes to advance + */ +#define DVB_RINGBUFFER_SKIP(rbuf, num) {\ + (rbuf)->pread = ((rbuf)->pread + (num)) % (rbuf)->size;\ +} -/* - * read @len: bytes from ring buffer into @buf: - * @usermem: specifies whether @buf: resides in user space - * returns number of bytes transferred or -EFAULT +/** + * dvb_ringbuffer_read_user - Reads a buffer into an user pointer + * + * @rbuf: pointer to struct dvb_ringbuffer + * @buf: pointer to the buffer where the data will be stored + * @len: bytes from ring buffer into @buf + * + * This variant assumes that the buffer is a memory at the userspace. So, + * it will internally call copy_to_user(). + * + * Return: number of bytes transferred or -EFAULT */ extern ssize_t dvb_ringbuffer_read_user(struct dvb_ringbuffer *rbuf, u8 __user *buf, size_t len); + +/** + * dvb_ringbuffer_read - Reads a buffer into a pointer + * + * @rbuf: pointer to struct dvb_ringbuffer + * @buf: pointer to the buffer where the data will be stored + * @len: bytes from ring buffer into @buf + * + * This variant assumes that the buffer is a memory at the Kernel space + * + * Return: number of bytes transferred or -EFAULT + */ extern void dvb_ringbuffer_read(struct dvb_ringbuffer *rbuf, u8 *buf, size_t len); - -/* write routines & macros */ -/* ----------------------- */ -/* write single byte to ring buffer */ -#define DVB_RINGBUFFER_WRITE_BYTE(rbuf,byte) \ - { (rbuf)->data[(rbuf)->pwrite]=(byte); \ - (rbuf)->pwrite=((rbuf)->pwrite+1)%(rbuf)->size; } /* - * write @len: bytes to ring buffer - * @usermem: specifies whether @buf: resides in user space - * returns number of bytes transferred or -EFAULT -*/ + * write routines & macros + */ + +/** + * DVB_RINGBUFFER_WRITE_BYTE - write single byte to ring buffer + * + * @rbuf: pointer to struct dvb_ringbuffer + * @byte: byte to write + */ +#define DVB_RINGBUFFER_WRITE_BYTE(rbuf, byte) \ + { (rbuf)->data[(rbuf)->pwrite] = (byte); \ + (rbuf)->pwrite = ((rbuf)->pwrite + 1) % (rbuf)->size; } + +/** + * dvb_ringbuffer_write - Writes a buffer into the ringbuffer + * + * @rbuf: pointer to struct dvb_ringbuffer + * @buf: pointer to the buffer where the data will be read + * @len: bytes from ring buffer into @buf + * + * This variant assumes that the buffer is a memory at the Kernel space + * + * return: number of bytes transferred or -EFAULT + */ extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer *rbuf, const u8 *buf, size_t len); -extern ssize_t dvb_ringbuffer_write_user(struct dvb_ringbuffer *rbuf, - const u8 __user *buf, size_t len); +/** + * dvb_ringbuffer_write_user - Writes a buffer received via an user pointer + * + * @rbuf: pointer to struct dvb_ringbuffer + * @buf: pointer to the buffer where the data will be read + * @len: bytes from ring buffer into @buf + * + * This variant assumes that the buffer is a memory at the userspace. So, + * it will internally call copy_from_user(). + * + * Return: number of bytes transferred or -EFAULT + */ +extern ssize_t dvb_ringbuffer_write_user(struct dvb_ringbuffer *rbuf, + const u8 __user *buf, size_t len); /** * dvb_ringbuffer_pkt_write - Write a packet into the ringbuffer. @@ -143,9 +213,10 @@ extern ssize_t dvb_ringbuffer_write_user(struct dvb_ringbuffer *rbuf, * @rbuf: Ringbuffer to write to. * @buf: Buffer to write. * @len: Length of buffer (currently limited to 65535 bytes max). - * returns Number of bytes written, or -EFAULT, -ENOMEM, -EVINAL. + * + * Return: Number of bytes written, or -EFAULT, -ENOMEM, -EVINAL. */ -extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8* buf, +extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8 *buf, size_t len); /** @@ -157,7 +228,7 @@ extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8* buf, * @buf: Destination buffer for data. * @len: Size of destination buffer. * - * returns Number of bytes read, or -EFAULT. + * Return: Number of bytes read, or -EFAULT. * * .. note:: * @@ -167,7 +238,7 @@ extern ssize_t dvb_ringbuffer_pkt_write(struct dvb_ringbuffer *rbuf, u8* buf, */ extern ssize_t dvb_ringbuffer_pkt_read_user(struct dvb_ringbuffer *rbuf, size_t idx, - int offset, u8 __user *buf, + int offset, u8 __user *buf, size_t len); /** @@ -181,7 +252,7 @@ extern ssize_t dvb_ringbuffer_pkt_read_user(struct dvb_ringbuffer *rbuf, * @buf: Destination buffer for data. * @len: Size of destination buffer. * - * returns Number of bytes read, or -EFAULT. + * Return: Number of bytes read, or -EFAULT. */ extern ssize_t dvb_ringbuffer_pkt_read(struct dvb_ringbuffer *rbuf, size_t idx, int offset, u8 *buf, size_t len); @@ -199,10 +270,11 @@ extern void dvb_ringbuffer_pkt_dispose(struct dvb_ringbuffer *rbuf, size_t idx); * * @rbuf: Ringbuffer concerned. * @idx: Previous packet index, or -1 to return the first packet index. - * @pktlen: On success, will be updated to contain the length of the packet in bytes. + * @pktlen: On success, will be updated to contain the length of the packet + * in bytes. * returns Packet index (if >=0), or -1 if no packets available. */ -extern ssize_t dvb_ringbuffer_pkt_next(struct dvb_ringbuffer *rbuf, size_t idx, size_t* pktlen); - +extern ssize_t dvb_ringbuffer_pkt_next(struct dvb_ringbuffer *rbuf, + size_t idx, size_t *pktlen); #endif /* _DVB_RINGBUFFER_H_ */ |