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