xge-queue.h revision 171095
1/*- 2 * Copyright (c) 2002-2007 Neterion, Inc. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24 * SUCH DAMAGE. 25 * 26 * $FreeBSD: head/sys/dev/nxge/include/xge-queue.h 171095 2007-06-29 22:47:18Z sam $ 27 */ 28 29/* 30 * FileName : xge-queue.h 31 * 32 * Description: serialized event queue 33 * 34 * Created: 7 June 2004 35 */ 36 37#ifndef XGE_QUEUE_H 38#define XGE_QUEUE_H 39 40#include <dev/nxge/include/xge-os-pal.h> 41#include <dev/nxge/include/xge-defs.h> 42#include <dev/nxge/include/xge-list.h> 43#include <dev/nxge/include/xgehal-event.h> 44 45__EXTERN_BEGIN_DECLS 46 47#define XGE_QUEUE_BUF_SIZE 0x1000 48#define XGE_DEFAULT_EVENT_MAX_DATA_SIZE 16 49 50/** 51 * enum xge_queue_status_e - Enumerates return codes of the xge_queue 52 * manipulation APIs. 53 * @XGE_QUEUE_IS_FULL: Queue is full, need to grow. 54 * @XGE_QUEUE_IS_EMPTY: Queue is empty. 55 * @XGE_QUEUE_OUT_OF_MEMORY: Out of memory. 56 * @XGE_QUEUE_NOT_ENOUGH_SPACE: Exceeded specified event size, 57 * see xge_queue_consume(). 58 * @XGE_QUEUE_OK: Neither one of the codes listed above. 59 * 60 * Enumerates return codes of xge_queue_consume() 61 * and xge_queue_produce() APIs. 62 */ 63typedef enum xge_queue_status_e { 64 XGE_QUEUE_OK = 0, 65 XGE_QUEUE_IS_FULL = 1, 66 XGE_QUEUE_IS_EMPTY = 2, 67 XGE_QUEUE_OUT_OF_MEMORY = 3, 68 XGE_QUEUE_NOT_ENOUGH_SPACE = 4 69} xge_queue_status_e; 70 71typedef void* xge_queue_h; 72 73/** 74 * struct xge_queue_item_t - Queue item. 75 * @item: List item. Note that the queue is "built" on top of 76 * the bi-directional linked list. 77 * @event_type: Event type. Includes (but is not restricted to) 78 * one of the xge_hal_event_e{} enumerated types. 79 * @data_size: Size of the enqueued user data. Note that xge_queue_t 80 * items are allowed to have variable sizes. 81 * @is_critical: For critical events, e.g. ECC. 82 * @context: Opaque (void*) "context", for instance event producer object. 83 * 84 * Item of the xge_queue_t{}. The queue is protected 85 * in terms of multi-threaded concurrent access. 86 * See also: xge_queue_t{}. 87 */ 88typedef struct xge_queue_item_t { 89 xge_list_t item; 90 xge_hal_event_e event_type; 91 int data_size; 92 int is_critical; 93 void *context; 94} xge_queue_item_t; 95 96/** 97 * function xge_queued_f - Item-enqueued callback. 98 * @data: Per-queue context independent of the event. E.g., device handle. 99 * @event_type: HAL or ULD-defined event type. Note that HAL own 100 * events are enumerated by xge_hal_event_e{}. 101 * 102 * Per-queue optional callback. If not NULL, called by HAL each 103 * time an event gets added to the queue. 104 */ 105typedef void (*xge_queued_f) (void *data, int event_type); 106 107/** 108 * struct xge_queue_t - Protected dynamic queue of variable-size items. 109 * @start_ptr: Points to the start of the queue. 110 * @end_ptr: Points to the end of the queue. 111 * @head_ptr: Points to the head of the queue. It gets changed during queue 112 * produce/consume operations. 113 * @tail_ptr: Points to the tail of the queue. It gets changed during queue 114 * produce/consume operations. 115 * @lock: Lock for queue operations(syncronization purpose). 116 * @pages_initial:Number of pages to be initially allocated at the time 117 * of queue creation. 118 * @pages_max: Max number of pages that can be allocated in the queue. 119 * @pages_current: Number of pages currently allocated 120 * @list_head: Points to the list of queue elements that are produced, but yet 121 * to be consumed. 122 * @signal_callback: (TODO) 123 * @pdev: PCI device handle 124 * @irqh: PCI device IRQ handle. 125 * @queued_func: Optional callback function to be called each time a new 126 * item is added to the queue. 127 * @queued_data: Arguments to the callback function. 128 * @has_critical_event: Non-zero, if the queue contains a critical event, 129 * see xge_hal_event_e{}. 130 * Protected dynamically growing queue. The queue is used to support multiple 131 * producer/consumer type scenarios. The queue is a strict FIFO: first come 132 * first served. 133 * Queue users may "produce" (see xge_queue_produce()) and "consume" 134 * (see xge_queue_consume()) items (a.k.a. events) variable sizes. 135 * See also: xge_queue_item_t{}. 136 */ 137typedef struct xge_queue_t { 138 void *start_ptr; 139 void *end_ptr; 140 void *head_ptr; 141 void *tail_ptr; 142 spinlock_t lock; 143 unsigned int pages_initial; 144 unsigned int pages_max; 145 unsigned int pages_current; 146 xge_list_t list_head; 147 pci_dev_h pdev; 148 pci_irq_h irqh; 149 xge_queued_f queued_func; 150 void *queued_data; 151 int has_critical_event; 152} xge_queue_t; 153 154/* ========================== PUBLIC API ================================= */ 155 156xge_queue_h xge_queue_create(pci_dev_h pdev, pci_irq_h irqh, int pages_initial, 157 int pages_max, xge_queued_f queued_func, void *queued_data); 158 159void xge_queue_destroy(xge_queue_h queueh); 160 161void* xge_queue_item_data(xge_queue_item_t *item); 162 163xge_queue_status_e 164xge_queue_produce(xge_queue_h queueh, int event_type, void *context, 165 int is_critical, const int data_size, void *data); 166 167static inline xge_queue_status_e 168xge_queue_produce_context(xge_queue_h queueh, int event_type, void *context) { 169 return xge_queue_produce(queueh, event_type, context, 0, 0, 0); 170} 171 172xge_queue_status_e xge_queue_consume(xge_queue_h queueh, int data_max_size, 173 xge_queue_item_t *item); 174 175void xge_queue_flush(xge_queue_h queueh); 176 177/* ========================== PRIVATE API ================================= */ 178 179xge_queue_status_e __io_queue_grow(xge_queue_h qh); 180 181int __queue_get_reset_critical (xge_queue_h qh); 182 183__EXTERN_END_DECLS 184 185#endif /* XGE_QUEUE_H */ 186