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