1 /*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 *
21 * Copyright (c) 2002-2006 Neterion, Inc.
22 */
23
24 #ifndef XGE_QUEUE_H
25 #define XGE_QUEUE_H
26
27 #include "xge-os-pal.h"
28 #include "xge-defs.h"
29 #include "xge-list.h"
30 #include "xgehal-event.h"
31
32 __EXTERN_BEGIN_DECLS
33
34 #define XGE_QUEUE_BUF_SIZE 0x1000
35 #define XGE_DEFAULT_EVENT_MAX_DATA_SIZE 16
36
37 /**
38 * enum xge_queue_status_e - Enumerates return codes of the xge_queue
39 * manipulation APIs.
40 * @XGE_QUEUE_IS_FULL: Queue is full, need to grow.
41 * @XGE_QUEUE_IS_EMPTY: Queue is empty.
42 * @XGE_QUEUE_OUT_OF_MEMORY: Out of memory.
43 * @XGE_QUEUE_NOT_ENOUGH_SPACE: Exceeded specified event size,
44 * see xge_queue_consume().
45 * @XGE_QUEUE_OK: Neither one of the codes listed above.
46 *
47 * Enumerates return codes of xge_queue_consume()
48 * and xge_queue_produce() APIs.
49 */
50 typedef enum xge_queue_status_e {
51 XGE_QUEUE_OK = 0,
52 XGE_QUEUE_IS_FULL = 1,
53 XGE_QUEUE_IS_EMPTY = 2,
54 XGE_QUEUE_OUT_OF_MEMORY = 3,
55 XGE_QUEUE_NOT_ENOUGH_SPACE = 4
56 } xge_queue_status_e;
57
58 typedef void* xge_queue_h;
59
60 /**
61 * struct xge_queue_item_t - Queue item.
62 * @item: List item. Note that the queue is "built" on top of
63 * the bi-directional linked list.
64 * @event_type: Event type. Includes (but is not restricted to)
65 * one of the xge_hal_event_e{} enumerated types.
66 * @data_size: Size of the enqueued user data. Note that xge_queue_t
67 * items are allowed to have variable sizes.
68 * @is_critical: For critical events, e.g. ECC.
69 * @context: Opaque (void*) "context", for instance event producer object.
70 *
71 * Item of the xge_queue_t{}. The queue is protected
72 * in terms of multi-threaded concurrent access.
73 * See also: xge_queue_t{}.
74 */
75 typedef struct xge_queue_item_t {
76 xge_list_t item;
77 xge_hal_event_e event_type;
78 int data_size;
79 int is_critical;
80 void *context;
81 } xge_queue_item_t;
82
83 /**
84 * function xge_queued_f - Item-enqueued callback.
85 * @data: Per-queue context independent of the event. E.g., device handle.
86 * @event_type: HAL or ULD-defined event type. Note that HAL own
87 * events are enumerated by xge_hal_event_e{}.
88 *
89 * Per-queue optional callback. If not NULL, called by HAL each
90 * time an event gets added to the queue.
91 */
92 typedef void (*xge_queued_f) (void *data, int event_type);
93
94 /**
95 * struct xge_queue_t - Protected dynamic queue of variable-size items.
96 * @start_ptr: Points to the start of the queue.
97 * @end_ptr: Points to the end of the queue.
98 * @head_ptr: Points to the head of the queue. It gets changed during queue
99 * produce/consume operations.
100 * @tail_ptr: Points to the tail of the queue. It gets changed during queue
101 * produce/consume operations.
102 * @lock: Lock for queue operations(syncronization purpose).
103 * @pages_initial:Number of pages to be initially allocated at the time
104 * of queue creation.
105 * @pages_max: Max number of pages that can be allocated in the queue.
106 * @pages_current: Number of pages currently allocated
107 * @list_head: Points to the list of queue elements that are produced, but yet
108 * to be consumed.
109 * @signal_callback: (TODO)
110 * @pdev: PCI device handle
111 * @irqh: PCI device IRQ handle.
112 * @queued_func: Optional callback function to be called each time a new
113 * item is added to the queue.
114 * @queued_data: Arguments to the callback function.
115 * @has_critical_event: Non-zero, if the queue contains a critical event,
116 * see xge_hal_event_e{}.
117 * Protected dynamically growing queue. The queue is used to support multiple
118 * producer/consumer type scenarios. The queue is a strict FIFO: first come
119 * first served.
120 * Queue users may "produce" (see xge_queue_produce()) and "consume"
121 * (see xge_queue_consume()) items (a.k.a. events) variable sizes.
122 * See also: xge_queue_item_t{}.
123 */
124 typedef struct xge_queue_t {
125 void *start_ptr;
126 void *end_ptr;
127 void *head_ptr;
128 void *tail_ptr;
129 spinlock_t lock;
130 unsigned int pages_initial;
131 unsigned int pages_max;
132 unsigned int pages_current;
133 xge_list_t list_head;
134 pci_dev_h pdev;
135 pci_irq_h irqh;
136 xge_queued_f queued_func;
137 void *queued_data;
138 int has_critical_event;
139 } xge_queue_t;
140
141 /* ========================== PUBLIC API ================================= */
142
143 xge_queue_h xge_queue_create(pci_dev_h pdev, pci_irq_h irqh, int pages_initial,
144 int pages_max, xge_queued_f queued_func, void *queued_data);
145
146 void xge_queue_destroy(xge_queue_h queueh);
147
148 void* xge_queue_item_data(xge_queue_item_t *item);
149
150 xge_queue_status_e
151 xge_queue_produce(xge_queue_h queueh, int event_type, void *context,
152 int is_critical, const int data_size, void *data);
153
154 static inline xge_queue_status_e
xge_queue_produce_context(xge_queue_h queueh,int event_type,void * context)155 xge_queue_produce_context(xge_queue_h queueh, int event_type, void *context) {
156 return xge_queue_produce(queueh, event_type, context, 0, 0, 0);
157 }
158
159 xge_queue_status_e xge_queue_consume(xge_queue_h queueh, int data_max_size,
160 xge_queue_item_t *item);
161
162 void xge_queue_flush(xge_queue_h queueh);
163
164 /* ========================== PRIVATE API ================================= */
165
166 xge_queue_status_e __io_queue_grow(xge_queue_h qh);
167
168 int __queue_get_reset_critical (xge_queue_h qh);
169
170 __EXTERN_END_DECLS
171
172 #endif /* XGE_QUEUE_H */
173