kfifo: use void * pointers for user buffers
[linux-2.6.git] / include / linux / kfifo.h
1 /*
2  * A generic kernel FIFO implementation.
3  *
4  * Copyright (C) 2009 Stefani Seibold <stefani@seibold.net>
5  * Copyright (C) 2004 Stelian Pop <stelian@popies.net>
6  *
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.
11  *
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.
16  *
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.
20  *
21  */
22
23 /*
24  * Howto porting drivers to the new generic fifo API:
25  *
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_*
39  */
40
41 #ifndef _LINUX_KFIFO_H
42 #define _LINUX_KFIFO_H
43
44 #include <linux/kernel.h>
45 #include <linux/spinlock.h>
46
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) */
52 };
53
54 /*
55  * Macros for declaration and initialization of the kfifo datatype
56  */
57
58 /* helper macro */
59 #define __kfifo_initializer(s, b) \
60         (struct kfifo) { \
61                 .size   = s, \
62                 .in     = 0, \
63                 .out    = 0, \
64                 .buffer = b \
65         }
66
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
71  *
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
76  */
77 #define DECLARE_KFIFO(name, size) \
78 union { \
79         struct kfifo name; \
80         unsigned char name##kfifo_buffer[size + sizeof(struct kfifo)]; \
81 }
82
83 /**
84  * INIT_KFIFO - Initialize a kfifo declared by DECLARE_KFIFO
85  * @name: name of the declared kfifo datatype
86  */
87 #define INIT_KFIFO(name) \
88         name = __kfifo_initializer(sizeof(name##kfifo_buffer) - \
89                                 sizeof(struct kfifo), name##kfifo_buffer)
90
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
95  *
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
100  */
101 #define DEFINE_KFIFO(name, size) \
102         unsigned char name##kfifo_buffer[size]; \
103         struct kfifo name = __kfifo_initializer(size, name##kfifo_buffer)
104
105 #undef __kfifo_initializer
106
107 extern void kfifo_init(struct kfifo *fifo, void *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 void *from, unsigned int len);
114 extern __must_check unsigned int kfifo_out(struct kfifo *fifo,
115                                 void *to, unsigned int len);
116
117 /**
118  * kfifo_reset - removes the entire FIFO contents
119  * @fifo: the fifo to be emptied.
120  */
121 static inline void kfifo_reset(struct kfifo *fifo)
122 {
123         fifo->in = fifo->out = 0;
124 }
125
126 /**
127  * kfifo_reset_out - skip FIFO contents
128  * @fifo: the fifo to be emptied.
129  */
130 static inline void kfifo_reset_out(struct kfifo *fifo)
131 {
132         smp_mb();
133         fifo->out = fifo->in;
134 }
135
136 /**
137  * kfifo_size - returns the size of the fifo in bytes
138  * @fifo: the fifo to be used.
139  */
140 static inline __must_check unsigned int kfifo_size(struct kfifo *fifo)
141 {
142         return fifo->size;
143 }
144
145 /**
146  * kfifo_len - returns the number of used bytes in the FIFO
147  * @fifo: the fifo to be used.
148  */
149 static inline unsigned int kfifo_len(struct kfifo *fifo)
150 {
151         register unsigned int   out;
152
153         out = fifo->out;
154         smp_rmb();
155         return fifo->in - out;
156 }
157
158 /**
159  * kfifo_is_empty - returns true if the fifo is empty
160  * @fifo: the fifo to be used.
161  */
162 static inline __must_check int kfifo_is_empty(struct kfifo *fifo)
163 {
164         return fifo->in == fifo->out;
165 }
166
167 /**
168  * kfifo_is_full - returns true if the fifo is full
169  * @fifo: the fifo to be used.
170  */
171 static inline __must_check int kfifo_is_full(struct kfifo *fifo)
172 {
173         return kfifo_len(fifo) == kfifo_size(fifo);
174 }
175
176 /**
177  * kfifo_avail - returns the number of bytes available in the FIFO
178  * @fifo: the fifo to be used.
179  */
180 static inline __must_check unsigned int kfifo_avail(struct kfifo *fifo)
181 {
182         return kfifo_size(fifo) - kfifo_len(fifo);
183 }
184
185 /**
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.
191  *
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.
195  */
196 static inline unsigned int kfifo_in_locked(struct kfifo *fifo,
197                 const void *from, unsigned int n, spinlock_t *lock)
198 {
199         unsigned long flags;
200         unsigned int ret;
201
202         spin_lock_irqsave(lock, flags);
203
204         ret = kfifo_in(fifo, from, n);
205
206         spin_unlock_irqrestore(lock, flags);
207
208         return ret;
209 }
210
211 /**
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.
217  *
218  * This function copies at most @len bytes from the FIFO into the
219  * @to buffer and returns the number of copied bytes.
220  */
221 static inline __must_check unsigned int kfifo_out_locked(struct kfifo *fifo,
222         void *to, unsigned int n, spinlock_t *lock)
223 {
224         unsigned long flags;
225         unsigned int ret;
226
227         spin_lock_irqsave(lock, flags);
228
229         ret = kfifo_out(fifo, to, n);
230
231         spin_unlock_irqrestore(lock, flags);
232
233         return ret;
234 }
235
236 extern void kfifo_skip(struct kfifo *fifo, unsigned int len);
237
238 extern __must_check unsigned int kfifo_from_user(struct kfifo *fifo,
239         const void __user *from, unsigned int n);
240
241 extern __must_check unsigned int kfifo_to_user(struct kfifo *fifo,
242         void __user *to, unsigned int n);
243
244 /*
245  * __kfifo_add_out internal helper function for updating the out offset
246  */
247 static inline void __kfifo_add_out(struct kfifo *fifo,
248                                 unsigned int off)
249 {
250         smp_mb();
251         fifo->out += off;
252 }
253
254 /*
255  * __kfifo_add_in internal helper function for updating the in offset
256  */
257 static inline void __kfifo_add_in(struct kfifo *fifo,
258                                 unsigned int off)
259 {
260         smp_wmb();
261         fifo->in += off;
262 }
263
264 /*
265  * __kfifo_off internal helper function for calculating the index of a
266  * given offeset
267  */
268 static inline unsigned int __kfifo_off(struct kfifo *fifo, unsigned int off)
269 {
270         return off & (fifo->size - 1);
271 }
272
273 /*
274  * __kfifo_peek_n internal helper function for determinate the length of
275  * the next record in the fifo
276  */
277 static inline unsigned int __kfifo_peek_n(struct kfifo *fifo,
278                                 unsigned int recsize)
279 {
280 #define __KFIFO_GET(fifo, off, shift) \
281         ((fifo)->buffer[__kfifo_off((fifo), (fifo)->out+(off))] << (shift))
282
283         unsigned int l;
284
285         l = __KFIFO_GET(fifo, 0, 0);
286
287         if (--recsize)
288                 l |= __KFIFO_GET(fifo, 1, 8);
289
290         return l;
291 #undef  __KFIFO_GET
292 }
293
294 /*
295  * __kfifo_poke_n internal helper function for storing the length of
296  * the next record into the fifo
297  */
298 static inline void __kfifo_poke_n(struct kfifo *fifo,
299                         unsigned int recsize, unsigned int n)
300 {
301 #define __KFIFO_PUT(fifo, off, val, shift) \
302                 ( \
303                 (fifo)->buffer[__kfifo_off((fifo), (fifo)->in+(off))] = \
304                 (unsigned char)((val) >> (shift)) \
305                 )
306
307         __KFIFO_PUT(fifo, 0, n, 0);
308
309         if (--recsize)
310                 __KFIFO_PUT(fifo, 1, n, 8);
311 #undef  __KFIFO_PUT
312 }
313
314 /*
315  * __kfifo_in_... internal functions for put date into the fifo
316  * do not call it directly, use kfifo_in_rec() instead
317  */
318 extern unsigned int __kfifo_in_n(struct kfifo *fifo,
319         const void *from, unsigned int n, unsigned int recsize);
320
321 extern unsigned int __kfifo_in_generic(struct kfifo *fifo,
322         const void *from, unsigned int n, unsigned int recsize);
323
324 static inline unsigned int __kfifo_in_rec(struct kfifo *fifo,
325         const void *from, unsigned int n, unsigned int recsize)
326 {
327         unsigned int ret;
328
329         ret = __kfifo_in_n(fifo, from, n, recsize);
330
331         if (likely(ret == 0)) {
332                 if (recsize)
333                         __kfifo_poke_n(fifo, recsize, n);
334                 __kfifo_add_in(fifo, n + recsize);
335         }
336         return ret;
337 }
338
339 /**
340  * kfifo_in_rec - puts some record data into the FIFO
341  * @fifo: the fifo to be used.
342  * @from: the data to be added.
343  * @n: the length of the data to be added.
344  * @recsize: size of record field
345  *
346  * This function copies @n bytes from the @from into the FIFO and returns
347  * the number of bytes which cannot be copied.
348  * A returned value greater than the @n value means that the record doesn't
349  * fit into the buffer.
350  *
351  * Note that with only one concurrent reader and one concurrent
352  * writer, you don't need extra locking to use these functions.
353  */
354 static inline __must_check unsigned int kfifo_in_rec(struct kfifo *fifo,
355         void *from, unsigned int n, unsigned int recsize)
356 {
357         if (!__builtin_constant_p(recsize))
358                 return __kfifo_in_generic(fifo, from, n, recsize);
359         return __kfifo_in_rec(fifo, from, n, recsize);
360 }
361
362 /*
363  * __kfifo_out_... internal functions for get date from the fifo
364  * do not call it directly, use kfifo_out_rec() instead
365  */
366 extern unsigned int __kfifo_out_n(struct kfifo *fifo,
367         void *to, unsigned int reclen, unsigned int recsize);
368
369 extern unsigned int __kfifo_out_generic(struct kfifo *fifo,
370         void *to, unsigned int n,
371         unsigned int recsize, unsigned int *total);
372
373 static inline unsigned int __kfifo_out_rec(struct kfifo *fifo,
374         void *to, unsigned int n, unsigned int recsize,
375         unsigned int *total)
376 {
377         unsigned int l;
378
379         if (!recsize) {
380                 l = n;
381                 if (total)
382                         *total = l;
383         } else {
384                 l = __kfifo_peek_n(fifo, recsize);
385                 if (total)
386                         *total = l;
387                 if (n < l)
388                         return l;
389         }
390
391         return __kfifo_out_n(fifo, to, l, recsize);
392 }
393
394 /**
395  * kfifo_out_rec - gets some record data from the FIFO
396  * @fifo: the fifo to be used.
397  * @to: where the data must be copied.
398  * @n: the size of the destination buffer.
399  * @recsize: size of record field
400  * @total: pointer where the total number of to copied bytes should stored
401  *
402  * This function copies at most @n bytes from the FIFO to @to and returns the
403  * number of bytes which cannot be copied.
404  * A returned value greater than the @n value means that the record doesn't
405  * fit into the @to buffer.
406  *
407  * Note that with only one concurrent reader and one concurrent
408  * writer, you don't need extra locking to use these functions.
409  */
410 static inline __must_check unsigned int kfifo_out_rec(struct kfifo *fifo,
411         void *to, unsigned int n, unsigned int recsize,
412         unsigned int *total)
413
414 {
415         if (!__builtin_constant_p(recsize))
416                 return __kfifo_out_generic(fifo, to, n, recsize, total);
417         return __kfifo_out_rec(fifo, to, n, recsize, total);
418 }
419
420 /*
421  * __kfifo_from_user_... internal functions for transfer from user space into
422  * the fifo. do not call it directly, use kfifo_from_user_rec() instead
423  */
424 extern unsigned int __kfifo_from_user_n(struct kfifo *fifo,
425         const void __user *from, unsigned int n, unsigned int recsize);
426
427 extern unsigned int __kfifo_from_user_generic(struct kfifo *fifo,
428         const void __user *from, unsigned int n, unsigned int recsize);
429
430 static inline unsigned int __kfifo_from_user_rec(struct kfifo *fifo,
431         const void __user *from, unsigned int n, unsigned int recsize)
432 {
433         unsigned int ret;
434
435         ret = __kfifo_from_user_n(fifo, from, n, recsize);
436
437         if (likely(ret == 0)) {
438                 if (recsize)
439                         __kfifo_poke_n(fifo, recsize, n);
440                 __kfifo_add_in(fifo, n + recsize);
441         }
442         return ret;
443 }
444
445 /**
446  * kfifo_from_user_rec - puts some data from user space into the FIFO
447  * @fifo: the fifo to be used.
448  * @from: pointer to the data to be added.
449  * @n: the length of the data to be added.
450  * @recsize: size of record field
451  *
452  * This function copies @n bytes from the @from into the
453  * FIFO and returns the number of bytes which cannot be copied.
454  *
455  * If the returned value is equal or less the @n value, the copy_from_user()
456  * functions has failed. Otherwise the record doesn't fit into the buffer.
457  *
458  * Note that with only one concurrent reader and one concurrent
459  * writer, you don't need extra locking to use these functions.
460  */
461 static inline __must_check unsigned int kfifo_from_user_rec(struct kfifo *fifo,
462         const void __user *from, unsigned int n, unsigned int recsize)
463 {
464         if (!__builtin_constant_p(recsize))
465                 return __kfifo_from_user_generic(fifo, from, n, recsize);
466         return __kfifo_from_user_rec(fifo, from, n, recsize);
467 }
468
469 /*
470  * __kfifo_to_user_... internal functions for transfer fifo data into user space
471  * do not call it directly, use kfifo_to_user_rec() instead
472  */
473 extern unsigned int __kfifo_to_user_n(struct kfifo *fifo,
474         void __user *to, unsigned int n, unsigned int reclen,
475         unsigned int recsize);
476
477 extern unsigned int __kfifo_to_user_generic(struct kfifo *fifo,
478         void __user *to, unsigned int n, unsigned int recsize,
479         unsigned int *total);
480
481 static inline unsigned int __kfifo_to_user_rec(struct kfifo *fifo,
482         void __user *to, unsigned int n,
483         unsigned int recsize, unsigned int *total)
484 {
485         unsigned int l;
486
487         if (!recsize) {
488                 l = n;
489                 if (total)
490                         *total = l;
491         } else {
492                 l = __kfifo_peek_n(fifo, recsize);
493                 if (total)
494                         *total = l;
495                 if (n < l)
496                         return l;
497         }
498
499         return __kfifo_to_user_n(fifo, to, n, l, recsize);
500 }
501
502 /**
503  * kfifo_to_user_rec - gets data from the FIFO and write it to user space
504  * @fifo: the fifo to be used.
505  * @to: where the data must be copied.
506  * @n: the size of the destination buffer.
507  * @recsize: size of record field
508  * @total: pointer where the total number of to copied bytes should stored
509  *
510  * This function copies at most @n bytes from the FIFO to the @to.
511  * In case of an error, the function returns the number of bytes which cannot
512  * be copied.
513  * If the returned value is equal or less the @n value, the copy_to_user()
514  * functions has failed. Otherwise the record doesn't fit into the @to buffer.
515  *
516  * Note that with only one concurrent reader and one concurrent
517  * writer, you don't need extra locking to use these functions.
518  */
519 static inline __must_check unsigned int kfifo_to_user_rec(struct kfifo *fifo,
520                 void __user *to, unsigned int n, unsigned int recsize,
521                 unsigned int *total)
522 {
523         if (!__builtin_constant_p(recsize))
524                 return __kfifo_to_user_generic(fifo, to, n, recsize, total);
525         return __kfifo_to_user_rec(fifo, to, n, recsize, total);
526 }
527
528 /*
529  * __kfifo_peek_... internal functions for peek into the next fifo record
530  * do not call it directly, use kfifo_peek_rec() instead
531  */
532 extern unsigned int __kfifo_peek_generic(struct kfifo *fifo,
533                                 unsigned int recsize);
534
535 /**
536  * kfifo_peek_rec - gets the size of the next FIFO record data
537  * @fifo: the fifo to be used.
538  * @recsize: size of record field
539  *
540  * This function returns the size of the next FIFO record in number of bytes
541  */
542 static inline __must_check unsigned int kfifo_peek_rec(struct kfifo *fifo,
543         unsigned int recsize)
544 {
545         if (!__builtin_constant_p(recsize))
546                 return __kfifo_peek_generic(fifo, recsize);
547         if (!recsize)
548                 return kfifo_len(fifo);
549         return __kfifo_peek_n(fifo, recsize);
550 }
551
552 /*
553  * __kfifo_skip_... internal functions for skip the next fifo record
554  * do not call it directly, use kfifo_skip_rec() instead
555  */
556 extern void __kfifo_skip_generic(struct kfifo *fifo, unsigned int recsize);
557
558 static inline void __kfifo_skip_rec(struct kfifo *fifo,
559         unsigned int recsize)
560 {
561         unsigned int l;
562
563         if (recsize) {
564                 l = __kfifo_peek_n(fifo, recsize);
565
566                 if (l + recsize <= kfifo_len(fifo)) {
567                         __kfifo_add_out(fifo, l + recsize);
568                         return;
569                 }
570         }
571         kfifo_reset_out(fifo);
572 }
573
574 /**
575  * kfifo_skip_rec - skip the next fifo out record
576  * @fifo: the fifo to be used.
577  * @recsize: size of record field
578  *
579  * This function skips the next FIFO record
580  */
581 static inline void kfifo_skip_rec(struct kfifo *fifo,
582         unsigned int recsize)
583 {
584         if (!__builtin_constant_p(recsize))
585                 __kfifo_skip_generic(fifo, recsize);
586         else
587                 __kfifo_skip_rec(fifo, recsize);
588 }
589
590 /**
591  * kfifo_avail_rec - returns the number of bytes available in a record FIFO
592  * @fifo: the fifo to be used.
593  * @recsize: size of record field
594  */
595 static inline __must_check unsigned int kfifo_avail_rec(struct kfifo *fifo,
596         unsigned int recsize)
597 {
598         unsigned int l = kfifo_size(fifo) - kfifo_len(fifo);
599
600         return (l > recsize) ? l - recsize : 0;
601 }
602
603 #endif