/* SPDX-License-Identifier: GPL-2.0-or-later */ /* * Definitions for the 'struct ptr_ring' datastructure. * * Author: * Michael S. Tsirkin <[email protected]> * * Copyright (C) 2016 Red Hat, Inc. * * This is a limited-size FIFO maintaining pointers in FIFO order, with * one CPU producing entries and another consuming entries from a FIFO. * * This implementation tries to minimize cache-contention when there is a * single producer and a single consumer CPU. */ #ifndef _LINUX_PTR_RING_H #define _LINUX_PTR_RING_H … #ifdef __KERNEL__ #include <linux/spinlock.h> #include <linux/cache.h> #include <linux/types.h> #include <linux/compiler.h> #include <linux/slab.h> #include <linux/mm.h> #include <asm/errno.h> #endif struct ptr_ring { … }; /* Note: callers invoking this in a loop must use a compiler barrier, * for example cpu_relax(). * * NB: this is unlike __ptr_ring_empty in that callers must hold producer_lock: * see e.g. ptr_ring_full. */ static inline bool __ptr_ring_full(struct ptr_ring *r) { … } static inline bool ptr_ring_full(struct ptr_ring *r) { … } static inline bool ptr_ring_full_irq(struct ptr_ring *r) { … } static inline bool ptr_ring_full_any(struct ptr_ring *r) { … } static inline bool ptr_ring_full_bh(struct ptr_ring *r) { … } /* Note: callers invoking this in a loop must use a compiler barrier, * for example cpu_relax(). Callers must hold producer_lock. * Callers are responsible for making sure pointer that is being queued * points to a valid data. */ static inline int __ptr_ring_produce(struct ptr_ring *r, void *ptr) { … } /* * Note: resize (below) nests producer lock within consumer lock, so if you * consume in interrupt or BH context, you must disable interrupts/BH when * calling this. */ static inline int ptr_ring_produce(struct ptr_ring *r, void *ptr) { … } static inline int ptr_ring_produce_irq(struct ptr_ring *r, void *ptr) { … } static inline int ptr_ring_produce_any(struct ptr_ring *r, void *ptr) { … } static inline int ptr_ring_produce_bh(struct ptr_ring *r, void *ptr) { … } static inline void *__ptr_ring_peek(struct ptr_ring *r) { … } /* * Test ring empty status without taking any locks. * * NB: This is only safe to call if ring is never resized. * * However, if some other CPU consumes ring entries at the same time, the value * returned is not guaranteed to be correct. * * In this case - to avoid incorrectly detecting the ring * as empty - the CPU consuming the ring entries is responsible * for either consuming all ring entries until the ring is empty, * or synchronizing with some other CPU and causing it to * re-test __ptr_ring_empty and/or consume the ring enteries * after the synchronization point. * * Note: callers invoking this in a loop must use a compiler barrier, * for example cpu_relax(). */ static inline bool __ptr_ring_empty(struct ptr_ring *r) { … } static inline bool ptr_ring_empty(struct ptr_ring *r) { … } static inline bool ptr_ring_empty_irq(struct ptr_ring *r) { … } static inline bool ptr_ring_empty_any(struct ptr_ring *r) { … } static inline bool ptr_ring_empty_bh(struct ptr_ring *r) { … } /* Must only be called after __ptr_ring_peek returned !NULL */ static inline void __ptr_ring_discard_one(struct ptr_ring *r) { … } static inline void *__ptr_ring_consume(struct ptr_ring *r) { … } static inline int __ptr_ring_consume_batched(struct ptr_ring *r, void **array, int n) { … } /* * Note: resize (below) nests producer lock within consumer lock, so if you * call this in interrupt or BH context, you must disable interrupts/BH when * producing. */ static inline void *ptr_ring_consume(struct ptr_ring *r) { … } static inline void *ptr_ring_consume_irq(struct ptr_ring *r) { … } static inline void *ptr_ring_consume_any(struct ptr_ring *r) { … } static inline void *ptr_ring_consume_bh(struct ptr_ring *r) { … } static inline int ptr_ring_consume_batched(struct ptr_ring *r, void **array, int n) { … } static inline int ptr_ring_consume_batched_irq(struct ptr_ring *r, void **array, int n) { … } static inline int ptr_ring_consume_batched_any(struct ptr_ring *r, void **array, int n) { … } static inline int ptr_ring_consume_batched_bh(struct ptr_ring *r, void **array, int n) { … } /* Cast to structure type and call a function without discarding from FIFO. * Function must return a value. * Callers must take consumer_lock. */ #define __PTR_RING_PEEK_CALL(r, f) … #define PTR_RING_PEEK_CALL(r, f) … #define PTR_RING_PEEK_CALL_IRQ(r, f) … #define PTR_RING_PEEK_CALL_BH(r, f) … #define PTR_RING_PEEK_CALL_ANY(r, f) … /* Not all gfp_t flags (besides GFP_KERNEL) are allowed. See * documentation for vmalloc for which of them are legal. */ static inline void **__ptr_ring_init_queue_alloc_noprof(unsigned int size, gfp_t gfp) { … } static inline void __ptr_ring_set_size(struct ptr_ring *r, int size) { … } static inline int ptr_ring_init_noprof(struct ptr_ring *r, int size, gfp_t gfp) { … } #define ptr_ring_init(...) … /* * Return entries into ring. Destroy entries that don't fit. * * Note: this is expected to be a rare slow path operation. * * Note: producer lock is nested within consumer lock, so if you * resize you must make sure all uses nest correctly. * In particular if you consume ring in interrupt or BH context, you must * disable interrupts/BH when doing so. */ static inline void ptr_ring_unconsume(struct ptr_ring *r, void **batch, int n, void (*destroy)(void *)) { … } static inline void **__ptr_ring_swap_queue(struct ptr_ring *r, void **queue, int size, gfp_t gfp, void (*destroy)(void *)) { … } /* * Note: producer lock is nested within consumer lock, so if you * resize you must make sure all uses nest correctly. * In particular if you consume ring in interrupt or BH context, you must * disable interrupts/BH when doing so. */ static inline int ptr_ring_resize_noprof(struct ptr_ring *r, int size, gfp_t gfp, void (*destroy)(void *)) { … } #define ptr_ring_resize(...) … /* * Note: producer lock is nested within consumer lock, so if you * resize you must make sure all uses nest correctly. * In particular if you consume ring in interrupt or BH context, you must * disable interrupts/BH when doing so. */ static inline int ptr_ring_resize_multiple_noprof(struct ptr_ring **rings, unsigned int nrings, int size, gfp_t gfp, void (*destroy)(void *)) { … } #define ptr_ring_resize_multiple(...) … static inline void ptr_ring_cleanup(struct ptr_ring *r, void (*destroy)(void *)) { … } #endif /* _LINUX_PTR_RING_H */
Codebase Browser
linux