include/sys/mdi_impldefs.h

   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 /*
  22  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
  23  * Use is subject to license terms.
  24  */
  25
  26 #ifndef _SYS_MDI_IMPLDEFS_H
  27 #define _SYS_MDI_IMPLDEFS_H
  28
  29
  30 #include <sys/note.h>
  31 #include <sys/types.h>
  32 #include <sys/sunmdi.h>
  33 #include <sys/modhash.h>
  34 #include <sys/callb.h>
  35 #include <sys/devctl.h>
  36
  37 #ifdef  __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 #ifdef _KERNEL
  42
  43 /*
  44  * Multipath Driver Interfaces
  45  *
  46  * The multipathing framework is provided in two modules.  The 'mpxio' misc.
  47  * module provides the core multipath framework and the 'scsi_vhci' nexus
  48  * driver provides the SCSI-III command set driver functionality for
  49  * managing Fibre-Channel storage devices.
  50  *
  51  * As in any multipathing solution there are three major problems to solve:
  52  *
  53  * 1) Identification and enumeration of multipath client devices.
  54  * 2) Optimal path selection when routing I/O requests.
  55  * 3) Observability interfaces to snapshot the multipath configuration,
  56  *    and infrastructure to provide performance and error statistics.
  57  *
  58  * The mpxio framework consists of several major components:
  59  *
  60  * 1) The MDI is the Multiplexed Device Interface; this is the core glue which
  61  *    holds the following components together.
  62  * 2) vHCI (Virtual Host Controller Interconnect) drivers provide multipathing
  63  *    services for a given bus technology (example: 'scsi_vhci' provides
  64  *    multipathing support for SCSI-III fibre-channel devices).
  65  * 3) pHCI (Physical Host Controller Interconnect) drivers provide transport
  66  *    services for a given host controller (example: 'fcp' provides transport
  67  *    for fibre-channel devices).
  68  * 4) Client Devices are standard Solaris target (or leaf) drivers
  69  *    (example: 'ssd' is the standard disk driver for fibre-channel arrays).
  70  * 5) Multipath information nodes ('pathinfo' nodes) connect client device
  71  *    nodes and pHCI device nodes in the device tree.
  72  *
  73  * With the scsi_vhci, a QLC card, and mpxio enabled, the device tree might
  74  * look like this:
  75  *
  76  *              /\
  77  *             /  ............
  78  *     <vHCI>:/               \
  79  *      +-----------+   +-----------+
  80  *      | scsi_vhci |   |  pci@1f,0 |
  81  *      +-----------+   +-----------+
  82  *            /   \               \
  83  * <Client>: /     \ :<Client>     \ :parent(pHCI)
  84  *  +----------+ +-----------+    +-------------+
  85  *  | ssd 1    | | ssd 2     |    | qlc@0,0     |
  86  *  +----------+ +-----------+    +-------------+
  87  *   |            |                /        \
  88  *   |            |       <pHCI>: /          \ :<pHCI>
  89  *   |            |      +-------------+   +-------------+
  90  *   |            |      | pHCI 1 (fp) |   | pHCI 2 (fp) |
  91  *   |            |      +-------------+   +-------------+
  92  *   |            |          /        |      /          |
  93  *   |            |    +------+       |    +------+     |
  94  *   |            |    | ssd 3|       |    | ssd  |     |
  95  *   |            |    |!mpxio|       |    | (OBP)|     |
  96  *   |            |    +------+       |    +------+     |
  97  *   |            |                   |                 |
  98  *   |            |       <pathinfo>: |                 |
  99  *   |            |               +-------+         +--------+
 100  *   |            +-------------->| path  |-------->| path   |
 101  *   |                            | info  |         | info   |
 102  *   |                            | node 1|         | node 3 |
 103  *   |                            +-------+         +--------+
 104  *   |                                |               |
 105  *   |                                |            +~~~~~~~~+
 106  *   |                            +-------+        :+--------+
 107  *   +--------------------------->| path  |-------->| path   |
 108  *                                | info  |        :| info   |
 109  *                                | node 2|        +| node 4 |
 110  *                                +-------+         +--------+
 111  *
 112  * The multipath information nodes (mdi_pathinfo nodes) establish the
 113  * relationship between the pseudo client driver instance nodes (children
 114  * of the vHCI) and the physical host controller interconnect (pHCI
 115  * drivers) forming a matrix structure.
 116  *
 117  * The mpxio module implements locking at multiple granularity levels to
 118  * support the needs of various consumers.  The multipath matrix can be
 119  * column locked, or row locked depending on the consumer. The intention
 120  * is to balance simplicity and performance.
 121  *
 122  * Locking:
 123  *
 124  * The devinfo locking still applies:
 125  *
 126  *   1) An ndi_devi_enter of a parent protects linkage/state of children.
 127  *   2) state >= DS_INITIALIZED adds devi_ref of parent
 128  *   3) devi_ref at state >= DS_ATTACHED prevents detach(9E).
 129  *
 130  * The ordering of 1) is (vHCI, pHCI). For a DEBUG kernel this ordering
 131  * is asserted by the ndi_devi_enter() implementation.  There is also an
 132  * ndi_devi_enter(Client), which is atypical since the client is a leaf.
 133  * This is done to synchronize pathinfo nodes during devinfo snapshot (see
 134  * di_register_pip) by pretending that the pathinfo nodes are children
 135  * of the client.
 136  *
 137  * In addition to devinfo locking the current implementation utilizes
 138  * the following locks:
 139  *
 140  *   mdi_mutex: protects the global list of vHCIs.
 141  *
 142  *   vh_phci_mutex: per-vHCI (mutex) lock: protects list of pHCIs registered
 143  *   with vHCI.
 144  *
 145  *   vh_client_mutex: per-vHCI (mutex) lock: protects list/hash of Clients
 146  *   associated with vHCI.
 147  *
 148  *   ph_mutex: per-pHCI (mutex) lock: protects the column (pHCI-mdi_pathinfo
 149  *   node list) and per-pHCI structure fields.  mdi_pathinfo node creation,
 150  *   deletion and child mdi_pathinfo node state changes are serialized on per
 151  *   pHCI basis (Protection against DR).
 152  *
 153  *   ct_mutex: per-client (mutex) lock: protects the row (client-mdi_pathinfo
 154  *   node list) and per-client structure fields.  The client-mdi_pathinfo node
 155  *   list is typically walked to select an optimal path when routing I/O
 156  *   requests.
 157  *
 158  *   pi_mutex: per-mdi_pathinfo (mutex) lock: protects the mdi_pathinfo node
 159  *   structure fields.
 160  *
 161  * Note that per-Client structure and per-pHCI fields are freely readable when
 162  * corresponding mdi_pathinfo locks are held, since holding an mdi_pathinfo
 163  * node guarantees that its corresponding client and pHCI devices will not be
 164  * freed.
 165  */
 166
 167 /*
 168  * MDI Client global unique identifier property name string definition
 169  */
 170 extern const char                       *mdi_client_guid_prop;
 171 #define MDI_CLIENT_GUID_PROP            (char *)mdi_client_guid_prop
 172
 173 /*
 174  * MDI Client load balancing policy definitions
 175  *
 176  * Load balancing policies are determined on a per-vHCI basis and are
 177  * configurable via the vHCI's driver.conf file.
 178  */
 179 typedef enum {
 180         LOAD_BALANCE_NONE,              /* Alternate pathing            */
 181         LOAD_BALANCE_RR,                /* Round Robin                  */
 182         LOAD_BALANCE_LBA                /* Logical Block Addressing     */
 183 } client_lb_t;
 184
 185 typedef struct {
 186         int region_size;
 187 }client_lb_args_t;
 188
 189 /*
 190  * MDI client load balancing property name/value string definitions
 191  */
 192 extern const char                       *mdi_load_balance;
 193 extern const char                       *mdi_load_balance_none;
 194 extern const char                       *mdi_load_balance_ap;
 195 extern const char                       *mdi_load_balance_rr;
 196 extern const char                       *mdi_load_balance_lba;
 197
 198 #define LOAD_BALANCE_PROP               (char *)mdi_load_balance
 199 #define LOAD_BALANCE_PROP_NONE          (char *)mdi_load_balance_none
 200 #define LOAD_BALANCE_PROP_AP            (char *)mdi_load_balance_ap
 201 #define LOAD_BALANCE_PROP_RR            (char *)mdi_load_balance_rr
 202 #define LOAD_BALANCE_PROP_LBA           (char *)mdi_load_balance_lba
 203
 204 /* default for region size */
 205 #define LOAD_BALANCE_DEFAULT_REGION_SIZE        18
 206
 207 /*
 208  * vHCI drivers:
 209  *
 210  * vHCI drivers are pseudo nexus drivers which implement multipath services
 211  * for a specific command set or bus architecture ('class').  There is a
 212  * single instance of the vHCI driver for each command set which supports
 213  * multipath devices.
 214  *
 215  * Each vHCI driver registers the following callbacks from attach(9e).
 216  */
 217 #define MDI_VHCI_OPS_REV_1              1
 218 #define MDI_VHCI_OPS_REV                MDI_VHCI_OPS_REV_1
 219
 220 typedef struct mdi_vhci_ops {
 221         /* revision management */
 222         int     vo_revision;
 223
 224         /* mdi_pathinfo node init callback */
 225         int     (*vo_pi_init)(dev_info_t *vdip, mdi_pathinfo_t *pip, int flags);
 226
 227         /* mdi_pathinfo node uninit callback */
 228         int     (*vo_pi_uninit)(dev_info_t *vdip, mdi_pathinfo_t *pip,
 229                     int flags);
 230
 231         /* mdi_pathinfo node state change callback */
 232         int     (*vo_pi_state_change)(dev_info_t *vdip, mdi_pathinfo_t *pip,
 233                     mdi_pathinfo_state_t state, uint32_t, int flags);
 234
 235         /* Client path failover callback */
 236         int     (*vo_failover)(dev_info_t *vdip, dev_info_t *cdip, int flags);
 237
 238         /* Client attached callback */
 239         void    (*vo_client_attached)(dev_info_t *cdip);
 240
 241         /* Ask vHCI if 'cinfo' device is support as a client */
 242         int     (*vo_is_dev_supported)(dev_info_t *vdip, dev_info_t *pdip,
 243                     void *cinfo);
 244 } mdi_vhci_ops_t;
 245
 246 /*
 247  * An mdi_vhci structure is created and bound to the devinfo node of every
 248  * registered vHCI class driver; this happens when a vHCI registers itself from
 249  * attach(9e).  This structure is unbound and freed when the vHCI unregisters
 250  * at detach(9e) time;
 251  *
 252  * Each vHCI driver is associated with a vHCI class name; this is the handle
 253  * used to register and unregister pHCI drivers for a given transport.
 254  *
 255  * Locking: Different parts of this structure are guarded by different
 256  * locks: global threading of multiple vHCIs and initialization is protected
 257  * by mdi_mutex, the list of pHCIs associated with a vHCI is protected by
 258  * vh_phci_mutex, and Clients are protected by vh_client_mutex.
 259  *
 260  * XXX Depending on the context, some of the fields can be freely read without
 261  * holding any locks (ex. holding vh_client_mutex lock also guarantees that
 262  * the vHCI (parent) cannot be unexpectedly freed).
 263  */
 264 typedef struct mdi_vhci {
 265         /* protected by mdi_mutex... */
 266         struct mdi_vhci         *vh_next;       /* next vHCI link       */
 267         struct mdi_vhci         *vh_prev;       /* prev vHCI link       */
 268         char                    *vh_class;      /* vHCI class name      */
 269         dev_info_t              *vh_dip;        /* vHCI devi handle     */
 270         int                     vh_refcnt;      /* vHCI reference count */
 271         struct mdi_vhci_config  *vh_config;     /* vHCI config          */
 272         client_lb_t             vh_lb;          /* vHCI load-balancing  */
 273         struct mdi_vhci_ops     *vh_ops;        /* vHCI callback vectors */
 274
 275         /* protected by MDI_VHCI_PHCI_LOCK vh_phci_mutex... */
 276         kmutex_t                vh_phci_mutex;  /* pHCI mutex           */
 277         int                     vh_phci_count;  /* pHCI device count    */
 278         struct mdi_phci         *vh_phci_head;  /* pHCI list head       */
 279         struct mdi_phci         *vh_phci_tail;  /* pHCI list tail       */
 280
 281         /* protected by MDI_VHCI_CLIENT_LOCK vh_client_mutex... */
 282         kmutex_t                vh_client_mutex; /* Client mutex        */
 283         int                     vh_client_count; /* Client count        */
 284         struct client_hash      *vh_client_table; /* Client hash        */
 285 } mdi_vhci_t;
 286
 287 /*
 288  * per-vHCI lock macros
 289  */
 290 #define MDI_VHCI_PHCI_LOCK(vh)          mutex_enter(&(vh)->vh_phci_mutex)
 291 #define MDI_VHCI_PHCI_TRYLOCK(vh)       mutex_tryenter(&(vh)->vh_phci_mutex)
 292 #define MDI_VHCI_PHCI_UNLOCK(vh)        mutex_exit(&(vh)->vh_phci_mutex)
 293 #ifdef  DEBUG
 294 #define MDI_VHCI_PCHI_LOCKED(vh)        MUTEX_HELD(&(vh)->vh_phci_mutex)
 295 #endif  /* DEBUG */
 296 #define MDI_VHCI_CLIENT_LOCK(vh)        mutex_enter(&(vh)->vh_client_mutex)
 297 #define MDI_VHCI_CLIENT_TRYLOCK(vh)     mutex_tryenter(&(vh)->vh_client_mutex)
 298 #define MDI_VHCI_CLIENT_UNLOCK(vh)      mutex_exit(&(vh)->vh_client_mutex)
 299 #ifdef  DEBUG
 300 #define MDI_VHCI_CLIENT_LOCKED(vh)      MUTEX_HELD(&(vh)->vh_client_mutex)
 301 #endif  /* DEBUG */
 302
 303
 304 /*
 305  * GUID Hash definitions
 306  *
 307  * Since all the mpxio managed devices for a given class are enumerated under
 308  * the single vHCI instance for that class, sequentially walking through the
 309  * client device link to find a client would be prohibitively slow.
 310  */
 311
 312 #define CLIENT_HASH_TABLE_SIZE  (32)    /* GUID hash */
 313
 314 /*
 315  * Client hash table structure
 316  */
 317 struct client_hash {
 318         struct mdi_client       *ct_hash_head;  /* Client hash head     */
 319         int                     ct_hash_count;  /* Client hash count    */
 320 };
 321
 322
 323 /*
 324  * pHCI Drivers:
 325  *
 326  * Physical HBA drivers provide transport services for mpxio-managed devices.
 327  * As each pHCI instance is attached, it must register itself with the mpxio
 328  * framework using mdi_phci_register().  When the pHCI is detached it must
 329  * similarly call mdi_phci_unregister().
 330  *
 331  * The framework maintains a list of registered pHCI device instances for each
 332  * vHCI.  This list involves (vh_phci_count, vh_phci_head, vh_phci_tail) and
 333  * (ph_next, ph_prev, ph_vhci) and is protected by vh_phci_mutex.
 334  *
 335  * Locking order:
 336  *
 337  * _NOTE(LOCK_ORDER(mdi_mutex, mdi_phci::ph_mutex))             XXX
 338  * _NOTE(LOCK_ORDER(mdi_phci::ph_mutex devinfo_tree_lock))              XXX
 339  */
 340 typedef struct mdi_phci {
 341         /* protected by MDI_VHCI_PHCI_LOCK vh_phci_mutex... */
 342         struct mdi_phci         *ph_next;       /* next pHCI link       */
 343         struct mdi_phci         *ph_prev;       /* prev pHCI link       */
 344         dev_info_t              *ph_dip;        /* pHCI devi handle     */
 345         struct mdi_vhci         *ph_vhci;       /* pHCI back ref. to vHCI */
 346
 347         /* protected by MDI_PHCI_LOCK ph_mutex... */
 348         kmutex_t                ph_mutex;       /* per-pHCI mutex       */
 349         int                     ph_path_count;  /* pi count             */
 350         mdi_pathinfo_t          *ph_path_head;  /* pi list head         */
 351         mdi_pathinfo_t          *ph_path_tail;  /* pi list tail         */
 352         int                     ph_flags;       /* pHCI operation flags */
 353         int                     ph_unstable;    /* Paths in transient state */
 354         kcondvar_t              ph_unstable_cv; /* Paths in transient state */
 355
 356         /* protected by mdi_phci_[gs]et_vhci_private caller... */
 357         void                    *ph_vprivate;   /* vHCI driver private  */
 358 } mdi_phci_t;
 359
 360 /*
 361  * A pHCI device is 'unstable' while one or more paths are in a transitional
 362  * state.  Hotplugging is prevented during this state.
 363  */
 364 #define MDI_PHCI_UNSTABLE(ph)           (ph)->ph_unstable++;
 365 #define MDI_PHCI_STABLE(ph) { \
 366         (ph)->ph_unstable--; \
 367         if ((ph)->ph_unstable == 0) { \
 368                 cv_broadcast(&(ph)->ph_unstable_cv); \
 369         } \
 370 }
 371
 372 /*
 373  * per-pHCI lock macros
 374  */
 375 #define MDI_PHCI_LOCK(ph)               mutex_enter(&(ph)->ph_mutex)
 376 #define MDI_PHCI_TRYLOCK(ph)            mutex_tryenter(&(ph)->ph_mutex)
 377 #define MDI_PHCI_UNLOCK(ph)             mutex_exit(&(ph)->ph_mutex)
 378 #ifdef  DEBUG
 379 #define MDI_PHCI_LOCKED(vh)             MUTEX_HELD(&(ph)->ph_mutex)
 380 #endif  /* DEBUG */
 381
 382 /*
 383  * pHCI state definitions and macros to track the pHCI driver instance state
 384  */
 385 #define MDI_PHCI_FLAGS_OFFLINE          0x1     /* pHCI is offline */
 386 #define MDI_PHCI_FLAGS_SUSPEND          0x2     /* pHCI is suspended */
 387 #define MDI_PHCI_FLAGS_POWER_DOWN       0x4     /* pHCI is power down */
 388 #define MDI_PHCI_FLAGS_DETACH           0x8     /* pHCI is detached */
 389 #define MDI_PHCI_FLAGS_USER_DISABLE     0x10    /* pHCI is disabled,user */
 390 #define MDI_PHCI_FLAGS_D_DISABLE        0x20    /* pHCI is disabled,driver */
 391 #define MDI_PHCI_FLAGS_D_DISABLE_TRANS  0x40    /* pHCI is disabled,transient */
 392 #define MDI_PHCI_FLAGS_POWER_TRANSITION 0x80    /* pHCI is power transition */
 393
 394 #define MDI_PHCI_DISABLE_MASK                                           \
 395             (MDI_PHCI_FLAGS_USER_DISABLE | MDI_PHCI_FLAGS_D_DISABLE |   \
 396             MDI_PHCI_FLAGS_D_DISABLE_TRANS)
 397
 398 #define MDI_PHCI_IS_READY(ph)                                           \
 399             (((ph)->ph_flags & MDI_PHCI_DISABLE_MASK) == 0)
 400
 401 #define MDI_PHCI_SET_OFFLINE(ph)                                        {\
 402             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 403             (ph)->ph_flags |= MDI_PHCI_FLAGS_OFFLINE;                   }
 404 #define MDI_PHCI_SET_ONLINE(ph)                                         {\
 405             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 406             (ph)->ph_flags &= ~MDI_PHCI_FLAGS_OFFLINE;                  }
 407 #define MDI_PHCI_IS_OFFLINE(ph)                                         \
 408             ((ph)->ph_flags & MDI_PHCI_FLAGS_OFFLINE)
 409
 410 #define MDI_PHCI_SET_SUSPEND(ph)                                        {\
 411             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 412             (ph)->ph_flags |= MDI_PHCI_FLAGS_SUSPEND;                   }
 413 #define MDI_PHCI_SET_RESUME(ph)                                         {\
 414             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 415             (ph)->ph_flags &= ~MDI_PHCI_FLAGS_SUSPEND;                  }
 416 #define MDI_PHCI_IS_SUSPENDED(ph)                                       \
 417             ((ph)->ph_flags & MDI_PHCI_FLAGS_SUSPEND)
 418
 419 #define MDI_PHCI_SET_DETACH(ph)                                         {\
 420             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 421             (ph)->ph_flags |= MDI_PHCI_FLAGS_DETACH;                    }
 422 #define MDI_PHCI_SET_ATTACH(ph)                                         {\
 423             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 424             (ph)->ph_flags &= ~MDI_PHCI_FLAGS_DETACH;                   }
 425
 426 #define MDI_PHCI_SET_POWER_DOWN(ph)                                     {\
 427             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 428             (ph)->ph_flags |= MDI_PHCI_FLAGS_POWER_DOWN;                }
 429 #define MDI_PHCI_SET_POWER_UP(ph)                                       {\
 430             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 431             (ph)->ph_flags &= ~MDI_PHCI_FLAGS_POWER_DOWN;               }
 432 #define MDI_PHCI_IS_POWERED_DOWN(ph)                                    \
 433             ((ph)->ph_flags & MDI_PHCI_FLAGS_POWER_DOWN)
 434
 435 #define MDI_PHCI_SET_USER_ENABLE(ph)                                    {\
 436             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 437             (ph)->ph_flags &= ~MDI_PHCI_FLAGS_USER_DISABLE;             }
 438 #define MDI_PHCI_SET_USER_DISABLE(ph)                                   {\
 439             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 440             (ph)->ph_flags |= MDI_PHCI_FLAGS_USER_DISABLE;              }
 441 #define MDI_PHCI_IS_USER_DISABLED(ph)                                   \
 442             ((ph)->ph_flags & MDI_PHCI_FLAGS_USER_DISABLE)
 443
 444 #define MDI_PHCI_SET_DRV_ENABLE(ph)                                     {\
 445             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 446             (ph)->ph_flags &= ~MDI_PHCI_FLAGS_D_DISABLE;                }
 447 #define MDI_PHCI_SET_DRV_DISABLE(ph)                                    {\
 448             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 449             (ph)->ph_flags |= MDI_PHCI_FLAGS_D_DISABLE;                 }
 450 #define MDI_PHCI_IS_DRV_DISABLED(ph)                                    \
 451             ((ph)->ph_flags & MDI_PHCI_FLAGS_D_DISABLE)
 452
 453 #define MDI_PHCI_SET_DRV_ENABLE_TRANSIENT(ph)                           {\
 454             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 455             (ph)->ph_flags &= ~MDI_PHCI_FLAGS_D_DISABLE_TRANS;          }
 456 #define MDI_PHCI_SET_DRV_DISABLE_TRANSIENT(ph)                          {\
 457             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 458             (ph)->ph_flags |= MDI_PHCI_FLAGS_D_DISABLE_TRANS;           }
 459 #define MDI_PHCI_IS_DRV_DISABLED_TRANSIENT(ph)                          \
 460             ((ph)->ph_flags & MDI_PHCI_FLAGS_D_DISABLE_TRANS)
 461
 462 #define MDI_PHCI_SET_POWER_TRANSITION(ph)                               {\
 463             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 464             (ph)->ph_flags |= MDI_PHCI_FLAGS_POWER_TRANSITION;          }
 465 #define MDI_PHCI_CLEAR_POWER_TRANSITION(ph)                             {\
 466             ASSERT(MDI_PHCI_LOCKED(ph));                                \
 467             (ph)->ph_flags &= ~MDI_PHCI_FLAGS_POWER_TRANSITION;         }
 468 #define MDI_PHCI_IS_POWER_TRANSITION(ph)                                \
 469             ((ph)->ph_flags & MDI_PHCI_FLAGS_POWER_TRANSITION)
 470
 471 /*
 472  * mpxio Managed Clients:
 473  *
 474  * This framework creates a struct mdi_client for every client device created
 475  * by the framework as a result of self-enumeration of target devices by the
 476  * registered pHCI devices.  This structure is bound to client device dev_info
 477  * node at the time of client device allocation (ndi_devi_alloc(9e)). This
 478  * structure is unbound from the dev_info node when mpxio framework removes a
 479  * client device node from the system.
 480  *
 481  * This structure is created when a first path is enumerated and removed when
 482  * last path is de-enumerated from the system.
 483  *
 484  * Multipath client devices are instantiated as children of corresponding vHCI
 485  * driver instance. Each client device is uniquely identified by a GUID
 486  * provided by target device itself.  The parent vHCI device also maintains a
 487  * hashed list of client devices, protected by vh_client_mutex.
 488  *
 489  * Typically pHCI devices self-enumerate their child devices using taskq,
 490  * resulting in multiple paths to the same client device to be enumerated by
 491  * competing threads.
 492  *
 493  * Currently this framework supports two kinds of load-balancing policy
 494  * configurable through the vHCI driver configuration files.
 495  *
 496  * NONE         - Legacy AP mode
 497  * Round Robin  - Balance the pHCI load in a Round Robin fashion.
 498  *
 499  * This framework identifies the client device in three distinct states:
 500  *
 501  * OPTIMAL      - Client device has at least one redundant path.
 502  * DEGRADED     - No redundant paths (critical).  Failure in the current active
 503  *                path would result in data access failures.
 504  * FAILED       - No paths are available to access this device.
 505  *
 506  * Locking order:
 507  *
 508  * _NOTE(LOCK_ORDER(mdi_mutex, mdi_client::ct_mutex))                   XXX
 509  * _NOTE(LOCK_ORDER(mdi_client::ct_mutex devinfo_tree_lock))            XXX
 510  */
 511 typedef struct mdi_client {
 512         /* protected by MDI_VHCI_CLIENT_LOCK vh_client_mutex... */
 513         struct mdi_client       *ct_hnext;      /* next client          */
 514         struct mdi_client       *ct_hprev;      /* prev client          */
 515         dev_info_t              *ct_dip;        /* client devi handle   */
 516         struct mdi_vhci         *ct_vhci;       /* vHCI back ref        */
 517         char                    *ct_drvname;    /* client driver name   */
 518         char                    *ct_guid;       /* client guid          */
 519         client_lb_t             ct_lb;          /* load balancing scheme */
 520         client_lb_args_t        *ct_lb_args;    /* load balancing args */
 521
 522
 523         /* protected by MDI_CLIENT_LOCK ct_mutex... */
 524         kmutex_t                ct_mutex;       /* per-client mutex     */
 525         int                     ct_path_count;  /* multi path count     */
 526         mdi_pathinfo_t          *ct_path_head;  /* multi path list head */
 527         mdi_pathinfo_t          *ct_path_tail;  /* multi path list tail */
 528         mdi_pathinfo_t          *ct_path_last;  /* last path used for i/o */
 529         int                     ct_state;       /* state information    */
 530         int                     ct_flags;       /* Driver op. flags     */
 531         int                     ct_failover_flags;      /* Failover args */
 532         int                     ct_failover_status;     /* last fo status */
 533         kcondvar_t              ct_failover_cv; /* Failover status cv   */
 534         int                     ct_unstable;    /* Paths in transient state */
 535         kcondvar_t              ct_unstable_cv; /* Paths in transient state */
 536
 537         int                     ct_power_cnt;   /* Hold count on parent power */
 538         kcondvar_t              ct_powerchange_cv;
 539                                         /* Paths in power transient state */
 540         short                   ct_powercnt_config;
 541                                         /* held in pre/post config */
 542         short                   ct_powercnt_unconfig;
 543                                         /* held in pre/post unconfig */
 544         int                     ct_powercnt_reset;
 545                                         /* ct_power_cnt was reset */
 546
 547         void                    *ct_cprivate;   /* client driver private */
 548         void                    *ct_vprivate;   /* vHCI driver private  */
 549 } mdi_client_t;
 550
 551 /*
 552  * per-Client device locking definitions
 553  */
 554 #define MDI_CLIENT_LOCK(ct)             mutex_enter(&(ct)->ct_mutex)
 555 #define MDI_CLIENT_TRYLOCK(ct)          mutex_tryenter(&(ct)->ct_mutex)
 556 #define MDI_CLIENT_UNLOCK(ct)           mutex_exit(&(ct)->ct_mutex)
 557 #ifdef  DEBUG
 558 #define MDI_CLIENT_LOCKED(ct)           MUTEX_HELD(&(ct)->ct_mutex)
 559 #endif  /* DEBUG */
 560
 561 /*
 562  * A Client device is in unstable while one or more paths are in transitional
 563  * state.  We do not allow failover to take place while paths are in transient
 564  * state. Similarly we do not allow state transition while client device
 565  * failover is in progress.
 566  */
 567 #define MDI_CLIENT_UNSTABLE(ct)         (ct)->ct_unstable++;
 568 #define MDI_CLIENT_STABLE(ct) { \
 569         (ct)->ct_unstable--; \
 570         if ((ct)->ct_unstable == 0) { \
 571                 cv_broadcast(&(ct)->ct_unstable_cv); \
 572         } \
 573 }
 574
 575 /*
 576  * Client driver instance state definitions:
 577  */
 578 #define MDI_CLIENT_FLAGS_OFFLINE                0x00000001
 579 #define MDI_CLIENT_FLAGS_SUSPEND                0x00000002
 580 #define MDI_CLIENT_FLAGS_POWER_DOWN             0x00000004
 581 #define MDI_CLIENT_FLAGS_DETACH                 0x00000008
 582 #define MDI_CLIENT_FLAGS_FAILOVER               0x00000010
 583 #define MDI_CLIENT_FLAGS_REPORT_DEV             0x00000020
 584 #define MDI_CLIENT_FLAGS_PATH_FREE_IN_PROGRESS  0x00000040
 585 #define MDI_CLIENT_FLAGS_ASYNC_FREE             0x00000080
 586 #define MDI_CLIENT_FLAGS_DEV_NOT_SUPPORTED      0x00000100
 587 #define MDI_CLIENT_FLAGS_POWER_TRANSITION       0x00000200
 588
 589 #define MDI_CLIENT_SET_OFFLINE(ct)                                      {\
 590             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 591             (ct)->ct_flags |= MDI_CLIENT_FLAGS_OFFLINE;                 }
 592 #define MDI_CLIENT_SET_ONLINE(ct)                                       {\
 593             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 594             (ct)->ct_flags &= ~MDI_CLIENT_FLAGS_OFFLINE;                }
 595 #define MDI_CLIENT_IS_OFFLINE(ct) \
 596             ((ct)->ct_flags & MDI_CLIENT_FLAGS_OFFLINE)
 597
 598 #define MDI_CLIENT_SET_SUSPEND(ct)                                      {\
 599             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 600             (ct)->ct_flags |= MDI_CLIENT_FLAGS_SUSPEND;                 }
 601 #define MDI_CLIENT_SET_RESUME(ct)                                       {\
 602             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 603             (ct)->ct_flags &= ~MDI_CLIENT_FLAGS_SUSPEND;                }
 604 #define MDI_CLIENT_IS_SUSPENDED(ct) \
 605             ((ct)->ct_flags & MDI_CLIENT_FLAGS_SUSPEND)
 606
 607 #define MDI_CLIENT_SET_POWER_DOWN(ct)                                   {\
 608             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 609             (ct)->ct_flags |= MDI_CLIENT_FLAGS_POWER_DOWN;              }
 610 #define MDI_CLIENT_SET_POWER_UP(ct)                                     {\
 611             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 612             (ct)->ct_flags &= ~MDI_CLIENT_FLAGS_POWER_DOWN;             }
 613 #define MDI_CLIENT_IS_POWERED_DOWN(ct) \
 614             ((ct)->ct_flags & MDI_CLIENT_FLAGS_POWER_DOWN)
 615
 616 #define MDI_CLIENT_SET_POWER_TRANSITION(ct)                             {\
 617             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 618             (ct)->ct_flags |= MDI_CLIENT_FLAGS_POWER_TRANSITION;        }
 619 #define MDI_CLIENT_CLEAR_POWER_TRANSITION(ct)                           {\
 620             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 621             (ct)->ct_flags &= ~MDI_CLIENT_FLAGS_POWER_TRANSITION;       }
 622 #define MDI_CLIENT_IS_POWER_TRANSITION(ct) \
 623             ((ct)->ct_flags & MDI_CLIENT_FLAGS_POWER_TRANSITION)
 624
 625 #define MDI_CLIENT_SET_DETACH(ct)                                       {\
 626             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 627             (ct)->ct_flags |= MDI_CLIENT_FLAGS_DETACH;                  }
 628 #define MDI_CLIENT_SET_ATTACH(ct)                                       {\
 629             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 630             (ct)->ct_flags &= ~MDI_CLIENT_FLAGS_DETACH;                 }
 631 #define MDI_CLIENT_IS_DETACHED(ct) \
 632             ((ct)->ct_flags & MDI_CLIENT_FLAGS_DETACH)
 633
 634 #define MDI_CLIENT_SET_FAILOVER_IN_PROGRESS(ct)                         {\
 635             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 636             (ct)->ct_flags |= MDI_CLIENT_FLAGS_FAILOVER;                }
 637 #define MDI_CLIENT_CLEAR_FAILOVER_IN_PROGRESS(ct)                       {\
 638             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 639             (ct)->ct_flags &= ~MDI_CLIENT_FLAGS_FAILOVER;               }
 640 #define MDI_CLIENT_IS_FAILOVER_IN_PROGRESS(ct) \
 641             ((ct)->ct_flags & MDI_CLIENT_FLAGS_FAILOVER)
 642
 643 #define MDI_CLIENT_SET_REPORT_DEV_NEEDED(ct)                            {\
 644             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 645             (ct)->ct_flags |= MDI_CLIENT_FLAGS_REPORT_DEV;              }
 646 #define MDI_CLIENT_CLEAR_REPORT_DEV_NEEDED(ct)                          {\
 647             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 648             (ct)->ct_flags &= ~MDI_CLIENT_FLAGS_REPORT_DEV;             }
 649 #define MDI_CLIENT_IS_REPORT_DEV_NEEDED(ct) \
 650             ((ct)->ct_flags & MDI_CLIENT_FLAGS_REPORT_DEV)
 651
 652 #define MDI_CLIENT_SET_PATH_FREE_IN_PROGRESS(ct)                        {\
 653             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 654             (ct)->ct_flags |= MDI_CLIENT_FLAGS_PATH_FREE_IN_PROGRESS;   }
 655 #define MDI_CLIENT_CLEAR_PATH_FREE_IN_PROGRESS(ct)                      {\
 656             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 657             (ct)->ct_flags &= ~MDI_CLIENT_FLAGS_PATH_FREE_IN_PROGRESS;  }
 658 #define MDI_CLIENT_IS_PATH_FREE_IN_PROGRESS(ct) \
 659             ((ct)->ct_flags & MDI_CLIENT_FLAGS_PATH_FREE_IN_PROGRESS)
 660
 661 #define MDI_CLIENT_SET_DEV_NOT_SUPPORTED(ct)                            {\
 662             ASSERT(MDI_CLIENT_LOCKED(ct));                              \
 663             (ct)->ct_flags |= MDI_CLIENT_FLAGS_DEV_NOT_SUPPORTED;       }
 664 #define MDI_CLIENT_IS_DEV_NOT_SUPPORTED(ct) \
 665             ((ct)->ct_flags & MDI_CLIENT_FLAGS_DEV_NOT_SUPPORTED)
 666
 667 /*
 668  * Client operating states.
 669  */
 670 #define MDI_CLIENT_STATE_OPTIMAL        1
 671 #define MDI_CLIENT_STATE_DEGRADED       2
 672 #define MDI_CLIENT_STATE_FAILED         3
 673
 674 #define MDI_CLIENT_STATE(ct) ((ct)->ct_state)
 675 #define MDI_CLIENT_SET_STATE(ct, state) ((ct)->ct_state = state)
 676
 677 #define MDI_CLIENT_IS_FAILED(ct) \
 678             ((ct)->ct_state == MDI_CLIENT_STATE_FAILED)
 679
 680 /*
 681  * mdi_pathinfo nodes:
 682  *
 683  * From this framework's perspective, a 'path' is a tuple consisting of a
 684  * client or end device, a host controller which provides device
 685  * identification and transport services (pHCI), and bus specific unit
 686  * addressing information.  A path may be decorated with properties which
 687  * describe the capabilities of the path; such properties are analogous to
 688  * device node and minor node properties.
 689  *
 690  * The framework maintains link list of mdi_pathinfo nodes created by every
 691  * pHCI driver instance via the pi_phci_link linkage; this is used (for example)
 692  * to make sure that all relevant pathinfo nodes are freed before the pHCI
 693  * is unregistered.
 694  *
 695  * Locking order:
 696  *
 697  * _NOTE(LOCK_ORDER(mdi_phci::ph_mutex mdi_pathinfo::pi_mutex))         XXX
 698  * _NOTE(LOCK_ORDER(mdi_client::ct_mutex mdi_pathinfo::pi_mutex))       XXX
 699  * _NOTE(LOCK_ORDER(mdi_phci::ph_mutex mdi_client::ct_mutex))           XXX
 700  * _NOTE(LOCK_ORDER(devinfo_tree_lock mdi_pathinfo::pi_mutex))          XXX
 701  *
 702  * mdi_pathinfo node structure definition
 703  */
 704 struct mdi_pathinfo {
 705         /* protected by MDI_PHCI_LOCK ph_mutex... */
 706         struct mdi_pathinfo     *pi_phci_link;   /* next path in phci list */
 707         mdi_phci_t              *pi_phci;       /* pHCI dev_info node   */
 708
 709         /* protected by MDI_CLIENT_LOCK ct_mutex... */
 710         struct mdi_pathinfo     *pi_client_link; /* next path in client list */
 711         mdi_client_t            *pi_client;     /* client               */
 712
 713         /* protected by MDI_VHCI_CLIENT_LOCK vh_client_mutex... */
 714         char                    *pi_addr;       /* path unit address    */
 715         int                     pi_path_instance; /* path instance */
 716
 717         /* protected by MDI_PI_LOCK pi_mutex... */
 718         kmutex_t                pi_mutex;       /* per path mutex       */
 719         mdi_pathinfo_state_t    pi_state;       /* path state           */
 720         mdi_pathinfo_state_t    pi_old_state;   /* path state           */
 721         kcondvar_t              pi_state_cv;    /* path state condvar   */
 722         nvlist_t                *pi_prop;       /* Properties           */
 723         void                    *pi_cprivate;   /* client private info  */
 724         void                    *pi_pprivate;   /* phci private info    */
 725         int                     pi_ref_cnt;     /* pi reference count   */
 726         kcondvar_t              pi_ref_cv;      /* condition variable   */
 727         struct mdi_pi_kstats    *pi_kstats;     /* aggregate kstats */
 728         int                     pi_pm_held;     /* phci's kidsup incremented */
 729         int                     pi_preferred;   /* Preferred path       */
 730         void                    *pi_vprivate;   /* vhci private info    */
 731         uint_t                  pi_flags;       /* path flags */
 732 };
 733
 734 /*
 735  * pathinfo statistics:
 736  *
 737  * The mpxio architecture allows for multiple pathinfo nodes for each
 738  * client-pHCI combination.  For statistics purposes, these statistics are
 739  * aggregated into a single client-pHCI set of kstats.
 740  */
 741 struct mdi_pi_kstats {
 742         int     pi_kstat_ref;           /* # paths aggregated, also a ref cnt */
 743         kstat_t *pi_kstat_iostats;      /* mdi:iopath statistic set */
 744         kstat_t *pi_kstat_errstats;     /* error statistics */
 745 };
 746
 747 /*
 748  * pathinfo error kstat
 749  */
 750 struct pi_errs {
 751         struct kstat_named pi_softerrs;         /* "Soft" Error */
 752         struct kstat_named pi_harderrs;         /* "Hard" Error */
 753         struct kstat_named pi_transerrs;        /* Transport Errors */
 754         struct kstat_named pi_icnt_busy;        /* Interconnect Busy */
 755         struct kstat_named pi_icnt_errors;      /* Interconnect Errors */
 756         struct kstat_named pi_phci_rsrc;        /* pHCI No Resources */
 757         struct kstat_named pi_phci_localerr;    /* pHCI Local Errors */
 758         struct kstat_named pi_phci_invstate;    /* pHCI Invalid State */
 759         struct kstat_named pi_failedfrom;       /* Failover: Failed From */
 760         struct kstat_named pi_failedto;         /* Failover: Failed To */
 761 };
 762
 763 /*
 764  * increment an error counter
 765  */
 766 #define MDI_PI_ERRSTAT(pip, x) { \
 767         if (MDI_PI((pip))->pi_kstats != NULL) { \
 768                 struct pi_errs *pep; \
 769                 pep = MDI_PI(pip)->pi_kstats->pi_kstat_errstats->ks_data; \
 770                 pep->x.value.ui32++; \
 771         } \
 772 }
 773
 774 /*
 775  * error codes which can be passed to MDI_PI_ERRSTAT
 776  */
 777 #define MDI_PI_SOFTERR  pi_softerrs
 778 #define MDI_PI_HARDERR  pi_harderrs
 779 #define MDI_PI_TRANSERR pi_transerrs
 780 #define MDI_PI_ICNTBUSY pi_icnt_busy
 781 #define MDI_PI_ICNTERR  pi_icnt_errors
 782 #define MDI_PI_PHCIRSRC pi_phci_rsrc
 783 #define MDI_PI_PHCILOCL pi_phci_localerr
 784 #define MDI_PI_PHCIINVS pi_phci_invstate
 785 #define MDI_PI_FAILFROM pi_failedfrom
 786 #define MDI_PI_FAILTO   pi_failedto
 787
 788 #define MDI_PI(type)                    ((struct mdi_pathinfo *)(type))
 789
 790 #define MDI_PI_LOCK(pip)                mutex_enter(&MDI_PI(pip)->pi_mutex)
 791 #define MDI_PI_TRYLOCK(pip)             mutex_tryenter(&MDI_PI(pip)->pi_mutex)
 792 #define MDI_PI_UNLOCK(pip)              mutex_exit(&MDI_PI(pip)->pi_mutex)
 793 #ifdef  DEBUG
 794 #define MDI_PI_LOCKED(pip)              MUTEX_HELD(&MDI_PI(pip)->pi_mutex)
 795 #endif  /* DEBUG */
 796
 797 #define MDI_PI_HOLD(pip)                (++MDI_PI(pip)->pi_ref_cnt)
 798 #define MDI_PI_RELE(pip)                (--MDI_PI(pip)->pi_ref_cnt)
 799
 800 #define MDI_EXT_STATE_CHANGE            0x10000000
 801
 802
 803 #define MDI_DISABLE_OP                  0x1
 804 #define MDI_ENABLE_OP                   0x2
 805 #define MDI_BEFORE_STATE_CHANGE         0x4
 806 #define MDI_AFTER_STATE_CHANGE          0x8
 807 #define MDI_SYNC_FLAG                   0x10
 808
 809 #define MDI_PI_STATE(pip)                                               \
 810         (MDI_PI((pip))->pi_state & MDI_PATHINFO_STATE_MASK)
 811 #define MDI_PI_OLD_STATE(pip)                                           \
 812         (MDI_PI((pip))->pi_old_state & MDI_PATHINFO_STATE_MASK)
 813
 814 #define MDI_PI_EXT_STATE(pip)                                           \
 815         (MDI_PI((pip))->pi_state & MDI_PATHINFO_EXT_STATE_MASK)
 816 #define MDI_PI_OLD_EXT_STATE(pip)                                       \
 817         (MDI_PI((pip))->pi_old_state & MDI_PATHINFO_EXT_STATE_MASK)
 818
 819 #define MDI_PI_SET_TRANSIENT(pip)                                       {\
 820         ASSERT(MDI_PI_LOCKED(pip));                                     \
 821         MDI_PI(pip)->pi_state |= MDI_PATHINFO_STATE_TRANSIENT;          }
 822 #define MDI_PI_CLEAR_TRANSIENT(pip)                                     {\
 823         ASSERT(MDI_PI_LOCKED(pip));                                     \
 824         MDI_PI(pip)->pi_state &= ~MDI_PATHINFO_STATE_TRANSIENT;         }
 825 #define MDI_PI_IS_TRANSIENT(pip) \
 826         (MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_TRANSIENT)
 827
 828 #define MDI_PI_SET_USER_DISABLE(pip)                                    {\
 829         ASSERT(MDI_PI_LOCKED(pip));                                     \
 830         MDI_PI(pip)->pi_state |= MDI_PATHINFO_STATE_USER_DISABLE;       }
 831 #define MDI_PI_SET_DRV_DISABLE(pip)                                     {\
 832         ASSERT(MDI_PI_LOCKED(pip));                                     \
 833         MDI_PI(pip)->pi_state |= MDI_PATHINFO_STATE_DRV_DISABLE;        }
 834 #define MDI_PI_SET_DRV_DISABLE_TRANS(pip)                               {\
 835         ASSERT(MDI_PI_LOCKED(pip));                                     \
 836         MDI_PI(pip)->pi_state |= MDI_PATHINFO_STATE_DRV_DISABLE_TRANSIENT; }
 837
 838 #define MDI_PI_SET_USER_ENABLE(pip)                                     {\
 839         ASSERT(MDI_PI_LOCKED(pip));                                     \
 840         MDI_PI(pip)->pi_state &= ~MDI_PATHINFO_STATE_USER_DISABLE;      }
 841 #define MDI_PI_SET_DRV_ENABLE(pip)                                      {\
 842         ASSERT(MDI_PI_LOCKED(pip));                                     \
 843         MDI_PI(pip)->pi_state &= ~MDI_PATHINFO_STATE_DRV_DISABLE;       }
 844 #define MDI_PI_SET_DRV_ENABLE_TRANS(pip)                                {\
 845         ASSERT(MDI_PI_LOCKED(pip));                                     \
 846         MDI_PI(pip)->pi_state &= ~MDI_PATHINFO_STATE_DRV_DISABLE_TRANSIENT; }
 847
 848 #define MDI_PI_IS_USER_DISABLE(pip)                                     \
 849         (MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_USER_DISABLE)
 850 #define MDI_PI_IS_DRV_DISABLE(pip)                                      \
 851         (MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_DRV_DISABLE)
 852 #define MDI_PI_IS_DRV_DISABLE_TRANSIENT(pip)                            \
 853         (MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_DRV_DISABLE_TRANSIENT)
 854
 855 #define MDI_PI_IS_DISABLE(pip)                                          \
 856         (MDI_PI_IS_USER_DISABLE(pip) ||                                 \
 857         MDI_PI_IS_DRV_DISABLE(pip) ||                                   \
 858         MDI_PI_IS_DRV_DISABLE_TRANSIENT(pip))
 859
 860 #define MDI_PI_IS_INIT(pip)                                             \
 861         ((MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_MASK) ==           \
 862                 MDI_PATHINFO_STATE_INIT)
 863
 864 #define MDI_PI_IS_INITING(pip)                                          \
 865         ((MDI_PI(pip)->pi_state & ~MDI_PATHINFO_EXT_STATE_MASK) ==      \
 866                 (MDI_PATHINFO_STATE_INIT | MDI_PATHINFO_STATE_TRANSIENT))
 867
 868 #define MDI_PI_SET_INIT(pip)                                            {\
 869         ASSERT(MDI_PI_LOCKED(pip));                                     \
 870         MDI_PI(pip)->pi_state = MDI_PATHINFO_STATE_INIT;                }
 871
 872 #define MDI_PI_SET_ONLINING(pip)                                        {\
 873         uint32_t        ext_state;                                      \
 874         ASSERT(MDI_PI_LOCKED(pip));                                     \
 875         ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK; \
 876         MDI_PI(pip)->pi_old_state = MDI_PI_STATE(pip);                  \
 877         MDI_PI(pip)->pi_state =                                         \
 878         (MDI_PATHINFO_STATE_ONLINE | MDI_PATHINFO_STATE_TRANSIENT);     \
 879         MDI_PI(pip)->pi_state |= ext_state;                             }
 880
 881 #define MDI_PI_IS_ONLINING(pip)                                         \
 882         ((MDI_PI(pip)->pi_state & ~MDI_PATHINFO_EXT_STATE_MASK) ==      \
 883         (MDI_PATHINFO_STATE_ONLINE | MDI_PATHINFO_STATE_TRANSIENT))
 884
 885 #define MDI_PI_SET_ONLINE(pip)                                          {\
 886         uint32_t        ext_state;                                      \
 887         ASSERT(MDI_PI_LOCKED(pip));                                     \
 888         ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK; \
 889         MDI_PI(pip)->pi_state = MDI_PATHINFO_STATE_ONLINE;              \
 890         MDI_PI(pip)->pi_state |= ext_state;                             }
 891
 892 #define MDI_PI_IS_ONLINE(pip)                                           \
 893         ((MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_MASK) ==           \
 894         MDI_PATHINFO_STATE_ONLINE)
 895
 896 #define MDI_PI_SET_OFFLINING(pip)                                       {\
 897         uint32_t        ext_state;                                      \
 898         ASSERT(MDI_PI_LOCKED(pip));                                     \
 899         ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK; \
 900         MDI_PI(pip)->pi_old_state = MDI_PI_STATE(pip);                  \
 901         MDI_PI(pip)->pi_state =                                         \
 902         (MDI_PATHINFO_STATE_OFFLINE | MDI_PATHINFO_STATE_TRANSIENT);    \
 903         MDI_PI(pip)->pi_state |= ext_state;                             }
 904
 905 #define MDI_PI_IS_OFFLINING(pip)                                        \
 906         ((MDI_PI(pip)->pi_state & ~MDI_PATHINFO_EXT_STATE_MASK) ==      \
 907         (MDI_PATHINFO_STATE_OFFLINE | MDI_PATHINFO_STATE_TRANSIENT))
 908
 909 #define MDI_PI_SET_OFFLINE(pip)                                         {\
 910         uint32_t        ext_state;                                      \
 911         ASSERT(MDI_PI_LOCKED(pip));                                     \
 912         ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK; \
 913         MDI_PI(pip)->pi_state = MDI_PATHINFO_STATE_OFFLINE;             \
 914         MDI_PI(pip)->pi_state |= ext_state;                             }
 915
 916 #define MDI_PI_IS_OFFLINE(pip)                                          \
 917         ((MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_MASK) ==           \
 918         MDI_PATHINFO_STATE_OFFLINE)
 919
 920 #define MDI_PI_SET_STANDBYING(pip)                                      {\
 921         uint32_t        ext_state;                                      \
 922         ASSERT(MDI_PI_LOCKED(pip));                                     \
 923         ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK; \
 924         MDI_PI(pip)->pi_old_state = MDI_PI_STATE(pip);                  \
 925         MDI_PI(pip)->pi_state =                                         \
 926         (MDI_PATHINFO_STATE_STANDBY | MDI_PATHINFO_STATE_TRANSIENT);    \
 927         MDI_PI(pip)->pi_state |= ext_state;                             }
 928
 929 #define MDI_PI_SET_STANDBY(pip)                                         {\
 930         uint32_t        ext_state;                                      \
 931         ASSERT(MDI_PI_LOCKED(pip));                                     \
 932         ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK; \
 933         MDI_PI(pip)->pi_state = MDI_PATHINFO_STATE_STANDBY;             \
 934         MDI_PI(pip)->pi_state |= ext_state;                             }
 935
 936 #define MDI_PI_IS_STANDBY(pip)                                          \
 937         ((MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_MASK) ==           \
 938         MDI_PATHINFO_STATE_STANDBY)
 939
 940 #define MDI_PI_SET_FAULTING(pip)                                        {\
 941         uint32_t        ext_state;                                      \
 942         ASSERT(MDI_PI_LOCKED(pip));                                     \
 943         ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK; \
 944         MDI_PI(pip)->pi_old_state = MDI_PI_STATE(pip);                  \
 945         MDI_PI(pip)->pi_state =                                         \
 946             (MDI_PATHINFO_STATE_FAULT | MDI_PATHINFO_STATE_TRANSIENT);  \
 947         MDI_PI(pip)->pi_state |= ext_state;                             }
 948
 949 #define MDI_PI_SET_FAULT(pip)                                           {\
 950         uint32_t        ext_state;                                      \
 951         ASSERT(MDI_PI_LOCKED(pip));                                     \
 952         ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK; \
 953         MDI_PI(pip)->pi_state = MDI_PATHINFO_STATE_FAULT;               \
 954         MDI_PI(pip)->pi_state |= ext_state;                             }
 955
 956 #define MDI_PI_IS_FAULT(pip)                                            \
 957         ((MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_MASK) ==           \
 958         MDI_PATHINFO_STATE_FAULT)
 959
 960 #define MDI_PI_IS_SUSPENDED(pip)                                        \
 961         ((MDI_PI(pip))->pi_phci->ph_flags & MDI_PHCI_FLAGS_SUSPEND)
 962
 963 #define MDI_PI_FLAGS_SET_HIDDEN(pip)                                    {\
 964         ASSERT(MDI_PI_LOCKED(pip));                                     \
 965         MDI_PI(pip)->pi_flags |= MDI_PATHINFO_FLAGS_HIDDEN;             }
 966 #define MDI_PI_FLAGS_CLR_HIDDEN(pip)                                    {\
 967         ASSERT(MDI_PI_LOCKED(pip));                                     \
 968         MDI_PI(pip)->pi_flags &= ~MDI_PATHINFO_FLAGS_HIDDEN;            }
 969 #define MDI_PI_FLAGS_IS_HIDDEN(pip)                                     \
 970         ((MDI_PI(pip)->pi_flags & MDI_PATHINFO_FLAGS_HIDDEN) ==         \
 971         MDI_PATHINFO_FLAGS_HIDDEN)
 972
 973 #define MDI_PI_FLAGS_SET_DEVICE_REMOVED(pip)                            {\
 974         ASSERT(MDI_PI_LOCKED(pip));                                     \
 975         MDI_PI(pip)->pi_flags |= MDI_PATHINFO_FLAGS_DEVICE_REMOVED;     }
 976 #define MDI_PI_FLAGS_CLR_DEVICE_REMOVED(pip)                            {\
 977         ASSERT(MDI_PI_LOCKED(pip));                                     \
 978         MDI_PI(pip)->pi_flags &= ~MDI_PATHINFO_FLAGS_DEVICE_REMOVED;    }
 979 #define MDI_PI_FLAGS_IS_DEVICE_REMOVED(pip)                             \
 980         ((MDI_PI(pip)->pi_flags & MDI_PATHINFO_FLAGS_DEVICE_REMOVED) == \
 981         MDI_PATHINFO_FLAGS_DEVICE_REMOVED)
 982
 983 /*
 984  * mdi_vhcache_client, mdi_vhcache_pathinfo, and mdi_vhcache_phci structures
 985  * hold the vhci to phci client mappings of the on-disk vhci busconfig cache.
 986  */
 987
 988 /* phci structure of vhci cache */
 989 typedef struct mdi_vhcache_phci {
 990         char                    *cphci_path;    /* phci path name */
 991         uint32_t                cphci_id;       /* used when building nvlist */
 992         mdi_phci_t              *cphci_phci;    /* pointer to actual phci */
 993         struct mdi_vhcache_phci *cphci_next;    /* next in vhci phci list */
 994 } mdi_vhcache_phci_t;
 995
 996 /* pathinfo structure of vhci cache */
 997 typedef struct mdi_vhcache_pathinfo {
 998         char                    *cpi_addr;      /* path address */
 999         mdi_vhcache_phci_t      *cpi_cphci;     /* phci the path belongs to */
1000         struct mdi_pathinfo     *cpi_pip;       /* ptr to actual pathinfo */
1001         uint32_t                cpi_flags;      /* see below */
1002         struct mdi_vhcache_pathinfo *cpi_next;  /* next path for the client */
1003 } mdi_vhcache_pathinfo_t;
1004
1005 /*
1006  * cpi_flags
1007  *
1008  * MDI_CPI_HINT_PATH_DOES_NOT_EXIST - set when configuration of the path has
1009  * failed.
1010  */
1011 #define MDI_CPI_HINT_PATH_DOES_NOT_EXIST        0x0001
1012
1013 /* client structure of vhci cache */
1014 typedef struct mdi_vhcache_client {
1015         char                    *cct_name_addr; /* client address */
1016         mdi_vhcache_pathinfo_t  *cct_cpi_head;  /* client's path list head */
1017         mdi_vhcache_pathinfo_t  *cct_cpi_tail;  /* client's path list tail */
1018         struct mdi_vhcache_client *cct_next;    /* next in vhci client list */
1019 } mdi_vhcache_client_t;
1020
1021 /* vhci cache structure - one for vhci instance */
1022 typedef struct mdi_vhci_cache {
1023         mdi_vhcache_phci_t      *vhcache_phci_head;     /* phci list head */
1024         mdi_vhcache_phci_t      *vhcache_phci_tail;     /* phci list tail */
1025         mdi_vhcache_client_t    *vhcache_client_head;   /* client list head */
1026         mdi_vhcache_client_t    *vhcache_client_tail;   /* client list tail */
1027         mod_hash_t              *vhcache_client_hash;   /* client hash */
1028         int                     vhcache_flags;          /* see below */
1029         int64_t                 vhcache_clean_time;     /* last clean time */
1030         krwlock_t               vhcache_lock;           /* cache lock */
1031 } mdi_vhci_cache_t;
1032
1033 /* vhcache_flags */
1034 #define MDI_VHCI_CACHE_SETUP_DONE       0x0001  /* cache setup completed */
1035
1036 /* vhci bus config structure - one for vhci instance */
1037 typedef struct mdi_vhci_config {
1038         char                    *vhc_vhcache_filename;  /* on-disk file name */
1039         mdi_vhci_cache_t        vhc_vhcache;            /* vhci cache */
1040         kmutex_t                vhc_lock;               /* vhci config lock */
1041         kcondvar_t              vhc_cv;
1042         int                     vhc_flags;              /* see below */
1043
1044         /* flush vhci cache when lbolt reaches vhc_flush_at_ticks */
1045         clock_t                 vhc_flush_at_ticks;
1046
1047         /*
1048          * Head and tail of the client list whose paths are being configured
1049          * asynchronously. vhc_acc_count is the number of clients on this list.
1050          * vhc_acc_thrcount is the number threads running to configure
1051          * the paths for these clients.
1052          */
1053         struct mdi_async_client_config *vhc_acc_list_head;
1054         struct mdi_async_client_config *vhc_acc_list_tail;
1055         int                     vhc_acc_count;
1056         int                     vhc_acc_thrcount;
1057
1058         /* callback id - for flushing the cache during system shutdown */
1059         callb_id_t              vhc_cbid;
1060
1061         /*
1062          * vhc_path_discovery_boot -    number of times path discovery will be
1063          *                              attempted during early boot.
1064          * vhc_path_discovery_postboot  number of times path discovery will be
1065          *                              attempted during late boot.
1066          * vhc_path_discovery_cutoff_time - time at which paths were last
1067          *                              discovered  + some timeout
1068          */
1069         int                     vhc_path_discovery_boot;
1070         int                     vhc_path_discovery_postboot;
1071         int64_t                 vhc_path_discovery_cutoff_time;
1072 } mdi_vhci_config_t;
1073
1074 /* vhc_flags */
1075 #define MDI_VHC_SINGLE_THREADED         0x0001  /* config single threaded */
1076 #define MDI_VHC_EXIT                    0x0002  /* exit all config activity */
1077 #define MDI_VHC_VHCACHE_DIRTY           0x0004  /* cache dirty */
1078 #define MDI_VHC_VHCACHE_FLUSH_THREAD    0x0008  /* cache flush thead running */
1079 #define MDI_VHC_VHCACHE_FLUSH_ERROR     0x0010  /* failed to flush cache */
1080 #define MDI_VHC_READONLY_FS             0x0020  /* filesys is readonly */
1081
1082 typedef struct mdi_phys_path {
1083         char                    *phys_path;
1084         struct mdi_phys_path    *phys_path_next;
1085 } mdi_phys_path_t;
1086
1087 /*
1088  * Lookup tokens are used to cache the result of the vhci cache client lookup
1089  * operations (to reduce the number of real lookup operations).
1090  */
1091 typedef struct mdi_vhcache_lookup_token {
1092         mdi_vhcache_client_t    *lt_cct;                /* vhcache client */
1093         int64_t                 lt_cct_lookup_time;     /* last lookup time */
1094 } mdi_vhcache_lookup_token_t;
1095
1096 /* asynchronous configuration of client paths */
1097 typedef struct mdi_async_client_config {
1098         char                    *acc_ct_name;   /* client name */
1099         char                    *acc_ct_addr;   /* client address */
1100         mdi_phys_path_t         *acc_phclient_path_list_head;   /* path head */
1101         mdi_vhcache_lookup_token_t acc_token;   /* lookup token */
1102         struct mdi_async_client_config *acc_next; /* next in vhci acc list */
1103 } mdi_async_client_config_t;
1104
1105 /*
1106  * vHCI driver instance registration/unregistration
1107  *
1108  * mdi_vhci_register() is called by a vHCI driver to register itself as the
1109  * manager of devices from a particular 'class'.  This should be called from
1110  * attach(9e).
1111  *
1112  * mdi_vhci_unregister() is called from detach(9E) to unregister a vHCI
1113  * instance from the framework.
1114  */
1115 int             mdi_vhci_register(char *, dev_info_t *, mdi_vhci_ops_t *, int);
1116 int             mdi_vhci_unregister(dev_info_t *, int);
1117
1118 /*
1119  * Utility functions
1120  */
1121 int             mdi_phci_get_path_count(dev_info_t *);
1122 dev_info_t      *mdi_phci_path2devinfo(dev_info_t *, caddr_t);
1123
1124
1125 /*
1126  * Path Selection Functions:
1127  *
1128  * mdi_select_path() is called by a vHCI driver to select to which path an
1129  * I/O request should be routed.  The caller passes the 'buf' structure as
1130  * one of the parameters.  The mpxio framework uses the buf's contents to
1131  * maintain per path statistics (total I/O size / count pending).  If more
1132  * than one online path is available, the framework automatically selects
1133  * a suitable one.  If a failover operation is active for this client device
1134  * the call fails, returning MDI_BUSY.
1135  *
1136  * By default this function returns a suitable path in the 'online' state,
1137  * based on the current load balancing policy.  Currently we support
1138  * LOAD_BALANCE_NONE (Previously selected online path will continue to be
1139  * used as long as the path is usable) and LOAD_BALANCE_RR (Online paths
1140  * will be selected in a round robin fashion).  The load balancing scheme
1141  * can be configured in the vHCI driver's configuration file (driver.conf).
1142  *
1143  * vHCI drivers may override this default behavior by specifying appropriate
1144  * flags.  If start_pip is specified (non NULL), it is used as the routine's
1145  * starting point; it starts walking from there to find the next appropriate
1146  * path.
1147  *
1148  * The following values for 'flags' are currently defined, the third argument
1149  * to mdi_select_path depends on the flags used.
1150  *
1151  *   <none>:                            default, arg is pip
1152  *   MDI_SELECT_ONLINE_PATH:            select an ONLINE path preferred-first,
1153  *                                      arg is pip
1154  *   MDI_SELECT_STANDBY_PATH:           select a STANDBY path, arg is pip
1155  *   MDI_SELECT_USER_DISABLE_PATH:      select user disable for failover and
1156  *                                      auto_failback
1157  *   MDI_SELECT_PATH_INSTANCE:          select a specific path, arg is
1158  *                                      path instance
1159  *   MDI_SELECT_NO_PREFERRED:           select path without preferred-first
1160  *
1161  * The selected paths are returned in an mdi_hold_path() state (pi_ref_cnt),
1162  * caller should release the hold by calling mdi_rele_path() at the end of
1163  * operation.
1164  */
1165 int             mdi_select_path(dev_info_t *, struct buf *, int,
1166                     void *, mdi_pathinfo_t **);
1167 int             mdi_set_lb_policy(dev_info_t *, client_lb_t);
1168 int             mdi_set_lb_region_size(dev_info_t *, int);
1169 client_lb_t     mdi_get_lb_policy(dev_info_t *);
1170
1171 /*
1172  * flags for mdi_select_path() routine
1173  */
1174 #define MDI_SELECT_ONLINE_PATH          0x0001
1175 #define MDI_SELECT_STANDBY_PATH         0x0002
1176 #define MDI_SELECT_USER_DISABLE_PATH    0x0004
1177 #define MDI_SELECT_PATH_INSTANCE        0x0008
1178 #define MDI_SELECT_NO_PREFERRED         0x0010
1179
1180 /*
1181  * MDI client device utility functions
1182  */
1183 int             mdi_client_get_path_count(dev_info_t *);
1184 dev_info_t      *mdi_client_path2devinfo(dev_info_t *, caddr_t);
1185
1186 /*
1187  * Failover:
1188  *
1189  * The vHCI driver calls mdi_failover() to initiate a failover operation.
1190  * mdi_failover() calls back into the vHCI driver's vo_failover()
1191  * entry point to perform the actual failover operation.  The reason
1192  * for requiring the vHCI driver to initiate failover by calling
1193  * mdi_failover(), instead of directly executing vo_failover() itself,
1194  * is to ensure that the mdi framework can keep track of the client
1195  * state properly.  Additionally, mdi_failover() provides as a
1196  * convenience the option of performing the failover operation
1197  * synchronously or asynchronously
1198  *
1199  * Upon successful completion of the failover operation, the paths that were
1200  * previously ONLINE will be in the STANDBY state, and the newly activated
1201  * paths will be in the ONLINE state.
1202  *
1203  * The flags modifier determines whether the activation is done synchronously
1204  */
1205 int mdi_failover(dev_info_t *, dev_info_t *, int);
1206
1207 /*
1208  * Client device failover mode of operation
1209  */
1210 #define MDI_FAILOVER_SYNC       1       /* Synchronous Failover         */
1211 #define MDI_FAILOVER_ASYNC      2       /* Asynchronous Failover        */
1212
1213 /*
1214  * mdi_is_dev_supported: The pHCI driver bus_config implementation calls
1215  * mdi_is_dev_supported to determine if a child device should is supported as
1216  * a vHCI child (i.e. as a client). The method used to specify the child
1217  * device, via the cinfo argument, is by agreement between the pHCI and the
1218  * vHCI.  In the case of SCSA and scsi_vhci cinfo is a pointer to the pHCI
1219  * probe dev_info node, which is decorated with the device idenity information
1220  * necessary to determine scsi_vhci support.
1221  */
1222 int mdi_is_dev_supported(char *class, dev_info_t *pdip, void *cinfo);
1223
1224 /*
1225  * mdi_pathinfo node kstat functions.
1226  */
1227 int mdi_pi_kstat_exists(mdi_pathinfo_t *);
1228 int mdi_pi_kstat_create(mdi_pathinfo_t *pip, char *ks_name);
1229 void mdi_pi_kstat_iosupdate(mdi_pathinfo_t *, struct buf *);
1230
1231 /*
1232  * mdi_pathinfo node extended state change functions.
1233  */
1234 int mdi_pi_get_state2(mdi_pathinfo_t *, mdi_pathinfo_state_t *, uint32_t *);
1235 int mdi_pi_get_preferred(mdi_pathinfo_t *);
1236
1237 /*
1238  * mdi_pathinfo node member functions
1239  */
1240 void *mdi_pi_get_client_private(mdi_pathinfo_t *);
1241 void mdi_pi_set_client_private(mdi_pathinfo_t *, void *);
1242 void mdi_pi_set_state(mdi_pathinfo_t *, mdi_pathinfo_state_t);
1243 void mdi_pi_set_preferred(mdi_pathinfo_t *, int);
1244
1245 /* get/set vhci private data */
1246 void *mdi_client_get_vhci_private(dev_info_t *);
1247 void mdi_client_set_vhci_private(dev_info_t *, void *);
1248 void *mdi_phci_get_vhci_private(dev_info_t *);
1249 void mdi_phci_set_vhci_private(dev_info_t *, void *);
1250 void *mdi_pi_get_vhci_private(mdi_pathinfo_t *);
1251 void mdi_pi_set_vhci_private(mdi_pathinfo_t *, void *);
1252 int mdi_dc_return_dev_state(mdi_pathinfo_t *pip, struct devctl_iocdata *dcp);
1253
1254 /*
1255  * mdi_pathinfo Property utilities
1256  */
1257 int mdi_prop_size(mdi_pathinfo_t *, size_t *);
1258 int mdi_prop_pack(mdi_pathinfo_t *, char **, uint_t);
1259
1260 /* obsolete interface, to be removed */
1261 void mdi_get_next_path(dev_info_t *, mdi_pathinfo_t *, mdi_pathinfo_t **);
1262 int mdi_get_component_type(dev_info_t *);
1263
1264 #endif  /* _KERNEL */
1265
1266 #ifdef  __cplusplus
1267 }
1268 #endif
1269
1270 #endif  /* _SYS_MDI_IMPLDEFS_H */