sys/dev/nxge/include/xge-queue.h

   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$
  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  */
  63 typedef 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
  71 typedef 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  */
  88 typedef 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  */
 105 typedef 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  */
 137 typedef 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
 156 xge_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
 159 void xge_queue_destroy(xge_queue_h queueh);
 160
 161 void* xge_queue_item_data(xge_queue_item_t *item);
 162
 163 xge_queue_status_e
 164 xge_queue_produce(xge_queue_h queueh, int event_type, void *context,
 165                 int is_critical, const int data_size, void *data);
 166
 167 static inline xge_queue_status_e
 168 xge_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
 172 xge_queue_status_e xge_queue_consume(xge_queue_h queueh, int data_max_size,
 173                 xge_queue_item_t *item);
 174
 175 void xge_queue_flush(xge_queue_h queueh);
 176
 177 /* ========================== PRIVATE API ================================= */
 178
 179 xge_queue_status_e __io_queue_grow(xge_queue_h qh);
 180
 181 int __queue_get_reset_critical (xge_queue_h qh);
 182
 183 __EXTERN_END_DECLS
 184
 185 #endif /* XGE_QUEUE_H */