linux/drivers/infiniband/sw/rxe/rxe_queue.h

/* SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB */
/*
 * Copyright (c) 2016 Mellanox Technologies Ltd. All rights reserved.
 * Copyright (c) 2015 System Fabric Works, Inc. All rights reserved.
 */

#ifndef RXE_QUEUE_H
#define RXE_QUEUE_H

/* Implements a simple circular buffer that is shared between user
 * and the driver and can be resized. The requested element size is
 * rounded up to a power of 2 and the number of elements in the buffer
 * is also rounded up to a power of 2. Since the queue is empty when
 * the producer and consumer indices match the maximum capacity of the
 * queue is one less than the number of element slots.
 *
 * Notes:
 *   - The driver indices are always masked off to q->index_mask
 *     before storing so do not need to be checked on reads.
 *   - The user whether user space or kernel is generally
 *     not trusted so its parameters are masked to make sure
 *     they do not access the queue out of bounds on reads.
 *   - The driver indices for queues must not be written
 *     by user so a local copy is used and a shared copy is
 *     stored when the local copy is changed.
 *   - By passing the type in the parameter list separate from q
 *     the compiler can eliminate the switch statement when the
 *     actual queue type is known when the function is called at
 *     compile time.
 *   - These queues are lock free. The user and driver must protect
 *     changes to their end of the queues with locks if more than one
 *     CPU can be accessing it at the same time.
 */

/**
 * enum queue_type - type of queue
 * @QUEUE_TYPE_TO_CLIENT:	Queue is written by rxe driver and
 *				read by client which may be a user space
 *				application or a kernel ulp.
 *				Used by rxe internals only.
 * @QUEUE_TYPE_FROM_CLIENT:	Queue is written by client and
 *				read by rxe driver.
 *				Used by rxe internals only.
 * @QUEUE_TYPE_FROM_ULP:	Queue is written by kernel ulp and
 *				read by rxe driver.
 *				Used by kernel verbs APIs only on
 *				behalf of ulps.
 * @QUEUE_TYPE_TO_ULP:		Queue is written by rxe driver and
 *				read by kernel ulp.
 *				Used by kernel verbs APIs only on
 *				behalf of ulps.
 */
enum queue_type { … };

struct rxe_queue_buf;

struct rxe_queue { … };

int do_mmap_info(struct rxe_dev *rxe, struct mminfo __user *outbuf,
		 struct ib_udata *udata, struct rxe_queue_buf *buf,
		 size_t buf_size, struct rxe_mmap_info **ip_p);

void rxe_queue_reset(struct rxe_queue *q);

struct rxe_queue *rxe_queue_init(struct rxe_dev *rxe, int *num_elem,
			unsigned int elem_size, enum queue_type type);

int rxe_queue_resize(struct rxe_queue *q, unsigned int *num_elem_p,
		     unsigned int elem_size, struct ib_udata *udata,
		     struct mminfo __user *outbuf,
		     spinlock_t *producer_lock, spinlock_t *consumer_lock);

void rxe_queue_cleanup(struct rxe_queue *queue);

static inline u32 queue_next_index(struct rxe_queue *q, int index)
{ … }

static inline u32 queue_get_producer(const struct rxe_queue *q,
				     enum queue_type type)
{ … }

static inline u32 queue_get_consumer(const struct rxe_queue *q,
				     enum queue_type type)
{ … }

static inline int queue_empty(struct rxe_queue *q, enum queue_type type)
{ … }

static inline int queue_full(struct rxe_queue *q, enum queue_type type)
{ … }

static inline u32 queue_count(const struct rxe_queue *q,
					enum queue_type type)
{ … }

static inline void queue_advance_producer(struct rxe_queue *q,
					  enum queue_type type)
{ … }

static inline void queue_advance_consumer(struct rxe_queue *q,
					  enum queue_type type)
{ … }

static inline void *queue_producer_addr(struct rxe_queue *q,
					enum queue_type type)
{ … }

static inline void *queue_consumer_addr(struct rxe_queue *q,
					enum queue_type type)
{ … }

static inline void *queue_addr_from_index(struct rxe_queue *q, u32 index)
{ … }

static inline u32 queue_index_from_addr(const struct rxe_queue *q,
				const void *addr)
{ … }

static inline void *queue_head(struct rxe_queue *q, enum queue_type type)
{ … }

#endif /* RXE_QUEUE_H */