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_HAL_DRIVER_H 25 #define XGE_HAL_DRIVER_H 26 27 #include "xge-os-pal.h" 28 #include "xge-list.h" 29 #include "xge-queue.h" 30 #include "xgehal-types.h" 31 #include "xgehal-config.h" 32 #include "xgehal-event.h" 33 34 __EXTERN_BEGIN_DECLS 35 36 /* maximum number of events consumed in a syncle poll() cycle */ 37 #define XGE_HAL_DRIVER_QUEUE_CONSUME_MAX 5 38 39 40 /** 41 * function xge_uld_sched_timer_cb_f - Per-device periodic timer 42 * callback. 43 * @devh: HAL device handle. 44 * @userdata: Per-device user data (a.k.a. context) specified via 45 * xge_hal_device_initialize(). 46 * 47 * Periodic or one-shot timer callback. If specified (that is, not NULL) 48 * HAL invokes this callback periodically. The call is performed in the 49 * interrupt context, or more exactly, in the context of HAL's ISR 50 * xge_hal_device_continue_irq(). 51 * 52 * See also: xge_hal_device_initialize{} 53 */ 54 typedef void (*xge_uld_sched_timer_cb_f)(xge_hal_device_h devh, void *userdata); 55 56 /** 57 * function xge_uld_link_up_f - Link-Up callback provided by upper-layer 58 * driver. 59 * @userdata: Opaque context set by the ULD via 60 * xge_hal_device_private_set() 61 * (typically - at HAL device iinitialization time). 62 * 63 * Link-up notification callback provided by the ULD. 64 * This is one of the per-driver callbacks, see xge_hal_uld_cbs_t{}. 65 * 66 * See also: xge_hal_uld_cbs_t{}, xge_uld_link_down_f{}, 67 * xge_hal_driver_initialize(), xge_hal_device_private_set(). 68 */ 69 typedef void (*xge_uld_link_up_f) (void *userdata); 70 71 /** 72 * function xge_uld_link_down_f - Link-Down callback provided by 73 * upper-layer driver. 74 * @userdata: Opaque context set by the ULD via 75 * xge_hal_device_private_set() 76 * (typically - at HAL device iinitialization time). 77 * 78 * Link-Down notification callback provided by the upper-layer driver. 79 * This is one of the per-driver callbacks, see xge_hal_uld_cbs_t{}. 80 * 81 * See also: xge_hal_uld_cbs_t{}, xge_uld_link_up_f{}, 82 * xge_hal_driver_initialize(), xge_hal_device_private_set(). 83 */ 84 typedef void (*xge_uld_link_down_f) (void *userdata); 85 86 /** 87 * function xge_uld_crit_err_f - Critical Error notification callback. 88 * @userdata: Opaque context set by the ULD via 89 * xge_hal_device_private_set() 90 * (typically - at HAL device iinitialization time). 91 * @type: Enumerated hw error, e.g.: double ECC. 92 * @serr_data: Xframe status. 93 * @ext_data: Extended data. The contents depends on the @type. 94 * 95 * Link-Down notification callback provided by the upper-layer driver. 96 * This is one of the per-driver callbacks, see xge_hal_uld_cbs_t{}. 97 * 98 * See also: xge_hal_uld_cbs_t{}, xge_hal_event_e{}, 99 * xge_hal_device_private_set(), xge_hal_driver_initialize(). 100 */ 101 typedef void (*xge_uld_crit_err_f) (void *userdata, xge_hal_event_e type, 102 u64 ext_data); 103 104 /** 105 * function xge_uld_event_queued_f - Event-enqueued notification 106 * callback. 107 * @devh: HAL device handle. 108 * @event_type: HAL- or ULD-defined event type. Note that HAL 109 * events are enumerated by xge_hal_event_e{}. 110 * 111 * "Event-was-enqueued" notification callback provided by the upper-layer 112 * driver. The callback is invoked (if defined, i.e., not NULL in the 113 * xge_hal_uld_cbs_t{} structure) each time immediately after an event 114 * is enqueued. 115 * 116 * See also: xge_hal_uld_cbs_t{}, xge_hal_device_private_set(), 117 * xge_hal_driver_initialize(). 118 */ 119 typedef void (*xge_uld_event_queued_f) (xge_hal_device_h devh, int event_type); 120 121 /** 122 * function xge_uld_event_f - ULD event callback. 123 * @item: ULD-defined event, item of the xge_queue_t. 124 * 125 * ULD event callback. 126 * Upper-layer driver can use HAL queue to serialize certain slow-path 127 * events. HAL periodically polls the queue as part of the 128 * xge_hal_device_poll() processing. When/if HAL discovers in the queue 129 * an unkown event type it simply invokes the event callback 130 * (which must be non-NULL and supplied by the ULD in this case). 131 * 132 * See also: xge_hal_uld_cbs_t{}, xge_hal_device_poll(), xge_queue_t{}, 133 * xge_hal_driver_initialize(), xge_queue_item_t{}. 134 */ 135 typedef void (*xge_uld_event_f) (xge_queue_item_t *item); 136 137 /** 138 * function xge_uld_before_device_poll_f - ULD "before-poll" callback. 139 * @devh: HAL device handle. 140 * 141 * HAL invokes the callback from inside its xge_hal_device_poll() 142 * implementation %prior to accessing the @devh device. This allows ULD to 143 * perform per-device locking and/or context mapping, if required.. 144 * The interface is currently used by AIX driver only. 145 * To avoid using/implementing the callback set the corresponding field 146 * in the xge_hal_uld_cbs_t{} structure to NULL. 147 * 148 * Returns: 0 on success, non-zero on failure. 149 * 150 * See also: xge_hal_driver_initialize(), xge_hal_uld_cbs_t{}, 151 * xge_hal_device_poll(). 152 */ 153 typedef int (*xge_uld_before_device_poll_f) (xge_hal_device_h devh); 154 155 /** 156 * function xge_uld_after_device_poll_f - ULD "after-poll" callback. 157 * @devh: HAL device handle. 158 * 159 * Unless NULL is specified, 160 * HAL invokes the callback from inside its xge_hal_device_poll() 161 * implementation immediately %after it has completed polling the @devh 162 * device. This allows ULD to undo the affects of 163 * xge_uld_before_device_poll_f{}. 164 * The interface is currently used by AIX driver only. 165 * 166 * See also: xge_hal_driver_initialize(), xge_hal_uld_cbs_t{}, 167 * xge_hal_device_poll(). 168 */ 169 typedef void (*xge_uld_after_device_poll_f) (xge_hal_device_h devh); 170 171 /** 172 * function xge_uld_xpak_alarm_log_f - ULD "XPAK alarm log" callback. 173 * @devh: HAL device handle. 174 * 175 * Unless NULL is specified, 176 * HAL invokes the callback from inside __hal_chk_xpak_counter() 177 */ 178 typedef void (*xge_uld_xpak_alarm_log_f) (xge_hal_device_h devh, xge_hal_xpak_alarm_type_e type); 179 180 /** 181 * struct xge_hal_uld_cbs_t - Upper-layer driver "slow-path" callbacks. 182 * @link_up: See xge_uld_link_up_f{}. 183 * @link_down: See xge_uld_link_down_f{}. 184 * @crit_err: See xge_uld_crit_err_f{}. 185 * @event: See xge_uld_event_f{}. 186 * @event_queued: See xge_uld_event_queued_f{}. 187 * @before_device_poll: See xge_uld_before_device_poll_f{}. 188 * @after_device_poll: See xge_uld_after_device_poll_f{}. 189 * @sched_timer: See xge_uld_sched_timer_cb_f{}. 190 * 191 * Upper layer driver slow-path (per-driver) callbacks. 192 * Implemented by ULD and provided to HAL via 193 * xge_hal_driver_initialize(). 194 * Note that these callbacks are not mandatory: HAL will not invoke 195 * a callback if NULL is specified. 196 * 197 * Note that in addition to those, there are curently 2 per-channel callbacks 198 * (completion and abort) specified at channel open time 199 * via xge_hal_channel_open(). 200 * 201 * See also: xge_hal_driver_initialize(). 202 */ 203 typedef struct xge_hal_uld_cbs_t { 204 xge_uld_link_up_f link_up; 205 xge_uld_link_down_f link_down; 206 xge_uld_crit_err_f crit_err; 207 xge_uld_event_f event; 208 xge_uld_event_queued_f event_queued; 209 xge_uld_before_device_poll_f before_device_poll; 210 xge_uld_after_device_poll_f after_device_poll; 211 xge_uld_sched_timer_cb_f sched_timer; 212 xge_uld_xpak_alarm_log_f xpak_alarm_log; 213 } xge_hal_uld_cbs_t; 214 215 /** 216 * struct xge_hal_driver_t - Represents HAL object. 217 * @config: HAL configuration. 218 * @devices: List of all PCI-enumerated Xframe devices in the system. 219 * A single xge_hal_driver_t instance contains zero or more 220 * Xframe devices. 221 * @devices_lock: Lock to protect %devices when inserting/removing. 222 * @is_initialized: True if HAL is initialized; false otherwise. 223 * @uld_callbacks: Upper-layer driver callbacks. See xge_hal_uld_cbs_t{}. 224 * @debug_module_mask: 32bit mask that defines which components of the 225 * driver are to be traced. The trace-able components are: 226 * XGE_COMPONENT_HAL_CONFIG 0x1 227 * XGE_COMPONENT_HAL_FIFO 0x2 228 * XGE_COMPONENT_HAL_RING 0x4 229 * XGE_COMPONENT_HAL_CHANNEL 0x8 230 * XGE_COMPONENT_HAL_DEVICE 0x10 231 * XGE_COMPONENT_HAL_MM 0x20 232 * XGE_COMPONENT_HAL_QUEUE 0x40 233 * XGE_COMPONENT_HAL_STATS 0x100 234 * XGE_COMPONENT_OSDEP 0x1000 235 * XGE_COMPONENT_LL 0x2000 236 * XGE_COMPONENT_TOE 0x4000 237 * XGE_COMPONENT_RDMA 0x8000 238 * XGE_COMPONENT_ALL 0xffffffff 239 * The @debug_module_mask allows to switch off and on tracing at runtime. 240 * In addition, the traces for the same trace-able components can be 241 * compiled out, based on the same mask provided via Makefile. 242 * @debug_level: See xge_debug_level_e{}. 243 * 244 * HAL (driver) object. There is a single instance of this structure per HAL. 245 */ 246 typedef struct xge_hal_driver_t { 247 xge_hal_driver_config_t config; 248 int is_initialized; 249 xge_hal_uld_cbs_t uld_callbacks; 250 u32 debug_module_mask; 251 int debug_level; 252 } xge_hal_driver_t; 253 254 extern xge_hal_driver_t *g_xge_hal_driver; 255 256 static inline int 257 xge_hal_driver_is_initialized(void) { 258 return g_xge_hal_driver->is_initialized; 259 } 260 261 static inline int 262 xge_hal_driver_debug_module_mask(void) 263 { 264 return g_xge_hal_driver->debug_module_mask; 265 } 266 267 static inline void 268 xge_hal_driver_debug_module_mask_set(u32 new_mask) 269 { 270 #if (defined(XGE_DEBUG_TRACE_MASK) && XGE_DEBUG_TRACE_MASK > 0) || \ 271 (defined(XGE_DEBUG_ERR_MASK) && XGE_DEBUG_ERR_MASK > 0) 272 g_xge_hal_driver->debug_module_mask = new_mask; 273 g_module_mask = &g_xge_hal_driver->debug_module_mask; 274 #endif 275 } 276 277 static inline int 278 xge_hal_driver_debug_level(void) { return g_xge_hal_driver->debug_level; } 279 280 static inline void 281 xge_hal_driver_debug_level_set(int new_level) 282 { 283 #if (defined(XGE_DEBUG_TRACE_MASK) && XGE_DEBUG_TRACE_MASK > 0) || \ 284 (defined(XGE_DEBUG_ERR_MASK) && XGE_DEBUG_ERR_MASK > 0) 285 g_xge_hal_driver->debug_level = new_level; 286 g_level = &g_xge_hal_driver->debug_level; 287 #endif 288 } 289 290 static inline void 291 xge_hal_driver_module_mask_set(int new_mask) { 292 g_xge_hal_driver->debug_module_mask = new_mask; } 293 294 xge_hal_status_e xge_hal_driver_initialize(xge_hal_driver_config_t *config, 295 xge_hal_uld_cbs_t *uld_callbacks); 296 297 void xge_hal_driver_terminate(void); 298 299 #ifdef XGE_TRACE_INTO_CIRCULAR_ARR 300 static inline void 301 xge_hal_driver_tracebuf_timestamp(int on) 302 { 303 g_xge_os_tracebuf->timestamp = on; 304 } 305 306 void xge_hal_driver_tracebuf_dump(void); 307 #else 308 #define xge_hal_driver_tracebuf_timestamp(a) 309 #define xge_hal_driver_tracebuf_dump() 310 #endif 311 312 __EXTERN_END_DECLS 313 314 #endif /* XGE_HAL_DRIVER_H */ 315