kfifo: fix Error/broken kernel-doc notation
[linux-2.6/linux-acpi-2.6/ibm-acpi-2.6.git] / include / linux / kfifo.h
blob3d44e9c65a8e3afa5621b8f771f7e0b54dc40515
1 /*
2 * A generic kernel FIFO implementation.
4 * Copyright (C) 2009 Stefani Seibold <stefani@seibold.net>
5 * Copyright (C) 2004 Stelian Pop <stelian@popies.net>
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 * Howto porting drivers to the new generic fifo API:
26 * - Modify the declaration of the "struct kfifo *" object into a
27 * in-place "struct kfifo" object
28 * - Init the in-place object with kfifo_alloc() or kfifo_init()
29 * Note: The address of the in-place "struct kfifo" object must be
30 * passed as the first argument to this functions
31 * - Replace the use of __kfifo_put into kfifo_in and __kfifo_get
32 * into kfifo_out
33 * - Replace the use of kfifo_put into kfifo_in_locked and kfifo_get
34 * into kfifo_out_locked
35 * Note: the spinlock pointer formerly passed to kfifo_init/kfifo_alloc
36 * must be passed now to the kfifo_in_locked and kfifo_out_locked
37 * as the last parameter.
38 * - All formerly name __kfifo_* functions has been renamed into kfifo_*
41 #ifndef _LINUX_KFIFO_H
42 #define _LINUX_KFIFO_H
44 #include <linux/kernel.h>
45 #include <linux/spinlock.h>
47 struct kfifo {
48 unsigned char *buffer; /* the buffer holding the data */
49 unsigned int size; /* the size of the allocated buffer */
50 unsigned int in; /* data is added at offset (in % size) */
51 unsigned int out; /* data is extracted from off. (out % size) */
55 * Macros for declaration and initialization of the kfifo datatype
58 /* helper macro */
59 #define __kfifo_initializer(s, b) \
60 (struct kfifo) { \
61 .size = s, \
62 .in = 0, \
63 .out = 0, \
64 .buffer = b \
67 /**
68 * DECLARE_KFIFO - macro to declare a kfifo and the associated buffer
69 * @name: name of the declared kfifo datatype
70 * @size: size of the fifo buffer
72 * Note1: the macro can be used inside struct or union declaration
73 * Note2: the macro creates two objects:
74 * A kfifo object with the given name and a buffer for the kfifo
75 * object named name##kfifo_buffer
77 #define DECLARE_KFIFO(name, size) \
78 union { \
79 struct kfifo name; \
80 unsigned char name##kfifo_buffer[size + sizeof(struct kfifo)]; \
83 /**
84 * INIT_KFIFO - Initialize a kfifo declared by DECLARED_KFIFO
85 * @name: name of the declared kfifo datatype
87 #define INIT_KFIFO(name) \
88 name = __kfifo_initializer(sizeof(name##kfifo_buffer) - \
89 sizeof(struct kfifo), name##kfifo_buffer)
91 /**
92 * DEFINE_KFIFO - macro to define and initialize a kfifo
93 * @name: name of the declared kfifo datatype
94 * @size: size of the fifo buffer
96 * Note1: the macro can be used for global and local kfifo data type variables
97 * Note2: the macro creates two objects:
98 * A kfifo object with the given name and a buffer for the kfifo
99 * object named name##kfifo_buffer
101 #define DEFINE_KFIFO(name, size) \
102 unsigned char name##kfifo_buffer[size]; \
103 struct kfifo name = __kfifo_initializer(size, name##kfifo_buffer)
105 #undef __kfifo_initializer
107 extern void kfifo_init(struct kfifo *fifo, unsigned char *buffer,
108 unsigned int size);
109 extern __must_check int kfifo_alloc(struct kfifo *fifo, unsigned int size,
110 gfp_t gfp_mask);
111 extern void kfifo_free(struct kfifo *fifo);
112 extern unsigned int kfifo_in(struct kfifo *fifo,
113 const unsigned char *from, unsigned int len);
114 extern __must_check unsigned int kfifo_out(struct kfifo *fifo,
115 unsigned char *to, unsigned int len);
118 * kfifo_reset - removes the entire FIFO contents
119 * @fifo: the fifo to be emptied.
121 static inline void kfifo_reset(struct kfifo *fifo)
123 fifo->in = fifo->out = 0;
127 * kfifo_reset_out - skip FIFO contents
128 * @fifo: the fifo to be emptied.
130 static inline void kfifo_reset_out(struct kfifo *fifo)
132 smp_mb();
133 fifo->out = fifo->in;
137 * kfifo_size - returns the size of the fifo in bytes
138 * @fifo: the fifo to be used.
140 static inline __must_check unsigned int kfifo_size(struct kfifo *fifo)
142 return fifo->size;
146 * kfifo_len - returns the number of used bytes in the FIFO
147 * @fifo: the fifo to be used.
149 static inline unsigned int kfifo_len(struct kfifo *fifo)
151 register unsigned int out;
153 out = fifo->out;
154 smp_rmb();
155 return fifo->in - out;
159 * kfifo_is_empty - returns true if the fifo is empty
160 * @fifo: the fifo to be used.
162 static inline __must_check int kfifo_is_empty(struct kfifo *fifo)
164 return fifo->in == fifo->out;
168 * kfifo_is_full - returns true if the fifo is full
169 * @fifo: the fifo to be used.
171 static inline __must_check int kfifo_is_full(struct kfifo *fifo)
173 return kfifo_len(fifo) == kfifo_size(fifo);
177 * kfifo_avail - returns the number of bytes available in the FIFO
178 * @fifo: the fifo to be used.
180 static inline __must_check unsigned int kfifo_avail(struct kfifo *fifo)
182 return kfifo_size(fifo) - kfifo_len(fifo);
186 * kfifo_in_locked - puts some data into the FIFO using a spinlock for locking
187 * @fifo: the fifo to be used.
188 * @from: the data to be added.
189 * @n: the length of the data to be added.
190 * @lock: pointer to the spinlock to use for locking.
192 * This function copies at most @len bytes from the @from buffer into
193 * the FIFO depending on the free space, and returns the number of
194 * bytes copied.
196 static inline unsigned int kfifo_in_locked(struct kfifo *fifo,
197 const unsigned char *from, unsigned int n, spinlock_t *lock)
199 unsigned long flags;
200 unsigned int ret;
202 spin_lock_irqsave(lock, flags);
204 ret = kfifo_in(fifo, from, n);
206 spin_unlock_irqrestore(lock, flags);
208 return ret;
212 * kfifo_out_locked - gets some data from the FIFO using a spinlock for locking
213 * @fifo: the fifo to be used.
214 * @to: where the data must be copied.
215 * @n: the size of the destination buffer.
216 * @lock: pointer to the spinlock to use for locking.
218 * This function copies at most @len bytes from the FIFO into the
219 * @to buffer and returns the number of copied bytes.
221 static inline __must_check unsigned int kfifo_out_locked(struct kfifo *fifo,
222 unsigned char *to, unsigned int n, spinlock_t *lock)
224 unsigned long flags;
225 unsigned int ret;
227 spin_lock_irqsave(lock, flags);
229 ret = kfifo_out(fifo, to, n);
232 * optimization: if the FIFO is empty, set the indices to 0
233 * so we don't wrap the next time
235 if (kfifo_is_empty(fifo))
236 kfifo_reset(fifo);
238 spin_unlock_irqrestore(lock, flags);
240 return ret;
243 extern void kfifo_skip(struct kfifo *fifo, unsigned int len);
245 extern __must_check unsigned int kfifo_from_user(struct kfifo *fifo,
246 const void __user *from, unsigned int n);
248 extern __must_check unsigned int kfifo_to_user(struct kfifo *fifo,
249 void __user *to, unsigned int n);
252 * __kfifo_add_out internal helper function for updating the out offset
254 static inline void __kfifo_add_out(struct kfifo *fifo,
255 unsigned int off)
257 smp_mb();
258 fifo->out += off;
262 * __kfifo_add_in internal helper function for updating the in offset
264 static inline void __kfifo_add_in(struct kfifo *fifo,
265 unsigned int off)
267 smp_wmb();
268 fifo->in += off;
272 * __kfifo_off internal helper function for calculating the index of a
273 * given offeset
275 static inline unsigned int __kfifo_off(struct kfifo *fifo, unsigned int off)
277 return off & (fifo->size - 1);
281 * __kfifo_peek_n internal helper function for determinate the length of
282 * the next record in the fifo
284 static inline unsigned int __kfifo_peek_n(struct kfifo *fifo,
285 unsigned int recsize)
287 #define __KFIFO_GET(fifo, off, shift) \
288 ((fifo)->buffer[__kfifo_off((fifo), (fifo)->out+(off))] << (shift))
290 unsigned int l;
292 l = __KFIFO_GET(fifo, 0, 0);
294 if (--recsize)
295 l |= __KFIFO_GET(fifo, 1, 8);
297 return l;
298 #undef __KFIFO_GET
302 * __kfifo_poke_n internal helper function for storing the length of
303 * the next record into the fifo
305 static inline void __kfifo_poke_n(struct kfifo *fifo,
306 unsigned int recsize, unsigned int n)
308 #define __KFIFO_PUT(fifo, off, val, shift) \
310 (fifo)->buffer[__kfifo_off((fifo), (fifo)->in+(off))] = \
311 (unsigned char)((val) >> (shift)) \
314 __KFIFO_PUT(fifo, 0, n, 0);
316 if (--recsize)
317 __KFIFO_PUT(fifo, 1, n, 8);
318 #undef __KFIFO_PUT
322 * __kfifo_in_... internal functions for put date into the fifo
323 * do not call it directly, use kfifo_in_rec() instead
325 extern unsigned int __kfifo_in_n(struct kfifo *fifo,
326 const void *from, unsigned int n, unsigned int recsize);
328 extern unsigned int __kfifo_in_generic(struct kfifo *fifo,
329 const void *from, unsigned int n, unsigned int recsize);
331 static inline unsigned int __kfifo_in_rec(struct kfifo *fifo,
332 const void *from, unsigned int n, unsigned int recsize)
334 unsigned int ret;
336 ret = __kfifo_in_n(fifo, from, n, recsize);
338 if (likely(ret == 0)) {
339 if (recsize)
340 __kfifo_poke_n(fifo, recsize, n);
341 __kfifo_add_in(fifo, n + recsize);
343 return ret;
347 * kfifo_in_rec - puts some record data into the FIFO
348 * @fifo: the fifo to be used.
349 * @from: the data to be added.
350 * @n: the length of the data to be added.
351 * @recsize: size of record field
353 * This function copies @n bytes from the @from into the FIFO and returns
354 * the number of bytes which cannot be copied.
355 * A returned value greater than the @n value means that the record doesn't
356 * fit into the buffer.
358 * Note that with only one concurrent reader and one concurrent
359 * writer, you don't need extra locking to use these functions.
361 static inline __must_check unsigned int kfifo_in_rec(struct kfifo *fifo,
362 void *from, unsigned int n, unsigned int recsize)
364 if (!__builtin_constant_p(recsize))
365 return __kfifo_in_generic(fifo, from, n, recsize);
366 return __kfifo_in_rec(fifo, from, n, recsize);
370 * __kfifo_out_... internal functions for get date from the fifo
371 * do not call it directly, use kfifo_out_rec() instead
373 extern unsigned int __kfifo_out_n(struct kfifo *fifo,
374 void *to, unsigned int reclen, unsigned int recsize);
376 extern unsigned int __kfifo_out_generic(struct kfifo *fifo,
377 void *to, unsigned int n,
378 unsigned int recsize, unsigned int *total);
380 static inline unsigned int __kfifo_out_rec(struct kfifo *fifo,
381 void *to, unsigned int n, unsigned int recsize,
382 unsigned int *total)
384 unsigned int l;
386 if (!recsize) {
387 l = n;
388 if (total)
389 *total = l;
390 } else {
391 l = __kfifo_peek_n(fifo, recsize);
392 if (total)
393 *total = l;
394 if (n < l)
395 return l;
398 return __kfifo_out_n(fifo, to, l, recsize);
402 * kfifo_out_rec - gets some record data from the FIFO
403 * @fifo: the fifo to be used.
404 * @to: where the data must be copied.
405 * @n: the size of the destination buffer.
406 * @recsize: size of record field
407 * @total: pointer where the total number of to copied bytes should stored
409 * This function copies at most @n bytes from the FIFO to @to and returns the
410 * number of bytes which cannot be copied.
411 * A returned value greater than the @n value means that the record doesn't
412 * fit into the @to buffer.
414 * Note that with only one concurrent reader and one concurrent
415 * writer, you don't need extra locking to use these functions.
417 static inline __must_check unsigned int kfifo_out_rec(struct kfifo *fifo,
418 void *to, unsigned int n, unsigned int recsize,
419 unsigned int *total)
422 if (!__builtin_constant_p(recsize))
423 return __kfifo_out_generic(fifo, to, n, recsize, total);
424 return __kfifo_out_rec(fifo, to, n, recsize, total);
428 * __kfifo_from_user_... internal functions for transfer from user space into
429 * the fifo. do not call it directly, use kfifo_from_user_rec() instead
431 extern unsigned int __kfifo_from_user_n(struct kfifo *fifo,
432 const void __user *from, unsigned int n, unsigned int recsize);
434 extern unsigned int __kfifo_from_user_generic(struct kfifo *fifo,
435 const void __user *from, unsigned int n, unsigned int recsize);
437 static inline unsigned int __kfifo_from_user_rec(struct kfifo *fifo,
438 const void __user *from, unsigned int n, unsigned int recsize)
440 unsigned int ret;
442 ret = __kfifo_from_user_n(fifo, from, n, recsize);
444 if (likely(ret == 0)) {
445 if (recsize)
446 __kfifo_poke_n(fifo, recsize, n);
447 __kfifo_add_in(fifo, n + recsize);
449 return ret;
453 * kfifo_from_user_rec - puts some data from user space into the FIFO
454 * @fifo: the fifo to be used.
455 * @from: pointer to the data to be added.
456 * @n: the length of the data to be added.
457 * @recsize: size of record field
459 * This function copies @n bytes from the @from into the
460 * FIFO and returns the number of bytes which cannot be copied.
462 * If the returned value is equal or less the @n value, the copy_from_user()
463 * functions has failed. Otherwise the record doesn't fit into the buffer.
465 * Note that with only one concurrent reader and one concurrent
466 * writer, you don't need extra locking to use these functions.
468 static inline __must_check unsigned int kfifo_from_user_rec(struct kfifo *fifo,
469 const void __user *from, unsigned int n, unsigned int recsize)
471 if (!__builtin_constant_p(recsize))
472 return __kfifo_from_user_generic(fifo, from, n, recsize);
473 return __kfifo_from_user_rec(fifo, from, n, recsize);
477 * __kfifo_to_user_... internal functions for transfer fifo data into user space
478 * do not call it directly, use kfifo_to_user_rec() instead
480 extern unsigned int __kfifo_to_user_n(struct kfifo *fifo,
481 void __user *to, unsigned int n, unsigned int reclen,
482 unsigned int recsize);
484 extern unsigned int __kfifo_to_user_generic(struct kfifo *fifo,
485 void __user *to, unsigned int n, unsigned int recsize,
486 unsigned int *total);
488 static inline unsigned int __kfifo_to_user_rec(struct kfifo *fifo,
489 void __user *to, unsigned int n,
490 unsigned int recsize, unsigned int *total)
492 unsigned int l;
494 if (!recsize) {
495 l = n;
496 if (total)
497 *total = l;
498 } else {
499 l = __kfifo_peek_n(fifo, recsize);
500 if (total)
501 *total = l;
502 if (n < l)
503 return l;
506 return __kfifo_to_user_n(fifo, to, n, l, recsize);
510 * kfifo_to_user_rec - gets data from the FIFO and write it to user space
511 * @fifo: the fifo to be used.
512 * @to: where the data must be copied.
513 * @n: the size of the destination buffer.
514 * @recsize: size of record field
515 * @total: pointer where the total number of to copied bytes should stored
517 * This function copies at most @n bytes from the FIFO to the @to.
518 * In case of an error, the function returns the number of bytes which cannot
519 * be copied.
520 * If the returned value is equal or less the @n value, the copy_to_user()
521 * functions has failed. Otherwise the record doesn't fit into the @to buffer.
523 * Note that with only one concurrent reader and one concurrent
524 * writer, you don't need extra locking to use these functions.
526 static inline __must_check unsigned int kfifo_to_user_rec(struct kfifo *fifo,
527 void __user *to, unsigned int n, unsigned int recsize,
528 unsigned int *total)
530 if (!__builtin_constant_p(recsize))
531 return __kfifo_to_user_generic(fifo, to, n, recsize, total);
532 return __kfifo_to_user_rec(fifo, to, n, recsize, total);
536 * __kfifo_peek_... internal functions for peek into the next fifo record
537 * do not call it directly, use kfifo_peek_rec() instead
539 extern unsigned int __kfifo_peek_generic(struct kfifo *fifo,
540 unsigned int recsize);
543 * kfifo_peek_rec - gets the size of the next FIFO record data
544 * @fifo: the fifo to be used.
545 * @recsize: size of record field
547 * This function returns the size of the next FIFO record in number of bytes
549 static inline __must_check unsigned int kfifo_peek_rec(struct kfifo *fifo,
550 unsigned int recsize)
552 if (!__builtin_constant_p(recsize))
553 return __kfifo_peek_generic(fifo, recsize);
554 if (!recsize)
555 return kfifo_len(fifo);
556 return __kfifo_peek_n(fifo, recsize);
560 * __kfifo_skip_... internal functions for skip the next fifo record
561 * do not call it directly, use kfifo_skip_rec() instead
563 extern void __kfifo_skip_generic(struct kfifo *fifo, unsigned int recsize);
565 static inline void __kfifo_skip_rec(struct kfifo *fifo,
566 unsigned int recsize)
568 unsigned int l;
570 if (recsize) {
571 l = __kfifo_peek_n(fifo, recsize);
573 if (l + recsize <= kfifo_len(fifo)) {
574 __kfifo_add_out(fifo, l + recsize);
575 return;
578 kfifo_reset_out(fifo);
582 * kfifo_skip_rec - skip the next fifo out record
583 * @fifo: the fifo to be used.
584 * @recsize: size of record field
586 * This function skips the next FIFO record
588 static inline void kfifo_skip_rec(struct kfifo *fifo,
589 unsigned int recsize)
591 if (!__builtin_constant_p(recsize))
592 __kfifo_skip_generic(fifo, recsize);
593 else
594 __kfifo_skip_rec(fifo, recsize);
598 * kfifo_avail_rec - returns the number of bytes available in a record FIFO
599 * @fifo: the fifo to be used.
600 * @recsize: size of record field
602 static inline __must_check unsigned int kfifo_avail_rec(struct kfifo *fifo,
603 unsigned int recsize)
605 unsigned int l = kfifo_size(fifo) - kfifo_len(fifo);
607 return (l > recsize) ? l - recsize : 0;
610 #endif