/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
/*
 * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

/*
 * Multipath driver interface (MDI) implementation; see mdi_impl.h for a more
 * detailed discussion of the overall mpxio architecture.
 *
 * Default locking order:
 *
 * _NOTE(LOCK_ORDER(mdi_mutex, mdi_vhci:vh_phci_mutex);
 * _NOTE(LOCK_ORDER(mdi_mutex, mdi_vhci:vh_client_mutex);
 * _NOTE(LOCK_ORDER(mdi_vhci:vh_phci_mutex, mdi_phci::ph_mutex);
 * _NOTE(LOCK_ORDER(mdi_vhci:vh_client_mutex, mdi_client::ct_mutex);
 * _NOTE(LOCK_ORDER(mdi_phci::ph_mutex mdi_pathinfo::pi_mutex))
 * _NOTE(LOCK_ORDER(mdi_phci::ph_mutex mdi_client::ct_mutex))
 * _NOTE(LOCK_ORDER(mdi_client::ct_mutex mdi_pathinfo::pi_mutex))
 */

#include <sys/note.h>
#include <sys/types.h>
#include <sys/varargs.h>
#include <sys/param.h>
#include <sys/errno.h>
#include <sys/uio.h>
#include <sys/buf.h>
#include <sys/modctl.h>
#include <sys/open.h>
#include <sys/kmem.h>
#include <sys/poll.h>
#include <sys/conf.h>
#include <sys/bootconf.h>
#include <sys/cmn_err.h>
#include <sys/stat.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
#include <sys/ddipropdefs.h>
#include <sys/sunndi.h>
#include <sys/ndi_impldefs.h>
#include <sys/promif.h>
#include <sys/sunmdi.h>
#include <sys/mdi_impldefs.h>
#include <sys/taskq.h>
#include <sys/epm.h>
#include <sys/sunpm.h>
#include <sys/modhash.h>
#include <sys/disp.h>
#include <sys/autoconf.h>
#include <sys/sysmacros.h>

#ifdef	DEBUG
#include <sys/debug.h>
int	mdi_debug = 1;
int	mdi_debug_logonly = 0;
#define	MDI_DEBUG(dbglevel, pargs) if (mdi_debug >= (dbglevel))	i_mdi_log pargs
#define	MDI_WARN	CE_WARN, __func__
#define	MDI_NOTE	CE_NOTE, __func__
#define	MDI_CONT	CE_CONT, __func__
static void i_mdi_log(int, const char *, dev_info_t *, const char *, ...);
#else	/* !DEBUG */
#define	MDI_DEBUG(dbglevel, pargs)
#endif	/* DEBUG */
int	mdi_debug_consoleonly = 0;

extern pri_t	minclsyspri;
extern int	modrootloaded;

/*
 * Global mutex:
 * Protects vHCI list and structure members.
 */
kmutex_t	mdi_mutex;

/*
 * Registered vHCI class driver lists
 */
int		mdi_vhci_count;
mdi_vhci_t	*mdi_vhci_head;
mdi_vhci_t	*mdi_vhci_tail;

/*
 * Client Hash Table size
 */
static int	mdi_client_table_size = CLIENT_HASH_TABLE_SIZE;

/*
 * taskq interface definitions
 */
#define	MDI_TASKQ_N_THREADS	8
#define	MDI_TASKQ_PRI		minclsyspri
#define	MDI_TASKQ_MINALLOC	(4*mdi_taskq_n_threads)
#define	MDI_TASKQ_MAXALLOC	(500*mdi_taskq_n_threads)

taskq_t				*mdi_taskq;
static uint_t			mdi_taskq_n_threads = MDI_TASKQ_N_THREADS;

#define	TICKS_PER_SECOND	(drv_usectohz(1000000))

/*
 * The data should be "quiet" for this interval (in seconds) before the
 * vhci cached data is flushed to the disk.
 */
static int mdi_vhcache_flush_delay = 10;

/* number of seconds the vhcache flush daemon will sleep idle before exiting */
static int mdi_vhcache_flush_daemon_idle_time = 60;

/*
 * MDI falls back to discovery of all paths when a bus_config_one fails.
 * The following parameters can be used to tune this operation.
 *
 * mdi_path_discovery_boot
 *	Number of times path discovery will be attempted during early boot.
 *	Probably there is no reason to ever set this value to greater than one.
 *
 * mdi_path_discovery_postboot
 *	Number of times path discovery will be attempted after early boot.
 *	Set it to a minimum of two to allow for discovery of iscsi paths which
 *	may happen very late during booting.
 *
 * mdi_path_discovery_interval
 *	Minimum number of seconds MDI will wait between successive discovery
 *	of all paths. Set it to -1 to disable discovery of all paths.
 */
static int mdi_path_discovery_boot = 1;
static int mdi_path_discovery_postboot = 2;
static int mdi_path_discovery_interval = 10;

/*
 * number of seconds the asynchronous configuration thread will sleep idle
 * before exiting.
 */
static int mdi_async_config_idle_time = 600;

static int mdi_bus_config_cache_hash_size = 256;

/* turns off multithreaded configuration for certain operations */
static int mdi_mtc_off = 0;

/*
 * The "path" to a pathinfo node is identical to the /devices path to a
 * devinfo node had the device been enumerated under a pHCI instead of
 * a vHCI.  This pathinfo "path" is associated with a 'path_instance'.
 * This association persists across create/delete of the pathinfo nodes,
 * but not across reboot.
 */
static uint_t		mdi_pathmap_instance = 1;	/* 0 -> any path */
static int		mdi_pathmap_hash_size = 256;
static kmutex_t		mdi_pathmap_mutex;
static mod_hash_t	*mdi_pathmap_bypath;		/* "path"->instance */
static mod_hash_t	*mdi_pathmap_byinstance;	/* instance->"path" */
static mod_hash_t	*mdi_pathmap_sbyinstance;	/* inst->shortpath */

/*
 * MDI component property name/value string definitions
 */
const char 		*mdi_component_prop = "mpxio-component";
const char		*mdi_component_prop_vhci = "vhci";
const char		*mdi_component_prop_phci = "phci";
const char		*mdi_component_prop_client = "client";

/*
 * MDI client global unique identifier property name
 */
const char		*mdi_client_guid_prop = "client-guid";

/*
 * MDI client load balancing property name/value string definitions
 */
const char		*mdi_load_balance = "load-balance";
const char		*mdi_load_balance_none = "none";
const char		*mdi_load_balance_rr = "round-robin";
const char		*mdi_load_balance_lba = "logical-block";

/*
 * Obsolete vHCI class definition; to be removed after Leadville update
 */
const char *mdi_vhci_class_scsi = MDI_HCI_CLASS_SCSI;

static char vhci_greeting[] =
	"\tThere already exists one vHCI driver for class %s\n"
	"\tOnly one vHCI driver for each class is allowed\n";

/*
 * Static function prototypes
 */
static int		i_mdi_phci_offline(dev_info_t *, uint_t);
static int		i_mdi_client_offline(dev_info_t *, uint_t);
static int		i_mdi_phci_pre_detach(dev_info_t *, ddi_detach_cmd_t);
static void		i_mdi_phci_post_detach(dev_info_t *,
			    ddi_detach_cmd_t, int);
static int		i_mdi_client_pre_detach(dev_info_t *,
			    ddi_detach_cmd_t);
static void		i_mdi_client_post_detach(dev_info_t *,
			    ddi_detach_cmd_t, int);
static void		i_mdi_pm_hold_pip(mdi_pathinfo_t *);
static void		i_mdi_pm_rele_pip(mdi_pathinfo_t *);
static int 		i_mdi_lba_lb(mdi_client_t *ct,
			    mdi_pathinfo_t **ret_pip, struct buf *buf);
static void		i_mdi_pm_hold_client(mdi_client_t *, int);
static void		i_mdi_pm_rele_client(mdi_client_t *, int);
static void		i_mdi_pm_reset_client(mdi_client_t *);
static int		i_mdi_power_all_phci(mdi_client_t *);
static void		i_mdi_log_sysevent(dev_info_t *, char *, char *);


/*
 * Internal mdi_pathinfo node functions
 */
static void		i_mdi_pi_kstat_destroy(mdi_pathinfo_t *);

static mdi_vhci_t	*i_mdi_vhci_class2vhci(char *);
static mdi_vhci_t	*i_devi_get_vhci(dev_info_t *);
static mdi_phci_t	*i_devi_get_phci(dev_info_t *);
static void		i_mdi_phci_lock(mdi_phci_t *, mdi_pathinfo_t *);
static void		i_mdi_phci_unlock(mdi_phci_t *);
static mdi_pathinfo_t	*i_mdi_pi_alloc(mdi_phci_t *, char *, mdi_client_t *);
static void		i_mdi_phci_add_path(mdi_phci_t *, mdi_pathinfo_t *);
static void		i_mdi_client_add_path(mdi_client_t *, mdi_pathinfo_t *);
static void		i_mdi_pi_free(mdi_phci_t *ph, mdi_pathinfo_t *,
			    mdi_client_t *);
static void		i_mdi_phci_remove_path(mdi_phci_t *, mdi_pathinfo_t *);
static void		i_mdi_client_remove_path(mdi_client_t *,
			    mdi_pathinfo_t *);

static int		i_mdi_pi_state_change(mdi_pathinfo_t *,
			    mdi_pathinfo_state_t, int);
static int		i_mdi_pi_offline(mdi_pathinfo_t *, int);
static dev_info_t	*i_mdi_devinfo_create(mdi_vhci_t *, char *, char *,
			    char **, int);
static dev_info_t	*i_mdi_devinfo_find(mdi_vhci_t *, char *, char *);
static int		i_mdi_devinfo_remove(dev_info_t *, dev_info_t *, int);
static int		i_mdi_is_child_present(dev_info_t *, dev_info_t *);
static mdi_client_t	*i_mdi_client_alloc(mdi_vhci_t *, char *, char *);
static void		i_mdi_client_enlist_table(mdi_vhci_t *, mdi_client_t *);
static void		i_mdi_client_delist_table(mdi_vhci_t *, mdi_client_t *);
static mdi_client_t	*i_mdi_client_find(mdi_vhci_t *, char *, char *);
static void		i_mdi_client_update_state(mdi_client_t *);
static int		i_mdi_client_compute_state(mdi_client_t *,
			    mdi_phci_t *);
static void		i_mdi_client_lock(mdi_client_t *, mdi_pathinfo_t *);
static void		i_mdi_client_unlock(mdi_client_t *);
static int		i_mdi_client_free(mdi_vhci_t *, mdi_client_t *);
static mdi_client_t	*i_devi_get_client(dev_info_t *);
/*
 * NOTE: this will be removed once the NWS files are changed to use the new
 * mdi_{enable,disable}_path interfaces
 */
static int		i_mdi_pi_enable_disable(dev_info_t *, dev_info_t *,
				int, int);
static mdi_pathinfo_t 	*i_mdi_enable_disable_path(mdi_pathinfo_t *pip,
				mdi_vhci_t *vh, int flags, int op);
/*
 * Failover related function prototypes
 */
static int		i_mdi_failover(void *);

/*
 * misc internal functions
 */
static int		i_mdi_get_hash_key(char *);
static int		i_map_nvlist_error_to_mdi(int);
static void		i_mdi_report_path_state(mdi_client_t *,
			    mdi_pathinfo_t *);

static void		setup_vhci_cache(mdi_vhci_t *);
static int		destroy_vhci_cache(mdi_vhci_t *);
static int		stop_vhcache_async_threads(mdi_vhci_config_t *);
static boolean_t	stop_vhcache_flush_thread(void *, int);
static void		free_string_array(char **, int);
static void		free_vhcache_phci(mdi_vhcache_phci_t *);
static void		free_vhcache_pathinfo(mdi_vhcache_pathinfo_t *);
static void		free_vhcache_client(mdi_vhcache_client_t *);
static int		mainnvl_to_vhcache(mdi_vhci_cache_t *, nvlist_t *);
static nvlist_t		*vhcache_to_mainnvl(mdi_vhci_cache_t *);
static void		vhcache_phci_add(mdi_vhci_config_t *, mdi_phci_t *);
static void		vhcache_phci_remove(mdi_vhci_config_t *, mdi_phci_t *);
static void		vhcache_pi_add(mdi_vhci_config_t *,
			    struct mdi_pathinfo *);
static void		vhcache_pi_remove(mdi_vhci_config_t *,
			    struct mdi_pathinfo *);
static void		free_phclient_path_list(mdi_phys_path_t *);
static void		sort_vhcache_paths(mdi_vhcache_client_t *);
static int		flush_vhcache(mdi_vhci_config_t *, int);
static void		vhcache_dirty(mdi_vhci_config_t *);
static void		free_async_client_config(mdi_async_client_config_t *);
static void		single_threaded_vhconfig_enter(mdi_vhci_config_t *);
static void		single_threaded_vhconfig_exit(mdi_vhci_config_t *);
static nvlist_t		*read_on_disk_vhci_cache(char *);
extern int		fread_nvlist(char *, nvlist_t **);
extern int		fwrite_nvlist(char *, nvlist_t *);

/* called once when first vhci registers with mdi */
static void
i_mdi_init()
{
	static int initialized = 0;

	if (initialized)
		return;
	initialized = 1;

	mutex_init(&mdi_mutex, NULL, MUTEX_DEFAULT, NULL);

	/* Create our taskq resources */
	mdi_taskq = taskq_create("mdi_taskq", mdi_taskq_n_threads,
	    MDI_TASKQ_PRI, MDI_TASKQ_MINALLOC, MDI_TASKQ_MAXALLOC,
	    TASKQ_PREPOPULATE | TASKQ_CPR_SAFE);
	ASSERT(mdi_taskq != NULL);	/* taskq_create never fails */

	/* Allocate ['path_instance' <-> "path"] maps */
	mutex_init(&mdi_pathmap_mutex, NULL, MUTEX_DRIVER, NULL);
	mdi_pathmap_bypath = mod_hash_create_strhash(
	    "mdi_pathmap_bypath", mdi_pathmap_hash_size,
	    mod_hash_null_valdtor);
	mdi_pathmap_byinstance = mod_hash_create_idhash(
	    "mdi_pathmap_byinstance", mdi_pathmap_hash_size,
	    mod_hash_null_valdtor);
	mdi_pathmap_sbyinstance = mod_hash_create_idhash(
	    "mdi_pathmap_sbyinstance", mdi_pathmap_hash_size,
	    mod_hash_null_valdtor);
}

/*
 * mdi_get_component_type():
 *		Return mpxio component type
 * Return Values:
 *		MDI_COMPONENT_NONE
 *		MDI_COMPONENT_VHCI
 *		MDI_COMPONENT_PHCI
 *		MDI_COMPONENT_CLIENT
 * XXX This doesn't work under multi-level MPxIO and should be
 *	removed when clients migrate mdi_component_is_*() interfaces.
 */
int
mdi_get_component_type(dev_info_t *dip)
{
	return (DEVI(dip)->devi_mdi_component);
}

/*
 * mdi_vhci_register():
 *		Register a vHCI module with the mpxio framework
 *		mdi_vhci_register() is called by vHCI drivers to register the
 *		'class_driver' vHCI driver and its MDI entrypoints with the
 *		mpxio framework.  The vHCI driver must call this interface as
 *		part of its attach(9e) handler.
 *		Competing threads may try to attach mdi_vhci_register() as
 *		the vHCI drivers are loaded and attached as a result of pHCI
 *		driver instance registration (mdi_phci_register()) with the
 *		framework.
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
/*ARGSUSED*/
int
mdi_vhci_register(char *class, dev_info_t *vdip, mdi_vhci_ops_t *vops,
    int flags)
{
	mdi_vhci_t		*vh = NULL;

	/* Registrant can't be older */
	ASSERT(vops->vo_revision <= MDI_VHCI_OPS_REV);

#ifdef DEBUG
	/*
	 * IB nexus driver is loaded only when IB hardware is present.
	 * In order to be able to do this there is a need to drive the loading
	 * and attaching of the IB nexus driver (especially when an IB hardware
	 * is dynamically plugged in) when an IB HCA driver (PHCI)
	 * is being attached. Unfortunately this gets into the limitations
	 * of devfs as there seems to be no clean way to drive configuration
	 * of a subtree from another subtree of a devfs. Hence, do not ASSERT
	 * for IB.
	 */
	if (strcmp(class, MDI_HCI_CLASS_IB) != 0)
		ASSERT(DEVI_BUSY_OWNED(ddi_get_parent(vdip)));
#endif

	i_mdi_init();

	mutex_enter(&mdi_mutex);
	/*
	 * Scan for already registered vhci
	 */
	for (vh = mdi_vhci_head; vh != NULL; vh = vh->vh_next) {
		if (strcmp(vh->vh_class, class) == 0) {
			/*
			 * vHCI has already been created.  Check for valid
			 * vHCI ops registration.  We only support one vHCI
			 * module per class
			 */
			if (vh->vh_ops != NULL) {
				mutex_exit(&mdi_mutex);
				cmn_err(CE_NOTE, vhci_greeting, class);
				return (MDI_FAILURE);
			}
			break;
		}
	}

	/*
	 * if not yet created, create the vHCI component
	 */
	if (vh == NULL) {
		struct client_hash	*hash = NULL;
		char			*load_balance;

		/*
		 * Allocate and initialize the mdi extensions
		 */
		vh = kmem_zalloc(sizeof (mdi_vhci_t), KM_SLEEP);
		hash = kmem_zalloc(mdi_client_table_size * sizeof (*hash),
		    KM_SLEEP);
		vh->vh_client_table = hash;
		vh->vh_class = kmem_zalloc(strlen(class) + 1, KM_SLEEP);
		(void) strcpy(vh->vh_class, class);
		vh->vh_lb = LOAD_BALANCE_RR;
		if (ddi_prop_lookup_string(DDI_DEV_T_ANY, vdip,
		    0, LOAD_BALANCE_PROP, &load_balance) == DDI_SUCCESS) {
			if (strcmp(load_balance, LOAD_BALANCE_PROP_NONE) == 0) {
				vh->vh_lb = LOAD_BALANCE_NONE;
			} else if (strcmp(load_balance, LOAD_BALANCE_PROP_LBA)
				    == 0) {
				vh->vh_lb = LOAD_BALANCE_LBA;
			}
			ddi_prop_free(load_balance);
		}

		mutex_init(&vh->vh_phci_mutex, NULL, MUTEX_DEFAULT, NULL);
		mutex_init(&vh->vh_client_mutex, NULL, MUTEX_DEFAULT, NULL);

		/*
		 * Store the vHCI ops vectors
		 */
		vh->vh_dip = vdip;
		vh->vh_ops = vops;

		setup_vhci_cache(vh);

		if (mdi_vhci_head == NULL) {
			mdi_vhci_head = vh;
		}
		if (mdi_vhci_tail) {
			mdi_vhci_tail->vh_next = vh;
		}
		mdi_vhci_tail = vh;
		mdi_vhci_count++;
	}

	/*
	 * Claim the devfs node as a vhci component
	 */
	DEVI(vdip)->devi_mdi_component |= MDI_COMPONENT_VHCI;

	/*
	 * Initialize our back reference from dev_info node
	 */
	DEVI(vdip)->devi_mdi_xhci = (caddr_t)vh;
	mutex_exit(&mdi_mutex);
	return (MDI_SUCCESS);
}

/*
 * mdi_vhci_unregister():
 *		Unregister a vHCI module from mpxio framework
 *		mdi_vhci_unregister() is called from the detach(9E) entrypoint
 * 		of a vhci to unregister it from the framework.
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
/*ARGSUSED*/
int
mdi_vhci_unregister(dev_info_t *vdip, int flags)
{
	mdi_vhci_t	*found, *vh, *prev = NULL;

	ASSERT(DEVI_BUSY_OWNED(ddi_get_parent(vdip)));

	/*
	 * Check for invalid VHCI
	 */
	if ((vh = i_devi_get_vhci(vdip)) == NULL)
		return (MDI_FAILURE);

	/*
	 * Scan the list of registered vHCIs for a match
	 */
	mutex_enter(&mdi_mutex);
	for (found = mdi_vhci_head; found != NULL; found = found->vh_next) {
		if (found == vh)
			break;
		prev = found;
	}

	if (found == NULL) {
		mutex_exit(&mdi_mutex);
		return (MDI_FAILURE);
	}

	/*
	 * Check the vHCI, pHCI and client count. All the pHCIs and clients
	 * should have been unregistered, before a vHCI can be
	 * unregistered.
	 */
	MDI_VHCI_PHCI_LOCK(vh);
	if (vh->vh_refcnt || vh->vh_phci_count || vh->vh_client_count) {
		MDI_VHCI_PHCI_UNLOCK(vh);
		mutex_exit(&mdi_mutex);
		return (MDI_FAILURE);
	}
	MDI_VHCI_PHCI_UNLOCK(vh);

	if (destroy_vhci_cache(vh) != MDI_SUCCESS) {
		mutex_exit(&mdi_mutex);
		return (MDI_FAILURE);
	}

	/*
	 * Remove the vHCI from the global list
	 */
	if (vh == mdi_vhci_head) {
		mdi_vhci_head = vh->vh_next;
	} else {
		prev->vh_next = vh->vh_next;
	}
	if (vh == mdi_vhci_tail) {
		mdi_vhci_tail = prev;
	}
	mdi_vhci_count--;
	mutex_exit(&mdi_mutex);

	vh->vh_ops = NULL;
	DEVI(vdip)->devi_mdi_component &= ~MDI_COMPONENT_VHCI;
	DEVI(vdip)->devi_mdi_xhci = NULL;
	kmem_free(vh->vh_class, strlen(vh->vh_class)+1);
	kmem_free(vh->vh_client_table,
	    mdi_client_table_size * sizeof (struct client_hash));
	mutex_destroy(&vh->vh_phci_mutex);
	mutex_destroy(&vh->vh_client_mutex);

	kmem_free(vh, sizeof (mdi_vhci_t));
	return (MDI_SUCCESS);
}

/*
 * i_mdi_vhci_class2vhci():
 *		Look for a matching vHCI module given a vHCI class name
 * Return Values:
 *		Handle to a vHCI component
 *		NULL
 */
static mdi_vhci_t *
i_mdi_vhci_class2vhci(char *class)
{
	mdi_vhci_t	*vh = NULL;

	ASSERT(!MUTEX_HELD(&mdi_mutex));

	mutex_enter(&mdi_mutex);
	for (vh = mdi_vhci_head; vh != NULL; vh = vh->vh_next) {
		if (strcmp(vh->vh_class, class) == 0) {
			break;
		}
	}
	mutex_exit(&mdi_mutex);
	return (vh);
}

/*
 * i_devi_get_vhci():
 *		Utility function to get the handle to a vHCI component
 * Return Values:
 *		Handle to a vHCI component
 *		NULL
 */
mdi_vhci_t *
i_devi_get_vhci(dev_info_t *vdip)
{
	mdi_vhci_t	*vh = NULL;
	if (MDI_VHCI(vdip)) {
		vh = (mdi_vhci_t *)DEVI(vdip)->devi_mdi_xhci;
	}
	return (vh);
}

/*
 * mdi_phci_register():
 *		Register a pHCI module with mpxio framework
 *		mdi_phci_register() is called by pHCI drivers to register with
 *		the mpxio framework and a specific 'class_driver' vHCI.  The
 *		pHCI driver must call this interface as part of its attach(9e)
 *		handler.
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
/*ARGSUSED*/
int
mdi_phci_register(char *class, dev_info_t *pdip, int flags)
{
	mdi_phci_t		*ph;
	mdi_vhci_t		*vh;
	char			*data;

	/*
	 * Some subsystems, like fcp, perform pHCI registration from a
	 * different thread than the one doing the pHCI attach(9E) - the
	 * driver attach code is waiting for this other thread to complete.
	 * This means we can only ASSERT DEVI_BUSY_CHANGING of parent
	 * (indicating that some thread has done an ndi_devi_enter of parent)
	 * not DEVI_BUSY_OWNED (which would indicate that we did the enter).
	 */
	ASSERT(DEVI_BUSY_CHANGING(ddi_get_parent(pdip)));

	/*
	 * Check for mpxio-disable property. Enable mpxio if the property is
	 * missing or not set to "yes".
	 * If the property is set to "yes" then emit a brief message.
	 */
	if ((ddi_prop_lookup_string(DDI_DEV_T_ANY, pdip, 0, "mpxio-disable",
	    &data) == DDI_SUCCESS)) {
		if (strcmp(data, "yes") == 0) {
			MDI_DEBUG(1, (MDI_CONT, pdip,
			    "?multipath capabilities disabled via %s.conf.",
			    ddi_driver_name(pdip)));
			ddi_prop_free(data);
			return (MDI_FAILURE);
		}
		ddi_prop_free(data);
	}

	/*
	 * Search for a matching vHCI
	 */
	vh = (mdi_vhci_t *)i_mdi_vhci_class2vhci(class);
	if (vh == NULL) {
		return (MDI_FAILURE);
	}

	ph = kmem_zalloc(sizeof (mdi_phci_t), KM_SLEEP);
	mutex_init(&ph->ph_mutex, NULL, MUTEX_DEFAULT, NULL);
	ph->ph_dip = pdip;
	ph->ph_vhci = vh;
	ph->ph_next = NULL;
	ph->ph_unstable = 0;
	ph->ph_vprivate = 0;
	cv_init(&ph->ph_unstable_cv, NULL, CV_DRIVER, NULL);

	MDI_PHCI_LOCK(ph);
	MDI_PHCI_SET_POWER_UP(ph);
	MDI_PHCI_UNLOCK(ph);
	DEVI(pdip)->devi_mdi_component |= MDI_COMPONENT_PHCI;
	DEVI(pdip)->devi_mdi_xhci = (caddr_t)ph;

	vhcache_phci_add(vh->vh_config, ph);

	MDI_VHCI_PHCI_LOCK(vh);
	if (vh->vh_phci_head == NULL) {
		vh->vh_phci_head = ph;
	}
	if (vh->vh_phci_tail) {
		vh->vh_phci_tail->ph_next = ph;
	}
	vh->vh_phci_tail = ph;
	vh->vh_phci_count++;
	MDI_VHCI_PHCI_UNLOCK(vh);

	i_mdi_log_sysevent(pdip, class, ESC_DDI_INITIATOR_REGISTER);
	return (MDI_SUCCESS);
}

/*
 * mdi_phci_unregister():
 *		Unregister a pHCI module from mpxio framework
 *		mdi_phci_unregister() is called by the pHCI drivers from their
 *		detach(9E) handler to unregister their instances from the
 *		framework.
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
/*ARGSUSED*/
int
mdi_phci_unregister(dev_info_t *pdip, int flags)
{
	mdi_vhci_t		*vh;
	mdi_phci_t		*ph;
	mdi_phci_t		*tmp;
	mdi_phci_t		*prev = NULL;
	mdi_pathinfo_t		*pip;

	ASSERT(DEVI_BUSY_CHANGING(ddi_get_parent(pdip)));

	ph = i_devi_get_phci(pdip);
	if (ph == NULL) {
		MDI_DEBUG(1, (MDI_WARN, pdip, "!not a valid pHCI"));
		return (MDI_FAILURE);
	}

	vh = ph->ph_vhci;
	ASSERT(vh != NULL);
	if (vh == NULL) {
		MDI_DEBUG(1, (MDI_WARN, pdip, "!not a valid vHCI"));
		return (MDI_FAILURE);
	}

	MDI_VHCI_PHCI_LOCK(vh);
	tmp = vh->vh_phci_head;
	while (tmp) {
		if (tmp == ph) {
			break;
		}
		prev = tmp;
		tmp = tmp->ph_next;
	}

	if (ph == vh->vh_phci_head) {
		vh->vh_phci_head = ph->ph_next;
	} else {
		prev->ph_next = ph->ph_next;
	}

	if (ph == vh->vh_phci_tail) {
		vh->vh_phci_tail = prev;
	}

	vh->vh_phci_count--;
	MDI_VHCI_PHCI_UNLOCK(vh);

	/* Walk remaining pathinfo nodes and disassociate them from pHCI */
	MDI_PHCI_LOCK(ph);
	for (pip = (mdi_pathinfo_t *)ph->ph_path_head; pip;
	    pip = (mdi_pathinfo_t *)MDI_PI(pip)->pi_phci_link)
		MDI_PI(pip)->pi_phci = NULL;
	MDI_PHCI_UNLOCK(ph);

	i_mdi_log_sysevent(pdip, ph->ph_vhci->vh_class,
	    ESC_DDI_INITIATOR_UNREGISTER);
	vhcache_phci_remove(vh->vh_config, ph);
	cv_destroy(&ph->ph_unstable_cv);
	mutex_destroy(&ph->ph_mutex);
	kmem_free(ph, sizeof (mdi_phci_t));
	DEVI(pdip)->devi_mdi_component &= ~MDI_COMPONENT_PHCI;
	DEVI(pdip)->devi_mdi_xhci = NULL;
	return (MDI_SUCCESS);
}

/*
 * i_devi_get_phci():
 * 		Utility function to return the phci extensions.
 */
static mdi_phci_t *
i_devi_get_phci(dev_info_t *pdip)
{
	mdi_phci_t	*ph = NULL;

	if (MDI_PHCI(pdip)) {
		ph = (mdi_phci_t *)DEVI(pdip)->devi_mdi_xhci;
	}
	return (ph);
}

/*
 * Single thread mdi entry into devinfo node for modifying its children.
 * If necessary we perform an ndi_devi_enter of the vHCI before doing
 * an ndi_devi_enter of 'dip'.  We maintain circular in two parts: one
 * for the vHCI and one for the pHCI.
 */
void
mdi_devi_enter(dev_info_t *phci_dip, int *circular)
{
	dev_info_t	*vdip;
	int		vcircular, pcircular;

	/* Verify calling context */
	ASSERT(MDI_PHCI(phci_dip));
	vdip = mdi_devi_get_vdip(phci_dip);
	ASSERT(vdip);			/* A pHCI always has a vHCI */

	/*
	 * If pHCI is detaching then the framework has already entered the
	 * vHCI on a threads that went down the code path leading to
	 * detach_node().  This framework enter of the vHCI during pHCI
	 * detach is done to avoid deadlock with vHCI power management
	 * operations which enter the vHCI and the enter down the path
	 * to the pHCI. If pHCI is detaching then we piggyback this calls
	 * enter of the vHCI on frameworks vHCI enter that has already
	 * occurred - this is OK because we know that the framework thread
	 * doing detach is waiting for our completion.
	 *
	 * We should DEVI_IS_DETACHING under an enter of the parent to avoid
	 * race with detach - but we can't do that because the framework has
	 * already entered the parent, so we have some complexity instead.
	 */
	for (;;) {
		if (ndi_devi_tryenter(vdip, &vcircular)) {
			ASSERT(vcircular != -1);
			if (DEVI_IS_DETACHING(phci_dip)) {
				ndi_devi_exit(vdip, vcircular);
				vcircular = -1;
			}
			break;
		} else if (DEVI_IS_DETACHING(phci_dip)) {
			vcircular = -1;
			break;
		} else if (servicing_interrupt()) {
			/*
			 * Don't delay an interrupt (and ensure adaptive
			 * mutex inversion support).
			 */
			ndi_devi_enter(vdip, &vcircular);
			break;
		} else {
			delay_random(2);
		}
	}

	ndi_devi_enter(phci_dip, &pcircular);
	*circular = (vcircular << 16) | (pcircular & 0xFFFF);
}

/*
 * Attempt to mdi_devi_enter.
 */
int
mdi_devi_tryenter(dev_info_t *phci_dip, int *circular)
{
	dev_info_t	*vdip;
	int		vcircular, pcircular;

	/* Verify calling context */
	ASSERT(MDI_PHCI(phci_dip));
	vdip = mdi_devi_get_vdip(phci_dip);
	ASSERT(vdip);			/* A pHCI always has a vHCI */

	if (ndi_devi_tryenter(vdip, &vcircular)) {
		if (ndi_devi_tryenter(phci_dip, &pcircular)) {
			*circular = (vcircular << 16) | (pcircular & 0xFFFF);
			return (1);	/* locked */
		}
		ndi_devi_exit(vdip, vcircular);
	}
	return (0);			/* busy */
}

/*
 * Release mdi_devi_enter or successful mdi_devi_tryenter.
 */
void
mdi_devi_exit(dev_info_t *phci_dip, int circular)
{
	dev_info_t	*vdip;
	int		vcircular, pcircular;

	/* Verify calling context */
	ASSERT(MDI_PHCI(phci_dip));
	vdip = mdi_devi_get_vdip(phci_dip);
	ASSERT(vdip);			/* A pHCI always has a vHCI */

	/* extract two circular recursion values from single int */
	pcircular = (short)(circular & 0xFFFF);
	vcircular = (short)((circular >> 16) & 0xFFFF);

	ndi_devi_exit(phci_dip, pcircular);
	if (vcircular != -1)
		ndi_devi_exit(vdip, vcircular);
}

/*
 * The functions mdi_devi_exit_phci() and mdi_devi_enter_phci() are used
 * around a pHCI drivers calls to mdi_pi_online/offline, after holding
 * the pathinfo node via mdi_hold_path/mdi_rele_path, to avoid deadlock
 * with vHCI power management code during path online/offline.  Each
 * mdi_devi_exit_phci must have a matching mdi_devi_enter_phci, and both must
 * occur within the scope of an active mdi_devi_enter that establishes the
 * circular value.
 */
void
mdi_devi_exit_phci(dev_info_t *phci_dip, int circular)
{
	int		pcircular;

	/* Verify calling context */
	ASSERT(MDI_PHCI(phci_dip));

	/* Keep hold on pHCI until we reenter in mdi_devi_enter_phci */
	ndi_hold_devi(phci_dip);

	pcircular = (short)(circular & 0xFFFF);
	ndi_devi_exit(phci_dip, pcircular);
}

void
mdi_devi_enter_phci(dev_info_t *phci_dip, int *circular)
{
	int		pcircular;

	/* Verify calling context */
	ASSERT(MDI_PHCI(phci_dip));

	ndi_devi_enter(phci_dip, &pcircular);

	/* Drop hold from mdi_devi_exit_phci. */
	ndi_rele_devi(phci_dip);

	/* verify matching mdi_devi_exit_phci/mdi_devi_enter_phci use */
	ASSERT(pcircular == ((short)(*circular & 0xFFFF)));
}

/*
 * mdi_devi_get_vdip():
 *		given a pHCI dip return vHCI dip
 */
dev_info_t *
mdi_devi_get_vdip(dev_info_t *pdip)
{
	mdi_phci_t	*ph;

	ph = i_devi_get_phci(pdip);
	if (ph && ph->ph_vhci)
		return (ph->ph_vhci->vh_dip);
	return (NULL);
}

/*
 * mdi_devi_pdip_entered():
 *		Return 1 if we are vHCI and have done an ndi_devi_enter
 *		of a pHCI
 */
int
mdi_devi_pdip_entered(dev_info_t *vdip)
{
	mdi_vhci_t	*vh;
	mdi_phci_t	*ph;

	vh = i_devi_get_vhci(vdip);
	if (vh == NULL)
		return (0);

	MDI_VHCI_PHCI_LOCK(vh);
	ph = vh->vh_phci_head;
	while (ph) {
		if (ph->ph_dip && DEVI_BUSY_OWNED(ph->ph_dip)) {
			MDI_VHCI_PHCI_UNLOCK(vh);
			return (1);
		}
		ph = ph->ph_next;
	}
	MDI_VHCI_PHCI_UNLOCK(vh);
	return (0);
}

/*
 * mdi_phci_path2devinfo():
 * 		Utility function to search for a valid phci device given
 *		the devfs pathname.
 */
dev_info_t *
mdi_phci_path2devinfo(dev_info_t *vdip, caddr_t pathname)
{
	char		*temp_pathname;
	mdi_vhci_t	*vh;
	mdi_phci_t	*ph;
	dev_info_t 	*pdip = NULL;

	vh = i_devi_get_vhci(vdip);
	ASSERT(vh != NULL);

	if (vh == NULL) {
		/*
		 * Invalid vHCI component, return failure
		 */
		return (NULL);
	}

	temp_pathname = kmem_zalloc(MAXPATHLEN, KM_SLEEP);
	MDI_VHCI_PHCI_LOCK(vh);
	ph = vh->vh_phci_head;
	while (ph != NULL) {
		pdip = ph->ph_dip;
		ASSERT(pdip != NULL);
		*temp_pathname = '\0';
		(void) ddi_pathname(pdip, temp_pathname);
		if (strcmp(temp_pathname, pathname) == 0) {
			break;
		}
		ph = ph->ph_next;
	}
	if (ph == NULL) {
		pdip = NULL;
	}
	MDI_VHCI_PHCI_UNLOCK(vh);
	kmem_free(temp_pathname, MAXPATHLEN);
	return (pdip);
}

/*
 * mdi_phci_get_path_count():
 * 		get number of path information nodes associated with a given
 *		pHCI device.
 */
int
mdi_phci_get_path_count(dev_info_t *pdip)
{
	mdi_phci_t	*ph;
	int		count = 0;

	ph = i_devi_get_phci(pdip);
	if (ph != NULL) {
		count = ph->ph_path_count;
	}
	return (count);
}

/*
 * i_mdi_phci_lock():
 *		Lock a pHCI device
 * Return Values:
 *		None
 * Note:
 *		The default locking order is:
 *		_NOTE(LOCK_ORDER(mdi_phci::ph_mutex mdi_pathinfo::pi_mutex))
 *		But there are number of situations where locks need to be
 *		grabbed in reverse order.  This routine implements try and lock
 *		mechanism depending on the requested parameter option.
 */
static void
i_mdi_phci_lock(mdi_phci_t *ph, mdi_pathinfo_t *pip)
{
	if (pip) {
		/* Reverse locking is requested. */
		while (MDI_PHCI_TRYLOCK(ph) == 0) {
			if (servicing_interrupt()) {
				MDI_PI_HOLD(pip);
				MDI_PI_UNLOCK(pip);
				MDI_PHCI_LOCK(ph);
				MDI_PI_LOCK(pip);
				MDI_PI_RELE(pip);
				break;
			} else {
				/*
				 * tryenter failed. Try to grab again
				 * after a small delay
				 */
				MDI_PI_HOLD(pip);
				MDI_PI_UNLOCK(pip);
				delay_random(2);
				MDI_PI_LOCK(pip);
				MDI_PI_RELE(pip);
			}
		}
	} else {
		MDI_PHCI_LOCK(ph);
	}
}

/*
 * i_mdi_phci_unlock():
 *		Unlock the pHCI component
 */
static void
i_mdi_phci_unlock(mdi_phci_t *ph)
{
	MDI_PHCI_UNLOCK(ph);
}

/*
 * i_mdi_devinfo_create():
 *		create client device's devinfo node
 * Return Values:
 *		dev_info
 *		NULL
 * Notes:
 */
static dev_info_t *
i_mdi_devinfo_create(mdi_vhci_t *vh, char *name, char *guid,
	char **compatible, int ncompatible)
{
	dev_info_t *cdip = NULL;

	ASSERT(MDI_VHCI_CLIENT_LOCKED(vh));

	/* Verify for duplicate entry */
	cdip = i_mdi_devinfo_find(vh, name, guid);
	ASSERT(cdip == NULL);
	if (cdip) {
		cmn_err(CE_WARN,
		    "i_mdi_devinfo_create: client %s@%s already exists",
			name ? name : "", guid ? guid : "");
	}

	ndi_devi_alloc_sleep(vh->vh_dip, name, DEVI_SID_NODEID, &cdip);
	if (cdip == NULL)
		goto fail;

	/*
	 * Create component type and Global unique identifier
	 * properties
	 */
	if (ndi_prop_update_string(DDI_DEV_T_NONE, cdip,
	    MDI_CLIENT_GUID_PROP, guid) != DDI_PROP_SUCCESS) {
		goto fail;
	}

	/* Decorate the node with compatible property */
	if (compatible &&
	    (ndi_prop_update_string_array(DDI_DEV_T_NONE, cdip,
	    "compatible", compatible, ncompatible) != DDI_PROP_SUCCESS)) {
		goto fail;
	}

	return (cdip);

fail:
	if (cdip) {
		(void) ndi_prop_remove_all(cdip);
		(void) ndi_devi_free(cdip);
	}
	return (NULL);
}

/*
 * i_mdi_devinfo_find():
 *		Find a matching devinfo node for given client node name
 *		and its guid.
 * Return Values:
 *		Handle to a dev_info node or NULL
 */
static dev_info_t *
i_mdi_devinfo_find(mdi_vhci_t *vh, caddr_t name, char *guid)
{
	char			*data;
	dev_info_t 		*cdip = NULL;
	dev_info_t 		*ndip = NULL;
	int			circular;

	ndi_devi_enter(vh->vh_dip, &circular);
	ndip = (dev_info_t *)DEVI(vh->vh_dip)->devi_child;
	while ((cdip = ndip) != NULL) {
		ndip = (dev_info_t *)DEVI(cdip)->devi_sibling;

		if (strcmp(DEVI(cdip)->devi_node_name, name)) {
			continue;
		}

		if (ddi_prop_lookup_string(DDI_DEV_T_ANY, cdip,
		    DDI_PROP_DONTPASS, MDI_CLIENT_GUID_PROP,
		    &data) != DDI_PROP_SUCCESS) {
			continue;
		}

		if (strcmp(data, guid) != 0) {
			ddi_prop_free(data);
			continue;
		}
		ddi_prop_free(data);
		break;
	}
	ndi_devi_exit(vh->vh_dip, circular);
	return (cdip);
}

/*
 * i_mdi_devinfo_remove():
 *		Remove a client device node
 */
static int
i_mdi_devinfo_remove(dev_info_t *vdip, dev_info_t *cdip, int flags)
{
	int	rv = MDI_SUCCESS;

	if (i_mdi_is_child_present(vdip, cdip) == MDI_SUCCESS ||
	    (flags & MDI_CLIENT_FLAGS_DEV_NOT_SUPPORTED)) {
		rv = ndi_devi_offline(cdip, NDI_DEVFS_CLEAN | NDI_DEVI_REMOVE);
		if (rv != NDI_SUCCESS) {
			MDI_DEBUG(1, (MDI_NOTE, cdip,
			    "!failed: cdip %p", (void *)cdip));
		}
		/*
		 * Convert to MDI error code
		 */
		switch (rv) {
		case NDI_SUCCESS:
			rv = MDI_SUCCESS;
			break;
		case NDI_BUSY:
			rv = MDI_BUSY;
			break;
		default:
			rv = MDI_FAILURE;
			break;
		}
	}
	return (rv);
}

/*
 * i_devi_get_client()
 *		Utility function to get mpxio component extensions
 */
static mdi_client_t *
i_devi_get_client(dev_info_t *cdip)
{
	mdi_client_t	*ct = NULL;

	if (MDI_CLIENT(cdip)) {
		ct = (mdi_client_t *)DEVI(cdip)->devi_mdi_client;
	}
	return (ct);
}

/*
 * i_mdi_is_child_present():
 *		Search for the presence of client device dev_info node
 */
static int
i_mdi_is_child_present(dev_info_t *vdip, dev_info_t *cdip)
{
	int		rv = MDI_FAILURE;
	struct dev_info	*dip;
	int		circular;

	ndi_devi_enter(vdip, &circular);
	dip = DEVI(vdip)->devi_child;
	while (dip) {
		if (dip == DEVI(cdip)) {
			rv = MDI_SUCCESS;
			break;
		}
		dip = dip->devi_sibling;
	}
	ndi_devi_exit(vdip, circular);
	return (rv);
}


/*
 * i_mdi_client_lock():
 *		Grab client component lock
 * Return Values:
 *		None
 * Note:
 *		The default locking order is:
 *		_NOTE(LOCK_ORDER(mdi_client::ct_mutex mdi_pathinfo::pi_mutex))
 *		But there are number of situations where locks need to be
 *		grabbed in reverse order.  This routine implements try and lock
 *		mechanism depending on the requested parameter option.
 */
static void
i_mdi_client_lock(mdi_client_t *ct, mdi_pathinfo_t *pip)
{
	if (pip) {
		/*
		 * Reverse locking is requested.
		 */
		while (MDI_CLIENT_TRYLOCK(ct) == 0) {
			if (servicing_interrupt()) {
				MDI_PI_HOLD(pip);
				MDI_PI_UNLOCK(pip);
				MDI_CLIENT_LOCK(ct);
				MDI_PI_LOCK(pip);
				MDI_PI_RELE(pip);
				break;
			} else {
				/*
				 * tryenter failed. Try to grab again
				 * after a small delay
				 */
				MDI_PI_HOLD(pip);
				MDI_PI_UNLOCK(pip);
				delay_random(2);
				MDI_PI_LOCK(pip);
				MDI_PI_RELE(pip);
			}
		}
	} else {
		MDI_CLIENT_LOCK(ct);
	}
}

/*
 * i_mdi_client_unlock():
 *		Unlock a client component
 */
static void
i_mdi_client_unlock(mdi_client_t *ct)
{
	MDI_CLIENT_UNLOCK(ct);
}

/*
 * i_mdi_client_alloc():
 * 		Allocate and initialize a client structure.  Caller should
 *		hold the vhci client lock.
 * Return Values:
 *		Handle to a client component
 */
/*ARGSUSED*/
static mdi_client_t *
i_mdi_client_alloc(mdi_vhci_t *vh, char *name, char *lguid)
{
	mdi_client_t	*ct;

	ASSERT(MDI_VHCI_CLIENT_LOCKED(vh));

	/*
	 * Allocate and initialize a component structure.
	 */
	ct = kmem_zalloc(sizeof (*ct), KM_SLEEP);
	mutex_init(&ct->ct_mutex, NULL, MUTEX_DEFAULT, NULL);
	ct->ct_hnext = NULL;
	ct->ct_hprev = NULL;
	ct->ct_dip = NULL;
	ct->ct_vhci = vh;
	ct->ct_drvname = kmem_alloc(strlen(name) + 1, KM_SLEEP);
	(void) strcpy(ct->ct_drvname, name);
	ct->ct_guid = kmem_alloc(strlen(lguid) + 1, KM_SLEEP);
	(void) strcpy(ct->ct_guid, lguid);
	ct->ct_cprivate = NULL;
	ct->ct_vprivate = NULL;
	ct->ct_flags = 0;
	ct->ct_state = MDI_CLIENT_STATE_FAILED;
	MDI_CLIENT_LOCK(ct);
	MDI_CLIENT_SET_OFFLINE(ct);
	MDI_CLIENT_SET_DETACH(ct);
	MDI_CLIENT_SET_POWER_UP(ct);
	MDI_CLIENT_UNLOCK(ct);
	ct->ct_failover_flags = 0;
	ct->ct_failover_status = 0;
	cv_init(&ct->ct_failover_cv, NULL, CV_DRIVER, NULL);
	ct->ct_unstable = 0;
	cv_init(&ct->ct_unstable_cv, NULL, CV_DRIVER, NULL);
	cv_init(&ct->ct_powerchange_cv, NULL, CV_DRIVER, NULL);
	ct->ct_lb = vh->vh_lb;
	ct->ct_lb_args =  kmem_zalloc(sizeof (client_lb_args_t), KM_SLEEP);
	ct->ct_lb_args->region_size = LOAD_BALANCE_DEFAULT_REGION_SIZE;
	ct->ct_path_count = 0;
	ct->ct_path_head = NULL;
	ct->ct_path_tail = NULL;
	ct->ct_path_last = NULL;

	/*
	 * Add this client component to our client hash queue
	 */
	i_mdi_client_enlist_table(vh, ct);
	return (ct);
}

/*
 * i_mdi_client_enlist_table():
 *		Attach the client device to the client hash table. Caller
 *		should hold the vhci client lock.
 */
static void
i_mdi_client_enlist_table(mdi_vhci_t *vh, mdi_client_t *ct)
{
	int 			index;
	struct client_hash	*head;

	ASSERT(MDI_VHCI_CLIENT_LOCKED(vh));

	index = i_mdi_get_hash_key(ct->ct_guid);
	head = &vh->vh_client_table[index];
	ct->ct_hnext = (mdi_client_t *)head->ct_hash_head;
	head->ct_hash_head = ct;
	head->ct_hash_count++;
	vh->vh_client_count++;
}

/*
 * i_mdi_client_delist_table():
 *		Attach the client device to the client hash table.
 *		Caller should hold the vhci client lock.
 */
static void
i_mdi_client_delist_table(mdi_vhci_t *vh, mdi_client_t *ct)
{
	int			index;
	char			*guid;
	struct client_hash 	*head;
	mdi_client_t		*next;
	mdi_client_t		*last;

	ASSERT(MDI_VHCI_CLIENT_LOCKED(vh));

	guid = ct->ct_guid;
	index = i_mdi_get_hash_key(guid);
	head = &vh->vh_client_table[index];

	last = NULL;
	next = (mdi_client_t *)head->ct_hash_head;
	while (next != NULL) {
		if (next == ct) {
			break;
		}
		last = next;
		next = next->ct_hnext;
	}

	if (next) {
		head->ct_hash_count--;
		if (last == NULL) {
			head->ct_hash_head = ct->ct_hnext;
		} else {
			last->ct_hnext = ct->ct_hnext;
		}
		ct->ct_hnext = NULL;
		vh->vh_client_count--;
	}
}


/*
 * i_mdi_client_free():
 *		Free a client component
 */
static int
i_mdi_client_free(mdi_vhci_t *vh, mdi_client_t *ct)
{
	int		rv = MDI_SUCCESS;
	int		flags = ct->ct_flags;
	dev_info_t	*cdip;
	dev_info_t	*vdip;

	ASSERT(MDI_VHCI_CLIENT_LOCKED(vh));

	vdip = vh->vh_dip;
	cdip = ct->ct_dip;

	(void) ndi_prop_remove(DDI_DEV_T_NONE, cdip, MDI_CLIENT_GUID_PROP);
	DEVI(cdip)->devi_mdi_component &= ~MDI_COMPONENT_CLIENT;
	DEVI(cdip)->devi_mdi_client = NULL;

	/*
	 * Clear out back ref. to dev_info_t node
	 */
	ct->ct_dip = NULL;

	/*
	 * Remove this client from our hash queue
	 */
	i_mdi_client_delist_table(vh, ct);

	/*
	 * Uninitialize and free the component
	 */
	kmem_free(ct->ct_drvname, strlen(ct->ct_drvname) + 1);
	kmem_free(ct->ct_guid, strlen(ct->ct_guid) + 1);
	kmem_free(ct->ct_lb_args, sizeof (client_lb_args_t));
	cv_destroy(&ct->ct_failover_cv);
	cv_destroy(&ct->ct_unstable_cv);
	cv_destroy(&ct->ct_powerchange_cv);
	mutex_destroy(&ct->ct_mutex);
	kmem_free(ct, sizeof (*ct));

	if (cdip != NULL) {
		MDI_VHCI_CLIENT_UNLOCK(vh);
		(void) i_mdi_devinfo_remove(vdip, cdip, flags);
		MDI_VHCI_CLIENT_LOCK(vh);
	}
	return (rv);
}

/*
 * i_mdi_client_find():
 * 		Find the client structure corresponding to a given guid
 *		Caller should hold the vhci client lock.
 */
static mdi_client_t *
i_mdi_client_find(mdi_vhci_t *vh, char *cname, char *guid)
{
	int			index;
	struct client_hash	*head;
	mdi_client_t		*ct;

	ASSERT(MDI_VHCI_CLIENT_LOCKED(vh));

	index = i_mdi_get_hash_key(guid);
	head = &vh->vh_client_table[index];

	ct = head->ct_hash_head;
	while (ct != NULL) {
		if (strcmp(ct->ct_guid, guid) == 0 &&
		    (cname == NULL || strcmp(ct->ct_drvname, cname) == 0)) {
			break;
		}
		ct = ct->ct_hnext;
	}
	return (ct);
}

/*
 * i_mdi_client_update_state():
 *		Compute and update client device state
 * Notes:
 *		A client device can be in any of three possible states:
 *
 *		MDI_CLIENT_STATE_OPTIMAL - Client in optimal state with more
 *		one online/standby paths. Can tolerate failures.
 *		MDI_CLIENT_STATE_DEGRADED - Client device in degraded state with
 *		no alternate paths available as standby. A failure on the online
 *		would result in loss of access to device data.
 *		MDI_CLIENT_STATE_FAILED - Client device in failed state with
 *		no paths available to access the device.
 */
static void
i_mdi_client_update_state(mdi_client_t *ct)
{
	int state;

	ASSERT(MDI_CLIENT_LOCKED(ct));
	state = i_mdi_client_compute_state(ct, NULL);
	MDI_CLIENT_SET_STATE(ct, state);
}

/*
 * i_mdi_client_compute_state():
 *		Compute client device state
 *
 *		mdi_phci_t *	Pointer to pHCI structure which should
 *				while computing the new value.  Used by
 *				i_mdi_phci_offline() to find the new
 *				client state after DR of a pHCI.
 */
static int
i_mdi_client_compute_state(mdi_client_t *ct, mdi_phci_t *ph)
{
	int		state;
	int		online_count = 0;
	int		standby_count = 0;
	mdi_pathinfo_t	*pip, *next;

	ASSERT(MDI_CLIENT_LOCKED(ct));
	pip = ct->ct_path_head;
	while (pip != NULL) {
		MDI_PI_LOCK(pip);
		next = (mdi_pathinfo_t *)MDI_PI(pip)->pi_client_link;
		if (MDI_PI(pip)->pi_phci == ph) {
			MDI_PI_UNLOCK(pip);
			pip = next;
			continue;
		}

		if ((MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_MASK)
				== MDI_PATHINFO_STATE_ONLINE)
			online_count++;
		else if ((MDI_PI(pip)->pi_state & MDI_PATHINFO_STATE_MASK)
				== MDI_PATHINFO_STATE_STANDBY)
			standby_count++;
		MDI_PI_UNLOCK(pip);
		pip = next;
	}

	if (online_count == 0) {
		if (standby_count == 0) {
			state = MDI_CLIENT_STATE_FAILED;
			MDI_DEBUG(2, (MDI_NOTE, ct->ct_dip,
			    "client state failed: ct = %p", (void *)ct));
		} else if (standby_count == 1) {
			state = MDI_CLIENT_STATE_DEGRADED;
		} else {
			state = MDI_CLIENT_STATE_OPTIMAL;
		}
	} else if (online_count == 1) {
		if (standby_count == 0) {
			state = MDI_CLIENT_STATE_DEGRADED;
		} else {
			state = MDI_CLIENT_STATE_OPTIMAL;
		}
	} else {
		state = MDI_CLIENT_STATE_OPTIMAL;
	}
	return (state);
}

/*
 * i_mdi_client2devinfo():
 *		Utility function
 */
dev_info_t *
i_mdi_client2devinfo(mdi_client_t *ct)
{
	return (ct->ct_dip);
}

/*
 * mdi_client_path2_devinfo():
 * 		Given the parent devinfo and child devfs pathname, search for
 *		a valid devfs node handle.
 */
dev_info_t *
mdi_client_path2devinfo(dev_info_t *vdip, char *pathname)
{
	dev_info_t 	*cdip = NULL;
	dev_info_t 	*ndip = NULL;
	char		*temp_pathname;
	int		circular;

	/*
	 * Allocate temp buffer
	 */
	temp_pathname = kmem_zalloc(MAXPATHLEN, KM_SLEEP);

	/*
	 * Lock parent against changes
	 */
	ndi_devi_enter(vdip, &circular);
	ndip = (dev_info_t *)DEVI(vdip)->devi_child;
	while ((cdip = ndip) != NULL) {
		ndip = (dev_info_t *)DEVI(cdip)->devi_sibling;

		*temp_pathname = '\0';
		(void) ddi_pathname(cdip, temp_pathname);
		if (strcmp(temp_pathname, pathname) == 0) {
			break;
		}
	}
	/*
	 * Release devinfo lock
	 */
	ndi_devi_exit(vdip, circular);

	/*
	 * Free the temp buffer
	 */
	kmem_free(temp_pathname, MAXPATHLEN);
	return (cdip);
}

/*
 * mdi_client_get_path_count():
 * 		Utility function to get number of path information nodes
 *		associated with a given client device.
 */
int
mdi_client_get_path_count(dev_info_t *cdip)
{
	mdi_client_t	*ct;
	int		count = 0;

	ct = i_devi_get_client(cdip);
	if (ct != NULL) {
		count = ct->ct_path_count;
	}
	return (count);
}


/*
 * i_mdi_get_hash_key():
 * 		Create a hash using strings as keys
 *
 */
static int
i_mdi_get_hash_key(char *str)
{
	uint32_t	g, hash = 0;
	char		*p;

	for (p = str; *p != '\0'; p++) {
		g = *p;
		hash += g;
	}
	return (hash % (CLIENT_HASH_TABLE_SIZE - 1));
}

/*
 * mdi_get_lb_policy():
 * 		Get current load balancing policy for a given client device
 */
client_lb_t
mdi_get_lb_policy(dev_info_t *cdip)
{
	client_lb_t	lb = LOAD_BALANCE_NONE;
	mdi_client_t	*ct;

	ct = i_devi_get_client(cdip);
	if (ct != NULL) {
		lb = ct->ct_lb;
	}
	return (lb);
}

/*
 * mdi_set_lb_region_size():
 * 		Set current region size for the load-balance
 */
int
mdi_set_lb_region_size(dev_info_t *cdip, int region_size)
{
	mdi_client_t	*ct;
	int		rv = MDI_FAILURE;

	ct = i_devi_get_client(cdip);
	if (ct != NULL && ct->ct_lb_args != NULL) {
		ct->ct_lb_args->region_size = region_size;
		rv = MDI_SUCCESS;
	}
	return (rv);
}

/*
 * mdi_Set_lb_policy():
 * 		Set current load balancing policy for a given client device
 */
int
mdi_set_lb_policy(dev_info_t *cdip, client_lb_t lb)
{
	mdi_client_t	*ct;
	int		rv = MDI_FAILURE;

	ct = i_devi_get_client(cdip);
	if (ct != NULL) {
		ct->ct_lb = lb;
		rv = MDI_SUCCESS;
	}
	return (rv);
}

/*
 * mdi_failover():
 *		failover function called by the vHCI drivers to initiate
 *		a failover operation.  This is typically due to non-availability
 *		of online paths to route I/O requests.  Failover can be
 *		triggered through user application also.
 *
 *		The vHCI driver calls mdi_failover() to initiate a failover
 *		operation. mdi_failover() calls back into the vHCI driver's
 *		vo_failover() entry point to perform the actual failover
 *		operation.  The reason for requiring the vHCI driver to
 *		initiate failover by calling mdi_failover(), instead of directly
 *		executing vo_failover() itself, is to ensure that the mdi
 *		framework can keep track of the client state properly.
 *		Additionally, mdi_failover() provides as a convenience the
 *		option of performing the failover operation synchronously or
 *		asynchronously
 *
 *		Upon successful completion of the failover operation, the
 *		paths that were previously ONLINE will be in the STANDBY state,
 *		and the newly activated paths will be in the ONLINE state.
 *
 *		The flags modifier determines whether the activation is done
 *		synchronously: MDI_FAILOVER_SYNC
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 *		MDI_BUSY
 */
/*ARGSUSED*/
int
mdi_failover(dev_info_t *vdip, dev_info_t *cdip, int flags)
{
	int			rv;
	mdi_client_t		*ct;

	ct = i_devi_get_client(cdip);
	ASSERT(ct != NULL);
	if (ct == NULL) {
		/* cdip is not a valid client device. Nothing more to do. */
		return (MDI_FAILURE);
	}

	MDI_CLIENT_LOCK(ct);

	if (MDI_CLIENT_IS_PATH_FREE_IN_PROGRESS(ct)) {
		/* A path to the client is being freed */
		MDI_CLIENT_UNLOCK(ct);
		return (MDI_BUSY);
	}


	if (MDI_CLIENT_IS_FAILED(ct)) {
		/*
		 * Client is in failed state. Nothing more to do.
		 */
		MDI_CLIENT_UNLOCK(ct);
		return (MDI_FAILURE);
	}

	if (MDI_CLIENT_IS_FAILOVER_IN_PROGRESS(ct)) {
		/*
		 * Failover is already in progress; return BUSY
		 */
		MDI_CLIENT_UNLOCK(ct);
		return (MDI_BUSY);
	}
	/*
	 * Make sure that mdi_pathinfo node state changes are processed.
	 * We do not allow failovers to progress while client path state
	 * changes are in progress
	 */
	if (ct->ct_unstable) {
		if (flags == MDI_FAILOVER_ASYNC) {
			MDI_CLIENT_UNLOCK(ct);
			return (MDI_BUSY);
		} else {
			while (ct->ct_unstable)
				cv_wait(&ct->ct_unstable_cv, &ct->ct_mutex);
		}
	}

	/*
	 * Client device is in stable state. Before proceeding, perform sanity
	 * checks again.
	 */
	if ((MDI_CLIENT_IS_DETACHED(ct)) || (MDI_CLIENT_IS_FAILED(ct)) ||
	    (!i_ddi_devi_attached(ct->ct_dip))) {
		/*
		 * Client is in failed state. Nothing more to do.
		 */
		MDI_CLIENT_UNLOCK(ct);
		return (MDI_FAILURE);
	}

	/*
	 * Set the client state as failover in progress.
	 */
	MDI_CLIENT_SET_FAILOVER_IN_PROGRESS(ct);
	ct->ct_failover_flags = flags;
	MDI_CLIENT_UNLOCK(ct);

	if (flags == MDI_FAILOVER_ASYNC) {
		/*
		 * Submit the initiate failover request via CPR safe
		 * taskq threads.
		 */
		(void) taskq_dispatch(mdi_taskq, (task_func_t *)i_mdi_failover,
		    ct, KM_SLEEP);
		return (MDI_ACCEPT);
	} else {
		/*
		 * Synchronous failover mode.  Typically invoked from the user
		 * land.
		 */
		rv = i_mdi_failover(ct);
	}
	return (rv);
}

/*
 * i_mdi_failover():
 *		internal failover function. Invokes vHCI drivers failover
 *		callback function and process the failover status
 * Return Values:
 *		None
 *
 * Note: A client device in failover state can not be detached or freed.
 */
static int
i_mdi_failover(void *arg)
{
	int		rv = MDI_SUCCESS;
	mdi_client_t	*ct = (mdi_client_t *)arg;
	mdi_vhci_t	*vh = ct->ct_vhci;

	ASSERT(!MDI_CLIENT_LOCKED(ct));

	if (vh->vh_ops->vo_failover != NULL) {
		/*
		 * Call vHCI drivers callback routine
		 */
		rv = (*vh->vh_ops->vo_failover)(vh->vh_dip, ct->ct_dip,
		    ct->ct_failover_flags);
	}

	MDI_CLIENT_LOCK(ct);
	MDI_CLIENT_CLEAR_FAILOVER_IN_PROGRESS(ct);

	/*
	 * Save the failover return status
	 */
	ct->ct_failover_status = rv;

	/*
	 * As a result of failover, client status would have been changed.
	 * Update the client state and wake up anyone waiting on this client
	 * device.
	 */
	i_mdi_client_update_state(ct);

	cv_broadcast(&ct->ct_failover_cv);
	MDI_CLIENT_UNLOCK(ct);
	return (rv);
}

/*
 * Load balancing is logical block.
 * IOs within the range described by region_size
 * would go on the same path. This would improve the
 * performance by cache-hit on some of the RAID devices.
 * Search only for online paths(At some point we
 * may want to balance across target ports).
 * If no paths are found then default to round-robin.
 */
static int
i_mdi_lba_lb(mdi_client_t *ct, mdi_pathinfo_t **ret_pip, struct buf *bp)
{
	int		path_index = -1;
	int		online_path_count = 0;
	int		online_nonpref_path_count = 0;
	int 		region_size = ct->ct_lb_args->region_size;
	mdi_pathinfo_t	*pip;
	mdi_pathinfo_t	*next;
	int		preferred, path_cnt;

	pip = ct->ct_path_head;
	while (pip) {
		MDI_PI_LOCK(pip);
		if (MDI_PI(pip)->pi_state ==
		    MDI_PATHINFO_STATE_ONLINE && MDI_PI(pip)->pi_preferred) {
			online_path_count++;
		} else if (MDI_PI(pip)->pi_state ==
		    MDI_PATHINFO_STATE_ONLINE && !MDI_PI(pip)->pi_preferred) {
			online_nonpref_path_count++;
		}
		next = (mdi_pathinfo_t *)
		    MDI_PI(pip)->pi_client_link;
		MDI_PI_UNLOCK(pip);
		pip = next;
	}
	/* if found any online/preferred then use this type */
	if (online_path_count > 0) {
		path_cnt = online_path_count;
		preferred = 1;
	} else if (online_nonpref_path_count > 0) {
		path_cnt = online_nonpref_path_count;
		preferred = 0;
	} else {
		path_cnt = 0;
	}
	if (path_cnt) {
		path_index = (bp->b_blkno >> region_size) % path_cnt;
		pip = ct->ct_path_head;
		while (pip && path_index != -1) {
			MDI_PI_LOCK(pip);
			if (path_index == 0 &&
			    (MDI_PI(pip)->pi_state ==
			    MDI_PATHINFO_STATE_ONLINE) &&
				MDI_PI(pip)->pi_preferred == preferred) {
				MDI_PI_HOLD(pip);
				MDI_PI_UNLOCK(pip);
				*ret_pip = pip;
				return (MDI_SUCCESS);
			}
			path_index --;
			next = (mdi_pathinfo_t *)
			    MDI_PI(pip)->pi_client_link;
			MDI_PI_UNLOCK(pip);
			pip = next;
		}
		MDI_DEBUG(4, (MDI_NOTE, ct->ct_dip,
		    "lba %llx: path %s %p",
		    bp->b_lblkno, mdi_pi_spathname(pip), (void *)pip));
	}
	return (MDI_FAILURE);
}

/*
 * mdi_select_path():
 *		select a path to access a client device.
 *
 *		mdi_select_path() function is called by the vHCI drivers to
 *		select a path to route the I/O request to.  The caller passes
 *		the block I/O data transfer structure ("buf") as one of the
 *		parameters.  The mpxio framework uses the buf structure
 *		contents to maintain per path statistics (total I/O size /
 *		count pending).  If more than one online paths are available to
 *		select, the framework automatically selects a suitable path
 *		for routing I/O request. If a failover operation is active for
 *		this client device the call shall be failed with MDI_BUSY error
 *		code.
 *
 *		By default this function returns a suitable path in online
 *		state based on the current load balancing policy.  Currently
 *		we support LOAD_BALANCE_NONE (Previously selected online path
 *		will continue to be used till the path is usable) and
 *		LOAD_BALANCE_RR (Online paths will be selected in a round
 *		robin fashion), LOAD_BALANCE_LB(Online paths will be selected
 *		based on the logical block).  The load balancing
 *		through vHCI drivers configuration file (driver.conf).
 *
 *		vHCI drivers may override this default behavior by specifying
 *		appropriate flags.  The meaning of the thrid argument depends
 *		on the flags specified. If MDI_SELECT_PATH_INSTANCE is set
 *		then the argument is the "path instance" of the path to select.
 *		If MDI_SELECT_PATH_INSTANCE is not set then the argument is
 *		"start_pip". A non NULL "start_pip" is the starting point to
 *		walk and find the next appropriate path.  The following values
 *		are currently defined: MDI_SELECT_ONLINE_PATH (to select an
 *		ONLINE path) and/or MDI_SELECT_STANDBY_PATH (to select an
 *		STANDBY path).
 *
 *		The non-standard behavior is used by the scsi_vhci driver,
 *		whenever it has to use a STANDBY/FAULTED path.  Eg. during
 *		attach of client devices (to avoid an unnecessary failover
 *		when the STANDBY path comes up first), during failover
 *		(to activate a STANDBY path as ONLINE).
 *
 *		The selected path is returned in a a mdi_hold_path() state
 *		(pi_ref_cnt). Caller should release the hold by calling
 *		mdi_rele_path().
 *
 * Return Values:
 *		MDI_SUCCESS	- Completed successfully
 *		MDI_BUSY 	- Client device is busy failing over
 *		MDI_NOPATH	- Client device is online, but no valid path are
 *				  available to access this client device
 *		MDI_FAILURE	- Invalid client device or state
 *		MDI_DEVI_ONLINING
 *				- Client device (struct dev_info state) is in
 *				  onlining state.
 */

/*ARGSUSED*/
int
mdi_select_path(dev_info_t *cdip, struct buf *bp, int flags,
    void *arg, mdi_pathinfo_t **ret_pip)
{
	mdi_client_t	*ct;
	mdi_pathinfo_t	*pip;
	mdi_pathinfo_t	*next;
	mdi_pathinfo_t	*head;
	mdi_pathinfo_t	*start;
	client_lb_t	lbp;	/* load balancing policy */
	int		sb = 1;	/* standard behavior */
	int		preferred = 1;	/* preferred path */
	int		cond, cont = 1;
	int		retry = 0;
	mdi_pathinfo_t	*start_pip;	/* request starting pathinfo */
	int		path_instance;	/* request specific path instance */

	/* determine type of arg based on flags */
	if (flags & MDI_SELECT_PATH_INSTANCE) {
		path_instance = (int)(intptr_t)arg;
		start_pip = NULL;
	} else {
		path_instance = 0;
		start_pip = (mdi_pathinfo_t *)arg;
	}

	if (flags != 0) {
		/*
		 * disable default behavior
		 */
		sb = 0;
	}

	*ret_pip = NULL;
	ct = i_devi_get_client(cdip);
	if (ct == NULL) {
		/* mdi extensions are NULL, Nothing more to do */
		return (MDI_FAILURE);
	}

	MDI_CLIENT_LOCK(ct);

	if (sb) {
		if (MDI_CLIENT_IS_FAILED(ct)) {
			/*
			 * Client is not ready to accept any I/O requests.
			 * Fail this request.
			 */
			MDI_DEBUG(2, (MDI_NOTE, cdip,
			    "client state offline ct = %p", (void *)ct));
			MDI_CLIENT_UNLOCK(ct);
			return (MDI_FAILURE);
		}

		if (MDI_CLIENT_IS_FAILOVER_IN_PROGRESS(ct)) {
			/*
			 * Check for Failover is in progress. If so tell the
			 * caller that this device is busy.
			 */
			MDI_DEBUG(2, (MDI_NOTE, cdip,
			    "client failover in progress ct = %p",
			    (void *)ct));
			MDI_CLIENT_UNLOCK(ct);
			return (MDI_BUSY);
		}

		/*
		 * Check to see whether the client device is attached.
		 * If not so, let the vHCI driver manually select a path
		 * (standby) and let the probe/attach process to continue.
		 */
		if (MDI_CLIENT_IS_DETACHED(ct) || !i_ddi_devi_attached(cdip)) {
			MDI_DEBUG(4, (MDI_NOTE, cdip,
			    "devi is onlining ct = %p", (void *)ct));
			MDI_CLIENT_UNLOCK(ct);
			return (MDI_DEVI_ONLINING);
		}
	}

	/*
	 * Cache in the client list head.  If head of the list is NULL
	 * return MDI_NOPATH
	 */
	head = ct->ct_path_head;
	if (head == NULL) {
		MDI_CLIENT_UNLOCK(ct);
		return (MDI_NOPATH);
	}

	/* Caller is specifying a specific pathinfo path by path_instance */
	if (path_instance) {
		/* search for pathinfo with correct path_instance */
		for (pip = head;
		    pip && (mdi_pi_get_path_instance(pip) != path_instance);
		    pip = (mdi_pathinfo_t *)MDI_PI(pip)->pi_client_link)
			;

		/* If path can't be selected then MDI_NOPATH is returned. */
		if (pip == NULL) {
			MDI_CLIENT_UNLOCK(ct);
			return (MDI_NOPATH);
		}

		/*
		 * Verify state of path. When asked to select a specific
		 * path_instance, we select the requested path in any
		 * state (ONLINE, OFFLINE, STANDBY, FAULT) other than INIT.
		 * We don't however select paths where the pHCI has detached.
		 * NOTE: last pathinfo node of an opened client device may
		 * exist in an OFFLINE state after the pHCI associated with
		 * that path has detached (but pi_phci will be NULL if that
		 * has occurred).
		 */
		MDI_PI_LOCK(pip);
		if ((MDI_PI(pip)->pi_state == MDI_PATHINFO_STATE_INIT) ||
		    (MDI_PI(pip)->pi_phci == NULL)) {
			MDI_PI_UNLOCK(pip);
			MDI_CLIENT_UNLOCK(ct);
			return (MDI_FAILURE);
		}

		/* Return MDI_BUSY if we have a transient condition */
		if (MDI_PI_IS_TRANSIENT(pip)) {
			MDI_PI_UNLOCK(pip);
			MDI_CLIENT_UNLOCK(ct);
			return (MDI_BUSY);
		}

		/*
		 * Return the path in hold state. Caller should release the
		 * lock by calling mdi_rele_path()
		 */
		MDI_PI_HOLD(pip);
		MDI_PI_UNLOCK(pip);
		*ret_pip = pip;
		MDI_CLIENT_UNLOCK(ct);
		return (MDI_SUCCESS);
	}

	/*
	 * for non default behavior, bypass current
	 * load balancing policy and always use LOAD_BALANCE_RR
	 * except that the start point will be adjusted based
	 * on the provided start_pip
	 */
	lbp = sb ? ct->ct_lb : LOAD_BALANCE_RR;

	switch (lbp) {
	case LOAD_BALANCE_NONE:
		/*
		 * Load balancing is None  or Alternate path mode
		 * Start looking for a online mdi_pathinfo node starting from
		 * last known selected path
		 */
		preferred = 1;
		pip = (mdi_pathinfo_t *)ct->ct_path_last;
		if (pip == NULL) {
			pip = head;
		}
		start = pip;
		do {
			MDI_PI_LOCK(pip);
			/*
			 * No need to explicitly check if the path is disabled.
			 * Since we are checking for state == ONLINE and the
			 * same variable is used for DISABLE/ENABLE information.
			 */
			if ((MDI_PI(pip)->pi_state  ==
				MDI_PATHINFO_STATE_ONLINE) &&
				preferred == MDI_PI(pip)->pi_preferred) {
				/*
				 * Return the path in hold state. Caller should
				 * release the lock by calling mdi_rele_path()
				 */
				MDI_PI_HOLD(pip);
				MDI_PI_UNLOCK(pip);
				ct->ct_path_last = pip;
				*ret_pip = pip;
				MDI_CLIENT_UNLOCK(ct);
				return (MDI_SUCCESS);
			}

			/*
			 * Path is busy.
			 */
			if (MDI_PI_IS_DRV_DISABLE_TRANSIENT(pip) ||
			    MDI_PI_IS_TRANSIENT(pip))
				retry = 1;
			/*
			 * Keep looking for a next available online path
			 */
			next = (mdi_pathinfo_t *)MDI_PI(pip)->pi_client_link;
			if (next == NULL) {
				next = head;
			}
			MDI_PI_UNLOCK(pip);
			pip = next;
			if (start == pip && preferred) {
				preferred = 0;
			} else if (start == pip && !preferred) {
				cont = 0;
			}
		} while (cont);
		break;

	case LOAD_BALANCE_LBA:
		/*
		 * Make sure we are looking
		 * for an online path. Otherwise, if it is for a STANDBY
		 * path request, it will go through and fetch an ONLINE
		 * path which is not desirable.
		 */
		if ((ct->ct_lb_args != NULL) &&
			    (ct->ct_lb_args->region_size) && bp &&
				(sb || (flags == MDI_SELECT_ONLINE_PATH))) {
			if (i_mdi_lba_lb(ct, ret_pip, bp)
				    == MDI_SUCCESS) {
				MDI_CLIENT_UNLOCK(ct);
				return (MDI_SUCCESS);
			}
		}
		/* FALLTHROUGH */
	case LOAD_BALANCE_RR:
		/*
		 * Load balancing is Round Robin. Start looking for a online
		 * mdi_pathinfo node starting from last known selected path
		 * as the start point.  If override flags are specified,
		 * process accordingly.
		 * If the search is already in effect(start_pip not null),
		 * then lets just use the same path preference to continue the
		 * traversal.
		 */

		if (start_pip != NULL) {
			preferred = MDI_PI(start_pip)->pi_preferred;
		} else {
			preferred = 1;
		}

		start = sb ? (mdi_pathinfo_t *)ct->ct_path_last : start_pip;
		if (start == NULL) {
			pip = head;
		} else {
			pip = (mdi_pathinfo_t *)MDI_PI(start)->pi_client_link;
			if (pip == NULL) {
				if ( flags & MDI_SELECT_NO_PREFERRED) {
					/*
					 * Return since we hit the end of list
					 */
					MDI_CLIENT_UNLOCK(ct);
					return (MDI_NOPATH);
				}

				if (!sb) {
					if (preferred == 0) {
						/*
						 * Looks like we have completed
						 * the traversal as preferred
						 * value is 0. Time to bail out.
						 */
						*ret_pip = NULL;
						MDI_CLIENT_UNLOCK(ct);
						return (MDI_NOPATH);
					} else {
						/*
						 * Looks like we reached the
						 * end of the list. Lets enable
						 * traversal of non preferred
						 * paths.
						 */
						preferred = 0;
					}
				}
				pip = head;
			}
		}
		start = pip;
		do {
			MDI_PI_LOCK(pip);
			if (sb) {
				cond = ((MDI_PI(pip)->pi_state ==
				    MDI_PATHINFO_STATE_ONLINE &&
					MDI_PI(pip)->pi_preferred ==
						preferred) ? 1 : 0);
			} else {
				if (flags == MDI_SELECT_ONLINE_PATH) {
					cond = ((MDI_PI(pip)->pi_state ==
					    MDI_PATHINFO_STATE_ONLINE &&
						MDI_PI(pip)->pi_preferred ==
						preferred) ? 1 : 0);
				} else if (flags == MDI_SELECT_STANDBY_PATH) {
					cond = ((MDI_PI(pip)->pi_state ==
					    MDI_PATHINFO_STATE_STANDBY &&
						MDI_PI(pip)->pi_preferred ==
						preferred) ? 1 : 0);
				} else if (flags == (MDI_SELECT_ONLINE_PATH |
				    MDI_SELECT_STANDBY_PATH)) {
					cond = (((MDI_PI(pip)->pi_state ==
					    MDI_PATHINFO_STATE_ONLINE ||
					    (MDI_PI(pip)->pi_state ==
					    MDI_PATHINFO_STATE_STANDBY)) &&
						MDI_PI(pip)->pi_preferred ==
						preferred) ? 1 : 0);
				} else if (flags ==
					(MDI_SELECT_STANDBY_PATH |
					MDI_SELECT_ONLINE_PATH |
					MDI_SELECT_USER_DISABLE_PATH)) {
					cond = (((MDI_PI(pip)->pi_state ==
					    MDI_PATHINFO_STATE_ONLINE ||
					    (MDI_PI(pip)->pi_state ==
					    MDI_PATHINFO_STATE_STANDBY) ||
						(MDI_PI(pip)->pi_state ==
					    (MDI_PATHINFO_STATE_ONLINE|
					    MDI_PATHINFO_STATE_USER_DISABLE)) ||
						(MDI_PI(pip)->pi_state ==
					    (MDI_PATHINFO_STATE_STANDBY |
					    MDI_PATHINFO_STATE_USER_DISABLE)))&&
						MDI_PI(pip)->pi_preferred ==
						preferred) ? 1 : 0);
				} else if (flags ==
				    (MDI_SELECT_STANDBY_PATH |
				    MDI_SELECT_ONLINE_PATH |
				    MDI_SELECT_NO_PREFERRED)) {
					cond = (((MDI_PI(pip)->pi_state ==
					    MDI_PATHINFO_STATE_ONLINE) ||
					    (MDI_PI(pip)->pi_state ==
					    MDI_PATHINFO_STATE_STANDBY))
					    ? 1 : 0);
				} else {
					cond = 0;
				}
			}
			/*
			 * No need to explicitly check if the path is disabled.
			 * Since we are checking for state == ONLINE and the
			 * same variable is used for DISABLE/ENABLE information.
			 */
			if (cond) {
				/*
				 * Return the path in hold state. Caller should
				 * release the lock by calling mdi_rele_path()
				 */
				MDI_PI_HOLD(pip);
				MDI_PI_UNLOCK(pip);
				if (sb)
					ct->ct_path_last = pip;
				*ret_pip = pip;
				MDI_CLIENT_UNLOCK(ct);
				return (MDI_SUCCESS);
			}
			/*
			 * Path is busy.
			 */
			if (MDI_PI_IS_DRV_DISABLE_TRANSIENT(pip) ||
			    MDI_PI_IS_TRANSIENT(pip))
				retry = 1;

			/*
			 * Keep looking for a next available online path
			 */
do_again:
			next = (mdi_pathinfo_t *)MDI_PI(pip)->pi_client_link;
			if (next == NULL) {
				if ( flags & MDI_SELECT_NO_PREFERRED) {
					/*
					 * Bail out since we hit the end of list
					 */
					MDI_PI_UNLOCK(pip);
					break;
				}

				if (!sb) {
					if (preferred == 1) {
						/*
						 * Looks like we reached the
						 * end of the list. Lets enable
						 * traversal of non preferred
						 * paths.
						 */
						preferred = 0;
						next = head;
					} else {
						/*
						 * We have done both the passes
						 * Preferred as well as for
						 * Non-preferred. Bail out now.
						 */
						cont = 0;
					}
				} else {
					/*
					 * Standard behavior case.
					 */
					next = head;
				}
			}
			MDI_PI_UNLOCK(pip);
			if (cont == 0) {
				break;
			}
			pip = next;

			if (!sb) {
				/*
				 * We need to handle the selection of
				 * non-preferred path in the following
				 * case:
				 *
				 * +------+   +------+   +------+   +-----+
				 * | A : 1| - | B : 1| - | C : 0| - |NULL |
				 * +------+   +------+   +------+   +-----+
				 *
				 * If we start the search with B, we need to
				 * skip beyond B to pick C which is non -
				 * preferred in the second pass. The following
				 * test, if true, will allow us to skip over
				 * the 'start'(B in the example) to select
				 * other non preferred elements.
				 */
				if ((start_pip != NULL) && (start_pip == pip) &&
				    (MDI_PI(start_pip)->pi_preferred
				    != preferred)) {
					/*
					 * try again after going past the start
					 * pip
					 */
					MDI_PI_LOCK(pip);
					goto do_again;
				}
			} else {
				/*
				 * Standard behavior case
				 */
				if (start == pip && preferred) {
					/* look for nonpreferred paths */
					preferred = 0;
				} else if (start == pip && !preferred) {
					/*
					 * Exit condition
					 */
					cont = 0;
				}
			}
		} while (cont);
		break;
	}

	MDI_CLIENT_UNLOCK(ct);
	if (retry == 1) {
		return (MDI_BUSY);
	} else {
		return (MDI_NOPATH);
	}
}

/*
 * For a client, return the next available path to any phci
 *
 * Note:
 *		Caller should hold the branch's devinfo node to get a consistent
 *		snap shot of the mdi_pathinfo nodes.
 *
 *		Please note that even the list is stable the mdi_pathinfo
 *		node state and properties are volatile.  The caller should lock
 *		and unlock the nodes by calling mdi_pi_lock() and
 *		mdi_pi_unlock() functions to get a stable properties.
 *
 *		If there is a need to use the nodes beyond the hold of the
 *		devinfo node period (For ex. I/O), then mdi_pathinfo node
 *		need to be held against unexpected removal by calling
 *		mdi_hold_path() and should be released by calling
 *		mdi_rele_path() on completion.
 */
mdi_pathinfo_t *
mdi_get_next_phci_path(dev_info_t *ct_dip, mdi_pathinfo_t *pip)
{
	mdi_client_t *ct;

	if (!MDI_CLIENT(ct_dip))
		return (NULL);

	/*
	 * Walk through client link
	 */
	ct = (mdi_client_t *)DEVI(ct_dip)->devi_mdi_client;
	ASSERT(ct != NULL);

	if (pip == NULL)
		return ((mdi_pathinfo_t *)ct->ct_path_head);

	return ((mdi_pathinfo_t *)MDI_PI(pip)->pi_client_link);
}

/*
 * For a phci, return the next available path to any client
 * Note: ditto mdi_get_next_phci_path()
 */
mdi_pathinfo_t *
mdi_get_next_client_path(dev_info_t *ph_dip, mdi_pathinfo_t *pip)
{
	mdi_phci_t *ph;

	if (!MDI_PHCI(ph_dip))
		return (NULL);

	/*
	 * Walk through pHCI link
	 */
	ph = (mdi_phci_t *)DEVI(ph_dip)->devi_mdi_xhci;
	ASSERT(ph != NULL);

	if (pip == NULL)
		return ((mdi_pathinfo_t *)ph->ph_path_head);

	return ((mdi_pathinfo_t *)MDI_PI(pip)->pi_phci_link);
}

/*
 * mdi_hold_path():
 *		Hold the mdi_pathinfo node against unwanted unexpected free.
 * Return Values:
 *		None
 */
void
mdi_hold_path(mdi_pathinfo_t *pip)
{
	if (pip) {
		MDI_PI_LOCK(pip);
		MDI_PI_HOLD(pip);
		MDI_PI_UNLOCK(pip);
	}
}


/*
 * mdi_rele_path():
 *		Release the mdi_pathinfo node which was selected
 *		through mdi_select_path() mechanism or manually held by
 *		calling mdi_hold_path().
 * Return Values:
 *		None
 */
void
mdi_rele_path(mdi_pathinfo_t *pip)
{
	if (pip) {
		MDI_PI_LOCK(pip);
		MDI_PI_RELE(pip);
		if (MDI_PI(pip)->pi_ref_cnt == 0) {
			cv_broadcast(&MDI_PI(pip)->pi_ref_cv);
		}
		MDI_PI_UNLOCK(pip);
	}
}

/*
 * mdi_pi_lock():
 * 		Lock the mdi_pathinfo node.
 * Note:
 *		The caller should release the lock by calling mdi_pi_unlock()
 */
void
mdi_pi_lock(mdi_pathinfo_t *pip)
{
	ASSERT(pip != NULL);
	if (pip) {
		MDI_PI_LOCK(pip);
	}
}


/*
 * mdi_pi_unlock():
 * 		Unlock the mdi_pathinfo node.
 * Note:
 *		The mdi_pathinfo node should have been locked with mdi_pi_lock()
 */
void
mdi_pi_unlock(mdi_pathinfo_t *pip)
{
	ASSERT(pip != NULL);
	if (pip) {
		MDI_PI_UNLOCK(pip);
	}
}

/*
 * mdi_pi_find():
 *		Search the list of mdi_pathinfo nodes attached to the
 *		pHCI/Client device node whose path address matches "paddr".
 *		Returns a pointer to the mdi_pathinfo node if a matching node is
 *		found.
 * Return Values:
 *		mdi_pathinfo node handle
 *		NULL
 * Notes:
 *		Caller need not hold any locks to call this function.
 */
mdi_pathinfo_t *
mdi_pi_find(dev_info_t *pdip, char *caddr, char *paddr)
{
	mdi_phci_t		*ph;
	mdi_vhci_t		*vh;
	mdi_client_t		*ct;
	mdi_pathinfo_t		*pip = NULL;

	MDI_DEBUG(2, (MDI_NOTE, pdip,
	    "caddr@%s paddr@%s", caddr ? caddr : "", paddr ? paddr : ""));
	if ((pdip == NULL) || (paddr == NULL)) {
		return (NULL);
	}
	ph = i_devi_get_phci(pdip);
	if (ph == NULL) {
		/*
		 * Invalid pHCI device, Nothing more to do.
		 */
		MDI_DEBUG(2, (MDI_WARN, pdip, "invalid phci"));
		return (NULL);
	}

	vh = ph->ph_vhci;
	if (vh == NULL) {
		/*
		 * Invalid vHCI device, Nothing more to do.
		 */
		MDI_DEBUG(2, (MDI_WARN, pdip, "invalid vhci"));
		return (NULL);
	}

	/*
	 * Look for pathinfo node identified by paddr.
	 */
	if (caddr == NULL) {
		/*
		 * Find a mdi_pathinfo node under pHCI list for a matching
		 * unit address.
		 */
		MDI_PHCI_LOCK(ph);
		if (MDI_PHCI_IS_OFFLINE(ph)) {
			MDI_DEBUG(2, (MDI_WARN, pdip,
			    "offline phci %p", (void *)ph));
			MDI_PHCI_UNLOCK(ph);
			return (NULL);
		}
		pip = (mdi_pathinfo_t *)ph->ph_path_head;

		while (pip != NULL) {
			if (strcmp(MDI_PI(pip)->pi_addr, paddr) == 0) {
				break;
			}
			pip = (mdi_pathinfo_t *)MDI_PI(pip)->pi_phci_link;
		}
		MDI_PHCI_UNLOCK(ph);
		MDI_DEBUG(2, (MDI_NOTE, pdip,
		    "found %s %p", mdi_pi_spathname(pip), (void *)pip));
		return (pip);
	}

	/*
	 * XXX - Is the rest of the code in this function really necessary?
	 * The consumers of mdi_pi_find() can search for the desired pathinfo
	 * node by calling mdi_pi_find(pdip, NULL, paddr). Irrespective of
	 * whether the search is based on the pathinfo nodes attached to
	 * the pHCI or the client node, the result will be the same.
	 */

	/*
	 * Find the client device corresponding to 'caddr'
	 */
	MDI_VHCI_CLIENT_LOCK(vh);

	/*
	 * XXX - Passing NULL to the following function works as long as the
	 * the client addresses (caddr) are unique per vhci basis.
	 */
	ct = i_mdi_client_find(vh, NULL, caddr);
	if (ct == NULL) {
		/*
		 * Client not found, Obviously mdi_pathinfo node has not been
		 * created yet.
		 */
		MDI_VHCI_CLIENT_UNLOCK(vh);
		MDI_DEBUG(2, (MDI_NOTE, pdip,
		    "client not found for caddr @%s", caddr ? caddr : ""));
		return (NULL);
	}

	/*
	 * Hold the client lock and look for a mdi_pathinfo node with matching
	 * pHCI and paddr
	 */
	MDI_CLIENT_LOCK(ct);

	/*
	 * Release the global mutex as it is no more needed. Note: We always
	 * respect the locking order while acquiring.
	 */
	MDI_VHCI_CLIENT_UNLOCK(vh);

	pip = (mdi_pathinfo_t *)ct->ct_path_head;
	while (pip != NULL) {
		/*
		 * Compare the unit address
		 */
		if ((MDI_PI(pip)->pi_phci == ph) &&
		    strcmp(MDI_PI(pip)->pi_addr, paddr) == 0) {
			break;
		}
		pip = (mdi_pathinfo_t *)MDI_PI(pip)->pi_client_link;
	}
	MDI_CLIENT_UNLOCK(ct);
	MDI_DEBUG(2, (MDI_NOTE, pdip,
	    "found: %s %p", mdi_pi_spathname(pip), (void *)pip));
	return (pip);
}

/*
 * mdi_pi_alloc():
 *		Allocate and initialize a new instance of a mdi_pathinfo node.
 *		The mdi_pathinfo node returned by this function identifies a
 *		unique device path is capable of having properties attached
 *		and passed to mdi_pi_online() to fully attach and online the
 *		path and client device node.
 *		The mdi_pathinfo node returned by this function must be
 *		destroyed using mdi_pi_free() if the path is no longer
 *		operational or if the caller fails to attach a client device
 *		node when calling mdi_pi_online(). The framework will not free
 *		the resources allocated.
 *		This function can be called from both interrupt and kernel
 *		contexts.  DDI_NOSLEEP flag should be used while calling
 *		from interrupt contexts.
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 *		MDI_NOMEM
 */
/*ARGSUSED*/
int
mdi_pi_alloc_compatible(dev_info_t *pdip, char *cname, char *caddr, char *paddr,
    char **compatible, int ncompatible, int flags, mdi_pathinfo_t **ret_pip)
{
	mdi_vhci_t	*vh;
	mdi_phci_t	*ph;
	mdi_client_t	*ct;
	mdi_pathinfo_t	*pip = NULL;
	dev_info_t	*cdip;
	int		rv = MDI_NOMEM;
	int		path_allocated = 0;

	MDI_DEBUG(2, (MDI_NOTE, pdip,
	    "cname %s: caddr@%s paddr@%s",
	    cname ? cname : "", caddr ? caddr : "", paddr ? paddr : ""));

	if (pdip == NULL || cname == NULL || caddr == NULL || paddr == NULL ||
	    ret_pip == NULL) {
		/* Nothing more to do */
		return (MDI_FAILURE);
	}

	*ret_pip = NULL;

	/* No allocations on detaching pHCI */
	if (DEVI_IS_DETACHING(pdip)) {
		/* Invalid pHCI device, return failure */
		MDI_DEBUG(1, (MDI_WARN, pdip,
		    "!detaching pHCI=%p", (void *)pdip));
		return (MDI_FAILURE);
	}

	ph = i_devi_get_phci(pdip);
	ASSERT(ph != NULL);
	if (ph == NULL) {
		/* Invalid pHCI device, return failure */
		MDI_DEBUG(1, (MDI_WARN, pdip,
		    "!invalid pHCI=%p", (void *)pdip));
		return (MDI_FAILURE);
	}

	MDI_PHCI_LOCK(ph);
	vh = ph->ph_vhci;
	if (vh == NULL) {
		/* Invalid vHCI device, return failure */
		MDI_DEBUG(1, (MDI_WARN, pdip,
		    "!invalid vHCI=%p", (void *)pdip));
		MDI_PHCI_UNLOCK(ph);
		return (MDI_FAILURE);
	}

	if (MDI_PHCI_IS_READY(ph) == 0) {
		/*
		 * Do not allow new node creation when pHCI is in
		 * offline/suspended states
		 */
		MDI_DEBUG(1, (MDI_WARN, pdip,
		    "pHCI=%p is not ready", (void *)ph));
		MDI_PHCI_UNLOCK(ph);
		return (MDI_BUSY);
	}
	MDI_PHCI_UNSTABLE(ph);
	MDI_PHCI_UNLOCK(ph);

	/* look for a matching client, create one if not found */
	MDI_VHCI_CLIENT_LOCK(vh);
	ct = i_mdi_client_find(vh, cname, caddr);
	if (ct == NULL) {
		ct = i_mdi_client_alloc(vh, cname, caddr);
		ASSERT(ct != NULL);
	}

	if (ct->ct_dip == NULL) {
		/*
		 * Allocate a devinfo node
		 */
		ct->ct_dip = i_mdi_devinfo_create(vh, cname, caddr,
		    compatible, ncompatible);
		if (ct->ct_dip == NULL) {
			(void) i_mdi_client_free(vh, ct);
			goto fail;
		}
	}
	cdip = ct->ct_dip;

	DEVI(cdip)->devi_mdi_component |= MDI_COMPONENT_CLIENT;
	DEVI(cdip)->devi_mdi_client = (caddr_t)ct;

	MDI_CLIENT_LOCK(ct);
	pip = (mdi_pathinfo_t *)ct->ct_path_head;
	while (pip != NULL) {
		/*
		 * Compare the unit address
		 */
		if ((MDI_PI(pip)->pi_phci == ph) &&
		    strcmp(MDI_PI(pip)->pi_addr, paddr) == 0) {
			break;
		}
		pip = (mdi_pathinfo_t *)MDI_PI(pip)->pi_client_link;
	}
	MDI_CLIENT_UNLOCK(ct);

	if (pip == NULL) {
		/*
		 * This is a new path for this client device.  Allocate and
		 * initialize a new pathinfo node
		 */
		pip = i_mdi_pi_alloc(ph, paddr, ct);
		ASSERT(pip != NULL);
		path_allocated = 1;
	}
	rv = MDI_SUCCESS;

fail:
	/*
	 * Release the global mutex.
	 */
	MDI_VHCI_CLIENT_UNLOCK(vh);

	/*
	 * Mark the pHCI as stable
	 */
	MDI_PHCI_LOCK(ph);
	MDI_PHCI_STABLE(ph);
	MDI_PHCI_UNLOCK(ph);
	*ret_pip = pip;

	MDI_DEBUG(2, (MDI_NOTE, pdip,
	    "alloc %s %p", mdi_pi_spathname(pip), (void *)pip));

	if (path_allocated)
		vhcache_pi_add(vh->vh_config, MDI_PI(pip));

	return (rv);
}

/*ARGSUSED*/
int
mdi_pi_alloc(dev_info_t *pdip, char *cname, char *caddr, char *paddr,
    int flags, mdi_pathinfo_t **ret_pip)
{
	return (mdi_pi_alloc_compatible(pdip, cname, caddr, paddr, NULL, 0,
	    flags, ret_pip));
}

/*
 * i_mdi_pi_alloc():
 *		Allocate a mdi_pathinfo node and add to the pHCI path list
 * Return Values:
 *		mdi_pathinfo
 */
/*ARGSUSED*/
static mdi_pathinfo_t *
i_mdi_pi_alloc(mdi_phci_t *ph, char *paddr, mdi_client_t *ct)
{
	mdi_pathinfo_t	*pip;
	int		ct_circular;
	int		ph_circular;
	static char	path[MAXPATHLEN];	/* mdi_pathmap_mutex protects */
	char		*path_persistent;
	int		path_instance;
	mod_hash_val_t	hv;

	ASSERT(MDI_VHCI_CLIENT_LOCKED(ph->ph_vhci));

	pip = kmem_zalloc(sizeof (struct mdi_pathinfo), KM_SLEEP);
	mutex_init(&MDI_PI(pip)->pi_mutex, NULL, MUTEX_DEFAULT, NULL);
	MDI_PI(pip)->pi_state = MDI_PATHINFO_STATE_INIT |
	    MDI_PATHINFO_STATE_TRANSIENT;

	if (MDI_PHCI_IS_USER_DISABLED(ph))
		MDI_PI_SET_USER_DISABLE(pip);

	if (MDI_PHCI_IS_DRV_DISABLED_TRANSIENT(ph))
		MDI_PI_SET_DRV_DISABLE_TRANS(pip);

	if (MDI_PHCI_IS_DRV_DISABLED(ph))
		MDI_PI_SET_DRV_DISABLE(pip);

	MDI_PI(pip)->pi_old_state = MDI_PATHINFO_STATE_INIT;
	cv_init(&MDI_PI(pip)->pi_state_cv, NULL, CV_DEFAULT, NULL);
	MDI_PI(pip)->pi_client = ct;
	MDI_PI(pip)->pi_phci = ph;
	MDI_PI(pip)->pi_addr = kmem_alloc(strlen(paddr) + 1, KM_SLEEP);
	(void) strcpy(MDI_PI(pip)->pi_addr, paddr);

        /*
	 * We form the "path" to the pathinfo node, and see if we have
	 * already allocated a 'path_instance' for that "path".  If so,
	 * we use the already allocated 'path_instance'.  If not, we
	 * allocate a new 'path_instance' and associate it with a copy of
	 * the "path" string (which is never freed). The association
	 * between a 'path_instance' this "path" string persists until
	 * reboot.
	 */
        mutex_enter(&mdi_pathmap_mutex);
	(void) ddi_pathname(ph->ph_dip, path);
	(void) sprintf(path + strlen(path), "/%s@%s",
	    mdi_pi_get_node_name(pip), mdi_pi_get_addr(pip));
        if (mod_hash_find(mdi_pathmap_bypath, (mod_hash_key_t)path, &hv) == 0) {
                path_instance = (uint_t)(intptr_t)hv;
        } else {
		/* allocate a new 'path_instance' and persistent "path" */
		path_instance = mdi_pathmap_instance++;
		path_persistent = i_ddi_strdup(path, KM_SLEEP);
                (void) mod_hash_insert(mdi_pathmap_bypath,
                    (mod_hash_key_t)path_persistent,
                    (mod_hash_val_t)(intptr_t)path_instance);
		(void) mod_hash_insert(mdi_pathmap_byinstance,
		    (mod_hash_key_t)(intptr_t)path_instance,
		    (mod_hash_val_t)path_persistent);

		/* create shortpath name */
		(void) snprintf(path, sizeof(path), "%s%d/%s@%s",
		    ddi_driver_name(ph->ph_dip), ddi_get_instance(ph->ph_dip),
		    mdi_pi_get_node_name(pip), mdi_pi_get_addr(pip));
		path_persistent = i_ddi_strdup(path, KM_SLEEP);
		(void) mod_hash_insert(mdi_pathmap_sbyinstance,
		    (mod_hash_key_t)(intptr_t)path_instance,
		    (mod_hash_val_t)path_persistent);
        }
        mutex_exit(&mdi_pathmap_mutex);
	MDI_PI(pip)->pi_path_instance = path_instance;

	(void) nvlist_alloc(&MDI_PI(pip)->pi_prop, NV_UNIQUE_NAME, KM_SLEEP);
	ASSERT(MDI_PI(pip)->pi_prop != NULL);
	MDI_PI(pip)->pi_pprivate = NULL;
	MDI_PI(pip)->pi_cprivate = NULL;
	MDI_PI(pip)->pi_vprivate = NULL;
	MDI_PI(pip)->pi_client_link = NULL;
	MDI_PI(pip)->pi_phci_link = NULL;
	MDI_PI(pip)->pi_ref_cnt = 0;
	MDI_PI(pip)->pi_kstats = NULL;
	MDI_PI(pip)->pi_preferred = 1;
	cv_init(&MDI_PI(pip)->pi_ref_cv, NULL, CV_DEFAULT, NULL);

	/*
	 * Lock both dev_info nodes against changes in parallel.
	 *
	 * The ndi_devi_enter(Client), is atypical since the client is a leaf.
	 * This atypical operation is done to synchronize pathinfo nodes
	 * during devinfo snapshot (see di_register_pip) by 'pretending' that
	 * the pathinfo nodes are children of the Client.
	 */
	ndi_devi_enter(ct->ct_dip, &ct_circular);
	ndi_devi_enter(ph->ph_dip, &ph_circular);

	i_mdi_phci_add_path(ph, pip);
	i_mdi_client_add_path(ct, pip);

	ndi_devi_exit(ph->ph_dip, ph_circular);
	ndi_devi_exit(ct->ct_dip, ct_circular);

	return (pip);
}

/*
 * mdi_pi_pathname_by_instance():
 *	Lookup of "path" by 'path_instance'. Return "path".
 *	NOTE: returned "path" remains valid forever (until reboot).
 */
char *
mdi_pi_pathname_by_instance(int path_instance)
{
	char		*path;
	mod_hash_val_t	hv;

	/* mdi_pathmap lookup of "path" by 'path_instance' */
	mutex_enter(&mdi_pathmap_mutex);
	if (mod_hash_find(mdi_pathmap_byinstance,
	    (mod_hash_key_t)(intptr_t)path_instance, &hv) == 0)
		path = (char *)hv;
	else
		path = NULL;
	mutex_exit(&mdi_pathmap_mutex);
	return (path);
}

/*
 * mdi_pi_spathname_by_instance():
 *	Lookup of "shortpath" by 'path_instance'. Return "shortpath".
 *	NOTE: returned "shortpath" remains valid forever (until reboot).
 */
char *
mdi_pi_spathname_by_instance(int path_instance)
{
	char		*path;
	mod_hash_val_t	hv;

	/* mdi_pathmap lookup of "path" by 'path_instance' */
	mutex_enter(&mdi_pathmap_mutex);
	if (mod_hash_find(mdi_pathmap_sbyinstance,
	    (mod_hash_key_t)(intptr_t)path_instance, &hv) == 0)
		path = (char *)hv;
	else
		path = NULL;
	mutex_exit(&mdi_pathmap_mutex);
	return (path);
}


/*
 * i_mdi_phci_add_path():
 * 		Add a mdi_pathinfo node to pHCI list.
 * Notes:
 *		Caller should per-pHCI mutex
 */
static void
i_mdi_phci_add_path(mdi_phci_t *ph, mdi_pathinfo_t *pip)
{
	ASSERT(DEVI_BUSY_OWNED(ph->ph_dip));

	MDI_PHCI_LOCK(ph);
	if (ph->ph_path_head == NULL) {
		ph->ph_path_head = pip;
	} else {
		MDI_PI(ph->ph_path_tail)->pi_phci_link = MDI_PI(pip);
	}
	ph->ph_path_tail = pip;
	ph->ph_path_count++;
	MDI_PHCI_UNLOCK(ph);
}

/*
 * i_mdi_client_add_path():
 *		Add mdi_pathinfo node to client list
 */
static void
i_mdi_client_add_path(mdi_client_t *ct, mdi_pathinfo_t *pip)
{
	ASSERT(DEVI_BUSY_OWNED(ct->ct_dip));

	MDI_CLIENT_LOCK(ct);
	if (ct->ct_path_head == NULL) {
		ct->ct_path_head = pip;
	} else {
		MDI_PI(ct->ct_path_tail)->pi_client_link = MDI_PI(pip);
	}
	ct->ct_path_tail = pip;
	ct->ct_path_count++;
	MDI_CLIENT_UNLOCK(ct);
}

/*
 * mdi_pi_free():
 *		Free the mdi_pathinfo node and also client device node if this
 *		is the last path to the device
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 *		MDI_BUSY
 */
/*ARGSUSED*/
int
mdi_pi_free(mdi_pathinfo_t *pip, int flags)
{
	int		rv = MDI_FAILURE;
	mdi_vhci_t	*vh;
	mdi_phci_t	*ph;
	mdi_client_t	*ct;
	int		(*f)();
	int		client_held = 0;

	MDI_PI_LOCK(pip);
	ph = MDI_PI(pip)->pi_phci;
	ASSERT(ph != NULL);
	if (ph == NULL) {
		/*
		 * Invalid pHCI device, return failure
		 */
		MDI_DEBUG(1, (MDI_WARN, NULL,
		    "!invalid pHCI: pip %s %p",
		    mdi_pi_spathname(pip), (void *)pip));
		MDI_PI_UNLOCK(pip);
		return (MDI_FAILURE);
	}

	vh = ph->ph_vhci;
	ASSERT(vh != NULL);
	if (vh == NULL) {
		/* Invalid pHCI device, return failure */
		MDI_DEBUG(1, (MDI_WARN, ph->ph_dip,
		    "!invalid vHCI: pip %s %p",
		    mdi_pi_spathname(pip), (void *)pip));
		MDI_PI_UNLOCK(pip);
		return (MDI_FAILURE);
	}

	ct = MDI_PI(pip)->pi_client;
	ASSERT(ct != NULL);
	if (ct == NULL) {
		/*
		 * Invalid Client device, return failure
		 */
		MDI_DEBUG(1, (MDI_WARN, ph->ph_dip,
		    "!invalid client: pip %s %p",
		    mdi_pi_spathname(pip), (void *)pip));
		MDI_PI_UNLOCK(pip);
		return (MDI_FAILURE);
	}

	/*
	 * Check to see for busy condition.  A mdi_pathinfo can only be freed
	 * if the node state is either offline or init and the reference count
	 * is zero.
	 */
	if (!(MDI_PI_IS_OFFLINE(pip) || MDI_PI_IS_INIT(pip) ||
	    MDI_PI_IS_INITING(pip))) {
		/*
		 * Node is busy
		 */
		MDI_DEBUG(1, (MDI_WARN, ct->ct_dip,
		    "!busy: pip %s %p", mdi_pi_spathname(pip), (void *)pip));
		MDI_PI_UNLOCK(pip);
		return (MDI_BUSY);
	}

	while (MDI_PI(pip)->pi_ref_cnt != 0) {
		/*
		 * Give a chance for pending I/Os to complete.
		 */
		MDI_DEBUG(1, (MDI_NOTE, ct->ct_dip,
		    "!%d cmds still pending on path: %s %p",
		    MDI_PI(pip)->pi_ref_cnt,
		    mdi_pi_spathname(pip), (void *)pip));
		if (cv_timedwait(&MDI_PI(pip)->pi_ref_cv,
		    &MDI_PI(pip)->pi_mutex,
		    ddi_get_lbolt() + drv_usectohz(60 * 1000000)) == -1) {
			/*
			 * The timeout time reached without ref_cnt being zero
			 * being signaled.
			 */
			MDI_DEBUG(1, (MDI_NOTE, ct->ct_dip,
			    "!Timeout reached on path %s %p without the cond",
			    mdi_pi_spathname(pip), (void *)pip));
			MDI_DEBUG(1, (MDI_NOTE, ct->ct_dip,
			    "!%d cmds still pending on path %s %p",
			    MDI_PI(pip)->pi_ref_cnt,
			    mdi_pi_spathname(pip), (void *)pip));
			MDI_PI_UNLOCK(pip);
			return (MDI_BUSY);
		}
	}
	if (MDI_PI(pip)->pi_pm_held) {
		client_held = 1;
	}
	MDI_PI_UNLOCK(pip);

	vhcache_pi_remove(vh->vh_config, MDI_PI(pip));

	MDI_CLIENT_LOCK(ct);

	/* Prevent further failovers till MDI_VHCI_CLIENT_LOCK is held */
	MDI_CLIENT_SET_PATH_FREE_IN_PROGRESS(ct);

	/*
	 * Wait till failover is complete before removing this node.
	 */
	while (MDI_CLIENT_IS_FAILOVER_IN_PROGRESS(ct))
		cv_wait(&ct->ct_failover_cv, &ct->ct_mutex);

	MDI_CLIENT_UNLOCK(ct);
	MDI_VHCI_CLIENT_LOCK(vh);
	MDI_CLIENT_LOCK(ct);
	MDI_CLIENT_CLEAR_PATH_FREE_IN_PROGRESS(ct);

	if (!MDI_PI_IS_INITING(pip)) {
		f = vh->vh_ops->vo_pi_uninit;
		if (f != NULL) {
			rv = (*f)(vh->vh_dip, pip, 0);
		}
	}
	/*
	 * If vo_pi_uninit() completed successfully.
	 */
	if (rv == MDI_SUCCESS) {
		if (client_held) {
			MDI_DEBUG(4, (MDI_NOTE, ct->ct_dip,
			    "i_mdi_pm_rele_client\n"));
			i_mdi_pm_rele_client(ct, 1);
		}
		i_mdi_pi_free(ph, pip, ct);
		if (ct->ct_path_count == 0) {
			/*
			 * Client lost its last path.
			 * Clean up the client device
			 */
			MDI_CLIENT_UNLOCK(ct);
			(void) i_mdi_client_free(ct->ct_vhci, ct);
			MDI_VHCI_CLIENT_UNLOCK(vh);
			return (rv);
		}
	}
	MDI_CLIENT_UNLOCK(ct);
	MDI_VHCI_CLIENT_UNLOCK(vh);

	if (rv == MDI_FAILURE)
		vhcache_pi_add(vh->vh_config, MDI_PI(pip));

	return (rv);
}

/*
 * i_mdi_pi_free():
 *		Free the mdi_pathinfo node
 */
static void
i_mdi_pi_free(mdi_phci_t *ph, mdi_pathinfo_t *pip, mdi_client_t *ct)
{
	int	ct_circular;
	int	ph_circular;

	ASSERT(MDI_CLIENT_LOCKED(ct));

	/*
	 * remove any per-path kstats
	 */
	i_mdi_pi_kstat_destroy(pip);

	/* See comments in i_mdi_pi_alloc() */
	ndi_devi_enter(ct->ct_dip, &ct_circular);
	ndi_devi_enter(ph->ph_dip, &ph_circular);

	i_mdi_client_remove_path(ct, pip);
	i_mdi_phci_remove_path(ph, pip);

	ndi_devi_exit(ph->ph_dip, ph_circular);
	ndi_devi_exit(ct->ct_dip, ct_circular);

	mutex_destroy(&MDI_PI(pip)->pi_mutex);
	cv_destroy(&MDI_PI(pip)->pi_state_cv);
	cv_destroy(&MDI_PI(pip)->pi_ref_cv);
	if (MDI_PI(pip)->pi_addr) {
		kmem_free(MDI_PI(pip)->pi_addr,
		    strlen(MDI_PI(pip)->pi_addr) + 1);
		MDI_PI(pip)->pi_addr = NULL;
	}

	if (MDI_PI(pip)->pi_prop) {
		(void) nvlist_free(MDI_PI(pip)->pi_prop);
		MDI_PI(pip)->pi_prop = NULL;
	}
	kmem_free(pip, sizeof (struct mdi_pathinfo));
}


/*
 * i_mdi_phci_remove_path():
 * 		Remove a mdi_pathinfo node from pHCI list.
 * Notes:
 *		Caller should hold per-pHCI mutex
 */
static void
i_mdi_phci_remove_path(mdi_phci_t *ph, mdi_pathinfo_t *pip)
{
	mdi_pathinfo_t	*prev = NULL;
	mdi_pathinfo_t	*path = NULL;

	ASSERT(DEVI_BUSY_OWNED(ph->ph_dip));

	MDI_PHCI_LOCK(ph);
	path = ph->ph_path_head;
	while (path != NULL) {
		if (path == pip) {
			break;
		}
		prev = path;
		path = (mdi_pathinfo_t *)MDI_PI(path)->pi_phci_link;
	}

	if (path) {
		ph->ph_path_count--;
		if (prev) {
			MDI_PI(prev)->pi_phci_link = MDI_PI(path)->pi_phci_link;
		} else {
			ph->ph_path_head =
			    (mdi_pathinfo_t *)MDI_PI(path)->pi_phci_link;
		}
		if (ph->ph_path_tail == path) {
			ph->ph_path_tail = prev;
		}
	}

	/*
	 * Clear the pHCI link
	 */
	MDI_PI(pip)->pi_phci_link = NULL;
	MDI_PI(pip)->pi_phci = NULL;
	MDI_PHCI_UNLOCK(ph);
}

/*
 * i_mdi_client_remove_path():
 * 		Remove a mdi_pathinfo node from client path list.
 */
static void
i_mdi_client_remove_path(mdi_client_t *ct, mdi_pathinfo_t *pip)
{
	mdi_pathinfo_t	*prev = NULL;
	mdi_pathinfo_t	*path;

	ASSERT(DEVI_BUSY_OWNED(ct->ct_dip));

	ASSERT(MDI_CLIENT_LOCKED(ct));
	path = ct->ct_path_head;
	while (path != NULL) {
		if (path == pip) {
			break;
		}
		prev = path;
		path = (mdi_pathinfo_t *)MDI_PI(path)->pi_client_link;
	}

	if (path) {
		ct->ct_path_count--;
		if (prev) {
			MDI_PI(prev)->pi_client_link =
			    MDI_PI(path)->pi_client_link;
		} else {
			ct->ct_path_head =
			    (mdi_pathinfo_t *)MDI_PI(path)->pi_client_link;
		}
		if (ct->ct_path_tail == path) {
			ct->ct_path_tail = prev;
		}
		if (ct->ct_path_last == path) {
			ct->ct_path_last = ct->ct_path_head;
		}
	}
	MDI_PI(pip)->pi_client_link = NULL;
	MDI_PI(pip)->pi_client = NULL;
}

/*
 * i_mdi_pi_state_change():
 *		online a mdi_pathinfo node
 *
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
/*ARGSUSED*/
static int
i_mdi_pi_state_change(mdi_pathinfo_t *pip, mdi_pathinfo_state_t state, int flag)
{
	int		rv = MDI_SUCCESS;
	mdi_vhci_t	*vh;
	mdi_phci_t	*ph;
	mdi_client_t	*ct;
	int		(*f)();
	dev_info_t	*cdip;

	MDI_PI_LOCK(pip);

	ph = MDI_PI(pip)->pi_phci;
	ASSERT(ph);
	if (ph == NULL) {
		/*
		 * Invalid pHCI device, fail the request
		 */
		MDI_PI_UNLOCK(pip);
		MDI_DEBUG(1, (MDI_WARN, NULL,
		    "!invalid phci: pip %s %p",
		    mdi_pi_spathname(pip), (void *)pip));
		return (MDI_FAILURE);
	}

	vh = ph->ph_vhci;
	ASSERT(vh);
	if (vh == NULL) {
		/*
		 * Invalid vHCI device, fail the request
		 */
		MDI_PI_UNLOCK(pip);
		MDI_DEBUG(1, (MDI_WARN, ph->ph_dip,
		    "!invalid vhci: pip %s %p",
		    mdi_pi_spathname(pip), (void *)pip));
		return (MDI_FAILURE);
	}

	ct = MDI_PI(pip)->pi_client;
	ASSERT(ct != NULL);
	if (ct == NULL) {
		/*
		 * Invalid client device, fail the request
		 */
		MDI_PI_UNLOCK(pip);
		MDI_DEBUG(1, (MDI_WARN, ph->ph_dip,
		    "!invalid client: pip %s %p",
		    mdi_pi_spathname(pip), (void *)pip));
		return (MDI_FAILURE);
	}

	/*
	 * If this path has not been initialized yet, Callback vHCI driver's
	 * pathinfo node initialize entry point
	 */

	if (MDI_PI_IS_INITING(pip)) {
		MDI_PI_UNLOCK(pip);
		f = vh->vh_ops->vo_pi_init;
		if (f != NULL) {
			rv = (*f)(vh->vh_dip, pip, 0);
			if (rv != MDI_SUCCESS) {
				MDI_DEBUG(1, (MDI_WARN, ct->ct_dip,
				    "!vo_pi_init failed: vHCI %p, pip %s %p",
				    (void *)vh, mdi_pi_spathname(pip),
				    (void *)pip));
				return (MDI_FAILURE);
			}
		}
		MDI_PI_LOCK(pip);
		MDI_PI_CLEAR_TRANSIENT(pip);
	}

	/*
	 * Do not allow state transition when pHCI is in offline/suspended
	 * states
	 */
	i_mdi_phci_lock(ph, pip);
	if (MDI_PHCI_IS_READY(ph) == 0) {
		MDI_DEBUG(1, (MDI_WARN, ct->ct_dip,
		    "!pHCI not ready, pHCI=%p", (void *)ph));
		MDI_PI_UNLOCK(pip);
		i_mdi_phci_unlock(ph);
		return (MDI_BUSY);
	}
	MDI_PHCI_UNSTABLE(ph);
	i_mdi_phci_unlock(ph);

	/*
	 * Check if mdi_pathinfo state is in transient state.
	 * If yes, offlining is in progress and wait till transient state is
	 * cleared.
	 */
	if (MDI_PI_IS_TRANSIENT(pip)) {
		while (MDI_PI_IS_TRANSIENT(pip)) {
			cv_wait(&MDI_PI(pip)->pi_state_cv,
			    &MDI_PI(pip)->pi_mutex);
		}
	}

	/*
	 * Grab the client lock in reverse order sequence and release the
	 * mdi_pathinfo mutex.
	 */
	i_mdi_client_lock(ct, pip);
	MDI_PI_UNLOCK(pip);

	/*
	 * Wait till failover state is cleared
	 */
	while (MDI_CLIENT_IS_FAILOVER_IN_PROGRESS(ct))
		cv_wait(&ct->ct_failover_cv, &ct->ct_mutex);

	/*
	 * Mark the mdi_pathinfo node state as transient
	 */
	MDI_PI_LOCK(pip);
	switch (state) {
	case MDI_PATHINFO_STATE_ONLINE:
		MDI_PI_SET_ONLINING(pip);
		break;

	case MDI_PATHINFO_STATE_STANDBY:
		MDI_PI_SET_STANDBYING(pip);
		break;

	case MDI_PATHINFO_STATE_FAULT:
		/*
		 * Mark the pathinfo state as FAULTED
		 */
		MDI_PI_SET_FAULTING(pip);
		MDI_PI_ERRSTAT(pip, MDI_PI_HARDERR);
		break;

	case MDI_PATHINFO_STATE_OFFLINE:
		/*
		 * ndi_devi_offline() cannot hold pip or ct locks.
		 */
		MDI_PI_UNLOCK(pip);

		/*
		 * If this is a user initiated path online->offline operation
		 * who's success would transition a client from DEGRADED to
		 * FAILED then only proceed if we can offline the client first.
		 */
		cdip = ct->ct_dip;
		if ((flag & NDI_USER_REQ) &&
		    MDI_PI_IS_ONLINE(pip) &&
		    (MDI_CLIENT_STATE(ct) == MDI_CLIENT_STATE_DEGRADED)) {
			i_mdi_client_unlock(ct);
			rv = ndi_devi_offline(cdip, NDI_DEVFS_CLEAN);
			if (rv != NDI_SUCCESS) {
				/*
				 * Convert to MDI error code
				 */
				switch (rv) {
				case NDI_BUSY:
					rv = MDI_BUSY;
					break;
				default:
					rv = MDI_FAILURE;
					break;
				}
				goto state_change_exit;
			} else {
				i_mdi_client_lock(ct, NULL);
			}
		}
		/*
		 * Mark the mdi_pathinfo node state as transient
		 */
		MDI_PI_LOCK(pip);
		MDI_PI_SET_OFFLINING(pip);
		break;
	}
	MDI_PI_UNLOCK(pip);
	MDI_CLIENT_UNSTABLE(ct);
	i_mdi_client_unlock(ct);

	f = vh->vh_ops->vo_pi_state_change;
	if (f != NULL)
		rv = (*f)(vh->vh_dip, pip, state, 0, flag);

	MDI_CLIENT_LOCK(ct);
	MDI_PI_LOCK(pip);
	if (rv == MDI_NOT_SUPPORTED) {
		MDI_CLIENT_SET_DEV_NOT_SUPPORTED(ct);
	}
	if (rv != MDI_SUCCESS) {
		MDI_DEBUG(2, (MDI_WARN, ct->ct_dip,
		    "vo_pi_state_change failed: rv %x", rv));
	}
	if (MDI_PI_IS_TRANSIENT(pip)) {
		if (rv == MDI_SUCCESS) {
			MDI_PI_CLEAR_TRANSIENT(pip);
		} else {
			MDI_PI(pip)->pi_state = MDI_PI_OLD_STATE(pip);
		}
	}

	/*
	 * Wake anyone waiting for this mdi_pathinfo node
	 */
	cv_broadcast(&MDI_PI(pip)->pi_state_cv);
	MDI_PI_UNLOCK(pip);

	/*
	 * Mark the client device as stable
	 */
	MDI_CLIENT_STABLE(ct);
	if (rv == MDI_SUCCESS) {
		if (ct->ct_unstable == 0) {
			cdip = ct->ct_dip;

			/*
			 * Onlining the mdi_pathinfo node will impact the
			 * client state Update the client and dev_info node
			 * state accordingly
			 */
			rv = NDI_SUCCESS;
			i_mdi_client_update_state(ct);
			switch (MDI_CLIENT_STATE(ct)) {
			case MDI_CLIENT_STATE_OPTIMAL:
			case MDI_CLIENT_STATE_DEGRADED:
				if (cdip && !i_ddi_devi_attached(cdip) &&
				    ((state == MDI_PATHINFO_STATE_ONLINE) ||
				    (state == MDI_PATHINFO_STATE_STANDBY))) {

					/*
					 * Must do ndi_devi_online() through
					 * hotplug thread for deferred
					 * attach mechanism to work
					 */
					MDI_CLIENT_UNLOCK(ct);
					rv = ndi_devi_online(cdip, 0);
					MDI_CLIENT_LOCK(ct);
					if ((rv != NDI_SUCCESS) &&
					    (MDI_CLIENT_STATE(ct) ==
					    MDI_CLIENT_STATE_DEGRADED)) {
						/*
						 * ndi_devi_online failed.
						 * Reset client flags to
						 * offline.
						 */
						MDI_DEBUG(1, (MDI_WARN, cdip,
						    "!ndi_devi_online failed "
						    "error %x", rv));
						MDI_CLIENT_SET_OFFLINE(ct);
					}
					if (rv != NDI_SUCCESS) {
						/* Reset the path state */
						MDI_PI_LOCK(pip);
						MDI_PI(pip)->pi_state =
						    MDI_PI_OLD_STATE(pip);
						MDI_PI_UNLOCK(pip);
					}
				}
				break;

			case MDI_CLIENT_STATE_FAILED:
				/*
				 * This is the last path case for
				 * non-user initiated events.
				 */
				if (((flag & NDI_USER_REQ) == 0) &&
				    cdip && (i_ddi_node_state(cdip) >=
				    DS_INITIALIZED)) {
					MDI_CLIENT_UNLOCK(ct);
					rv = ndi_devi_offline(cdip,
					    NDI_DEVFS_CLEAN);
					MDI_CLIENT_LOCK(ct);

					if (rv != NDI_SUCCESS) {
						/*
						 * ndi_devi_offline failed.
						 * Reset client flags to
						 * online as the path could not
						 * be offlined.
						 */
						MDI_DEBUG(1, (MDI_WARN, cdip,
						    "!ndi_devi_offline failed: "
						    "error %x", rv));
						MDI_CLIENT_SET_ONLINE(ct);
					}
				}
				break;
			}
			/*
			 * Convert to MDI error code
			 */
			switch (rv) {
			case NDI_SUCCESS:
				MDI_CLIENT_SET_REPORT_DEV_NEEDED(ct);
				i_mdi_report_path_state(ct, pip);
				rv = MDI_SUCCESS;
				break;
			case NDI_BUSY:
				rv = MDI_BUSY;
				break;
			default:
				rv = MDI_FAILURE;
				break;
			}
		}
	}
	MDI_CLIENT_UNLOCK(ct);

state_change_exit:
	/*
	 * Mark the pHCI as stable again.
	 */
	MDI_PHCI_LOCK(ph);
	MDI_PHCI_STABLE(ph);
	MDI_PHCI_UNLOCK(ph);
	return (rv);
}

/*
 * mdi_pi_online():
 *		Place the path_info node in the online state.  The path is
 *		now available to be selected by mdi_select_path() for
 *		transporting I/O requests to client devices.
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
int
mdi_pi_online(mdi_pathinfo_t *pip, int flags)
{
	mdi_client_t	*ct = MDI_PI(pip)->pi_client;
	int		client_held = 0;
	int		rv;

	ASSERT(ct != NULL);
	rv = i_mdi_pi_state_change(pip, MDI_PATHINFO_STATE_ONLINE, flags);
	if (rv != MDI_SUCCESS)
		return (rv);

	MDI_PI_LOCK(pip);
	if (MDI_PI(pip)->pi_pm_held == 0) {
		MDI_DEBUG(4, (MDI_NOTE, ct->ct_dip,
		    "i_mdi_pm_hold_pip %p", (void *)pip));
		i_mdi_pm_hold_pip(pip);
		client_held = 1;
	}
	MDI_PI_UNLOCK(pip);

	if (client_held) {
		MDI_CLIENT_LOCK(ct);
		if (ct->ct_power_cnt == 0) {
			rv = i_mdi_power_all_phci(ct);
		}

		MDI_DEBUG(4, (MDI_NOTE, ct->ct_dip,
		    "i_mdi_pm_hold_client %p", (void *)ct));
		i_mdi_pm_hold_client(ct, 1);
		MDI_CLIENT_UNLOCK(ct);
	}

	return (rv);
}

/*
 * mdi_pi_standby():
 *		Place the mdi_pathinfo node in standby state
 *
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
int
mdi_pi_standby(mdi_pathinfo_t *pip, int flags)
{
	return (i_mdi_pi_state_change(pip, MDI_PATHINFO_STATE_STANDBY, flags));
}

/*
 * mdi_pi_fault():
 *		Place the mdi_pathinfo node in fault'ed state
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
int
mdi_pi_fault(mdi_pathinfo_t *pip, int flags)
{
	return (i_mdi_pi_state_change(pip, MDI_PATHINFO_STATE_FAULT, flags));
}

/*
 * mdi_pi_offline():
 *		Offline a mdi_pathinfo node.
 * Return Values:
 *		MDI_SUCCESS
 *		MDI_FAILURE
 */
int
mdi_pi_offline(mdi_pathinfo_t *pip, int flags)
{
	int	ret, client_held = 0;
	mdi_client_t	*ct;

	/*
	 * Original code overloaded NDI_DEVI_REMOVE to this interface, and
	 * used it to mean "user initiated operation" (i.e. devctl). Callers
	 * should now just use NDI_USER_REQ.
	 */
	if (flags & NDI_DEVI_REMOVE) {
		flags &= ~NDI_DEVI_REMOVE;
		flags |= NDI_USER_REQ;
	}

	ret = i_mdi_pi_state_change(pip, MDI_PATHINFO_STATE_OFFLINE, flags);

	if (ret == MDI_SUCCESS) {
		MDI_PI_LOCK(pip);
		if (MDI_PI(pip)->pi_pm_held) {
			client_held = 1;
		}
		MDI_PI_UNLOCK(pip);

		if (client_held) {
			ct = MDI_PI(pip)->pi_client;
			MDI_CLIENT_LOCK(ct);
			MDI_DEBUG(4, (MDI_NOTE, ct->ct_dip,
			    "i_mdi_pm_rele_client\n"));
			i_mdi_pm_rele_client(ct, 1);
			MDI_CLIENT_UNLOCK(ct);
		}
	}

	return (ret);
}

/*
 * i_mdi_pi_offline():
 *		Offline a mdi_pathinfo node and call the vHCI driver's callback
 */
static int
i_mdi_pi_offline(mdi_pathinfo_t *pip, int flags)
{
	dev_info_t	*vdip = NULL;
	mdi_vhci_t	*vh = NULL;
	mdi_client_t	*ct = NULL;
	int		(*f)();
	int		rv;

	MDI_PI_LOCK(pip);
	ct = MDI_PI(pip)->pi_client;
	ASSERT(ct != NULL);

	while (MDI_PI(pip)->pi_ref_cnt != 0) {
		/*
		 * Give a chance for pending I/Os to complete.
		 */
		MDI_DEBUG(1, (MDI_NOTE, ct->ct_dip,
		    "!%d cmds still pending on path %s %p",
		    MDI_PI(pip)->pi_ref_cnt, mdi_pi_spathname(pip),
		    (void *)pip));
		if (cv_timedwait(&MDI_PI(pip)->pi_ref_cv,
		    &MDI_PI(pip)->pi_mutex,
		    ddi_get_lbolt() + drv_usectohz(60 * 1000000)) == -1) {
			/*
			 * The timeout time reached without ref_cnt being zero
			 * being signaled.
			 */
			MDI_DEBUG(1, (MDI_NOTE, ct->ct_dip,
			    "!Timeout reached on path %s %p without the cond",
			    mdi_pi_spathname(pip), (void *)pip));
			MDI_DEBUG(1, (MDI_NOTE, ct->ct_dip,
			    "!%d cmds still pending on path %s %p",
			    MDI_PI(pip)->pi_ref_cnt,
			    mdi_pi_spathname(pip), (void *)pip));
		}
	}
	vh = ct->ct_vhci;
	vdip = vh->vh_dip;

	/*
	 * Notify vHCI that has registered this event
	 */
	ASSERT(vh->vh_ops);
	f = vh->vh_ops->vo_pi_state_change;

	if (f != NULL) {
		MDI_PI_UNLOCK(pip);
		if ((rv = (*f)(vdip, pip, MDI_PATHINFO_STATE_OFFLINE, 0,
		    flags)) != MDI_SUCCESS) {
			MDI_DEBUG(1, (MDI_WARN, ct->ct_dip,
			    "!vo_path_offline failed: vdip %s%d %p: path %s %p",
			    ddi_driver_name(vdip), ddi_get_instance(vdip),
			    (void *)vdip, mdi_pi_spathname(pip), (void *)pip));
		}
		MDI_PI_LOCK(pip);
	}

	/*
	 * Set the mdi_pathinfo node state and clear the transient condition
	 */
	MDI_PI_SET_OFFLINE(pip);
	cv_broadcast(&MDI_PI(pip)->pi_state_cv);
	MDI_PI_UNLOCK(pip);

	MDI_CLIENT_LOCK(ct);
	if (rv == MDI_SUCCESS) {
		if (ct->ct_unstable == 0) {
			dev_info_t	*cdip = ct->ct_dip;

			/*
			 * Onlining the mdi_pathinfo node will impact the
			 * client state Update the client and dev_info node
			 * state accordingly
			 */
			i_mdi_client_update_state(ct);
			rv = NDI_SUCCESS;
			if (MDI_CLIENT_STATE(ct) == MDI_CLIENT_STATE_FAILED) {
				if (cdip &&
				    (i_ddi_node_state(cdip) >=
				    DS_INITIALIZED)) {
					MDI_CLIENT_UNLOCK(ct);
					rv = ndi_devi_offline(cdip,
					    NDI_DEVFS_CLEAN);
					MDI_CLIENT_LOCK(ct);
					if (rv != NDI_SUCCESS) {
						/*
						 * ndi_devi_offline failed.
						 * Reset client flags to
						 * online.
						 */
						MDI_DEBUG(4, (MDI_WARN, cdip,
						    "ndi_devi_offline failed: "
						    "error %x", rv));
						MDI_CLIENT_SET_ONLINE(ct);
					}
				}
			}
			/*
			 * Convert to MDI error code
			 */
			switch (rv) {
			case NDI_SUCCESS:
				rv = MDI_SUCCESS;
				break;
			case NDI_BUSY:
				rv = MDI_BUSY;
				break;
			default:
				rv = MDI_FAILURE;
				break;
			}
		}
		MDI_CLIENT_SET_REPORT_DEV_NEEDED(ct);
		i_mdi_report_path_state(ct, pip);
	}

	MDI_CLIENT_UNLOCK(ct);

	/*
	 * Change in the mdi_pathinfo node state will impact the client state
	 */
	MDI_DEBUG(2, (MDI_NOTE, ct->ct_dip,
	    "ct = %p pip = %p", (void *)ct, (void *)pip));
	return (rv);
}

/*
 * mdi_pi_get_node_name():
 *              Get the name associated with a mdi_pathinfo node.
 *              Since pathinfo nodes are not directly named, we
 *              return the node_name of the client.
 *
 * Return Values:
 *              char *
 */
char *
mdi_pi_get_node_name(mdi_pathinfo_t *pip)
{
	mdi_client_t    *ct;

	if (pip == NULL)
		return (NULL);
	ct = MDI_PI(pip)->pi_client;
	if ((ct == NULL) || (ct->ct_dip == NULL))
		return (NULL);
	return (ddi_node_name(ct->ct_dip));
}

/*
 * mdi_pi_get_addr():
 *		Get the unit address associated with a mdi_pathinfo node
 *
 * Return Values:
 *		char *
 */
char *
mdi_pi_get_addr(mdi_pathinfo_t *pip)
{
	if (pip == NULL)
		return (NULL);

	return (MDI_PI(pip)->pi_addr);
}

/*
 * mdi_pi_get_path_instance():
 *		Get the 'path_instance' of a mdi_pathinfo node
 *
 * Return Values:
 *		path_instance
 */
int
mdi_pi_get_path_instance(mdi_pathinfo_t *pip)
{
	if (pip == NULL)
		return (0);

	return (MDI_PI(pip)->pi_path_instance);
}

/*
 * mdi_pi_pathname():
 *		Return pointer to path to pathinfo node.
 */
char *
mdi_pi_pathname(mdi_pathinfo_t *pip)
{
	if (pip == NULL)
		return (NULL);
	return (mdi_pi_pathname_by_instance(mdi_pi_get_path_instance(pip)));
}

/*
 * mdi_pi_spathname():
 *		Return pointer to shortpath to pathinfo node. Used for debug
 *		messages, so return "" instead of NULL when unknown.
 */
char *
mdi_pi_spathname(mdi_pathinfo_t *pip)
{
	char	*spath = "";

	if (pip) {
		spath = mdi_pi_spathname_by_instance(
		    mdi_pi_get_path_instance(pip));
		if (spath == NULL)
			spath = "";
	}
	return (spath);
}

char *
mdi_pi_pathname_obp(mdi_pathinfo_t *pip, char *path)
{
	char *obp_path = NULL;
	if ((pip == NULL) || (path == NULL))
		return (NULL);

	if (mdi_prop_lookup_string(pip, "obp-path", &obp_path) == MDI_SUCCESS) {
		(void) strcpy(path, obp_path);
		(void) mdi_prop_free(obp_path);
	} else {
		path = NULL;
	}
	return (path);
}

int
mdi_pi_pathname_obp_set(mdi_pathinfo_t *pip, char *component)
{
	dev_info_t *pdip;
	char *obp_path = NULL;
	int rc = MDI_FAILURE;

	if (pip == NULL)
		return (MDI_FAILURE);

	pdip = mdi_pi_get_phci(pip);
	if (pdip == NULL)
		return (MDI_FAILURE);

	obp_path = kmem_zalloc(MAXPATHLEN, KM_SLEEP);

	if (ddi_pathname_obp(pdip, obp_path) == NULL) {
		(void) ddi_pathname(pdip, obp_path);
	}

	if (component) {
		(void) strncat(obp_path, "/", MAXPATHLEN);
		(void) strncat(obp_path, component, MAXPATHLEN);
	}
	rc = mdi_prop_update_string(pip, "obp-path", obp_path);

	if (obp_path)
		kmem_free(obp_path, MAXPATHLEN);
	return (rc);
}

/*
 * mdi_pi_get_client():
 *		Get the client devinfo associated with a mdi_pathinfo node
 *
 * Return Values:
 *		Handle to client device dev_info node
 */
dev_info_t *
mdi_pi_get_client(mdi_pathinfo_t *pip)
{
	dev_info_t	*dip = NULL;
	if (pip) {
		dip = MDI_PI(pip)->pi_client->ct_dip;
	}
	return (dip);
}

/*
 * mdi_pi_get_phci():
 *		Get the pHCI devinfo associated with the mdi_pathinfo node
 * Return Values:
 *		Handle to dev_info node
 */
dev_info_t *
mdi_pi_get_phci(mdi_pathinfo_t *pip)
{
	dev_info_t	*dip = NULL;
	mdi_phci_t	*ph;

	if (pip) {
		ph = MDI_PI(pip)->pi_phci;
		if (ph)
			dip = ph->ph_dip;
	}
	return (dip);
}

/*
 * mdi_pi_get_client_private():
 *		Get the client private information associated with the
 *		mdi_pathinfo node
 */
void *
mdi_pi_get_client_private(mdi_pathinfo_t *pip)
{
	void *cprivate = NULL;
	if (pip) {
		cprivate = MDI_PI(pip)->pi_cprivate;
	}
	return (cprivate);
}

/*
 * mdi_pi_set_client_private():
 *		Set the client private information in the mdi_pathinfo node
 */
void
mdi_pi_set_client_private(mdi_pathinfo_t *pip, void *priv)
{
	if (pip) {
		MDI_PI(pip)->pi_cprivate = priv;
	}
}

/*
 * mdi_pi_get_phci_private():
 *		Get the pHCI private information associated with the
 *		mdi_pathinfo node
 */
caddr_t
mdi_pi_get_phci_private(mdi_pathinfo_t *pip)
{
	caddr_t	pprivate = NULL;

	if (pip) {
		pprivate = MDI_PI(pip)->pi_pprivate;
	}
	return (pprivate);
}

/*
 * mdi_pi_set_phci_private():
 *		Set the pHCI private information in the mdi_pathinfo node
 */
void
mdi_pi_set_phci_private(mdi_pathinfo_t *pip, caddr_t priv)
{
	if (pip) {
		MDI_PI(pip)->pi_pprivate = priv;
	}
}

/*
 * mdi_pi_get_state():
 *		Get the mdi_pathinfo node state. Transient states are internal
 *		and not provided to the users
 */
mdi_pathinfo_state_t
mdi_pi_get_state(mdi_pathinfo_t *pip)
{
	mdi_pathinfo_state_t    state = MDI_PATHINFO_STATE_INIT;

	if (pip) {
		if (MDI_PI_IS_TRANSIENT(pip)) {
			/*
			 * mdi_pathinfo is in state transition.  Return the
			 * last good state.
			 */
			state = MDI_PI_OLD_STATE(pip);
		} else {
			state = MDI_PI_STATE(pip);
		}
	}
	return (state);
}

/*
 * mdi_pi_get_flags():
 *		Get the mdi_pathinfo node flags.
 */
uint_t
mdi_pi_get_flags(mdi_pathinfo_t *pip)
{
	return (pip ? MDI_PI(pip)->pi_flags : 0);
}

/*
 * Note that the following function needs to be the new interface for
 * mdi_pi_get_state when mpxio gets integrated to ON.
 */
int
mdi_pi_get_state2(mdi_pathinfo_t *pip, mdi_pathinfo_state_t *state,
		uint32_t *ext_state)
{
	*state = MDI_PATHINFO_STATE_INIT;

	if (pip) {
		if (MDI_PI_IS_TRANSIENT(pip)) {
			/*
			 * mdi_pathinfo is in state transition.  Return the
			 * last good state.
			 */
			*state = MDI_PI_OLD_STATE(pip);
			*ext_state = MDI_PI_OLD_EXT_STATE(pip);
		} else {
			*state = MDI_PI_STATE(pip);
			*ext_state = MDI_PI_EXT_STATE(pip);
		}
	}
	return (MDI_SUCCESS);
}

/*
 * mdi_pi_get_preferred:
 *	Get the preferred path flag
 */
int
mdi_pi_get_preferred(mdi_pathinfo_t *pip)
{
	if (pip) {
		return (MDI_PI(pip)->pi_preferred);
	}
	return (0);
}

/*
 * mdi_pi_set_preferred:
 *	Set the preferred path flag
 */
void
mdi_pi_set_preferred(mdi_pathinfo_t *pip, int preferred)
{
	if (pip) {
		MDI_PI(pip)->pi_preferred = preferred;
	}
}

/*
 * mdi_pi_set_state():
 *		Set the mdi_pathinfo node state
 */
void
mdi_pi_set_state(mdi_pathinfo_t *pip, mdi_pathinfo_state_t state)
{
	uint32_t	ext_state;

	if (pip) {
		ext_state = MDI_PI(pip)->pi_state & MDI_PATHINFO_EXT_STATE_MASK;
		MDI_PI(pip)->pi_state = state;
		MDI_PI(pip)->pi_state |= ext_state;

		/* Path has changed state, invalidate DINFOCACHE snap shot. */
		i_ddi_di_cache_invalidate();
	}
}

/*
 * Property functions:
 */
int
i_map_nvlist_error_to_mdi(int val)
{
	int rv;

	switch (val) {
	case 0:
		rv = DDI_PROP_SUCCESS;
		break;
	case EINVAL:
	case ENOTSUP:
		rv = DDI_PROP_INVAL_ARG;
		break;
	case ENOMEM:
		rv = DDI_PROP_NO_MEMORY;
		break;
	default:
		rv = DDI_PROP_NOT_FOUND;
		break;
	}
	return (rv);
}

/*
 * mdi_pi_get_next_prop():
 * 		Property walk function.  The caller should hold mdi_pi_lock()
 *		and release by calling mdi_pi_unlock() at the end of walk to
 *		get a consistent value.
 */
nvpair_t *
mdi_pi_get_next_prop(mdi_pathinfo_t *pip, nvpair_t *prev)
{
	if ((pip == NULL) || (MDI_PI(pip)->pi_prop == NULL)) {
		return (NULL);
	}
	ASSERT(MDI_PI_LOCKED(pip));
	return (nvlist_next_nvpair(MDI_PI(pip)->pi_prop, prev));
}

/*
 * mdi_prop_remove():
 * 		Remove the named property from the named list.
 */
int
mdi_prop_remove(mdi_pathinfo_t *pip, char *name)
{
	if (pip == NULL) {
		return (DDI_PROP_NOT_FOUND);
	}
	ASSERT(!MDI_PI_LOCKED(pip));
	MDI_PI_LOCK(pip);
	if (MDI_PI(pip)->pi_prop == NULL) {
		MDI_PI_UNLOCK(pip);
		return (DDI_PROP_NOT_FOUND);
	}
	if (name) {
		(void) nvlist_remove_all(MDI_PI(pip)->pi_prop, name);
	} else {
		char		nvp_name[MAXNAMELEN];
		nvpair_t	*nvp;
		nvp = nvlist_next_nvpair(MDI_PI(pip)->pi_prop, NULL);
		while (nvp) {
			nvpair_t	*next;
			next = nvlist_next_nvpair(MDI_PI(pip)->pi_prop, nvp);
			(void) snprintf(nvp_name, sizeof(nvp_name), "%s",
			    nvpair_name(nvp));
			(void) nvlist_remove_all(MDI_PI(pip)->pi_prop,
			    nvp_name);
			nvp = next;
		}
	}
	MDI_PI_UNLOCK(pip);
	return (DDI_PROP_SUCCESS);
}

/*
 * mdi_prop_size():
 * 		Get buffer size needed to pack the property data.
 * 		Caller should hold the mdi_pathinfo_t lock to get a consistent
 *		buffer size.
 */
int
mdi_prop_size(mdi_pathinfo_t *pip, size_t *buflenp)
{
	int	rv;
	size_t	bufsize;

	*buflenp = 0;
	if ((pip == NULL) || (MDI_PI(pip)->pi_prop == NULL)) {
		return (DDI_PROP_NOT_FOUND);
	}
	ASSERT(MDI_PI_LOCKED(pip));
	rv = nvlist_size(MDI_PI(pip)->pi_prop,
	    &bufsize, NV_ENCODE_NATIVE);
	*buflenp = bufsize;
	return (i_map_nvlist_error_to_mdi(rv));
}

/*
 * mdi_prop_pack():
 * 		pack the property list.  The caller should hold the
 *		mdi_pathinfo_t node to get a consistent data
 */
int
mdi_prop_pack(mdi_pathinfo_t *pip, char **bufp, uint_t buflen)
{
	int	rv;
	size_t	bufsize;

	if ((pip == NULL) || MDI_PI(pip)->pi_prop == NULL) {
		return (DDI_PROP_NOT_FOUND);
	}

	ASSERT(MDI_PI_LOCKED(pip));

	bufsize = buflen;
	rv = nvlist_pack(MDI_PI(pip)->pi_prop, bufp, (size_t *)&bufsize,
	    NV_ENCODE_NATIVE, KM_SLEEP);

	return (i_map_nvlist_error_to_mdi(rv));
}

/*
 * mdi_prop_update_byte():
 *		Create/Update a byte property
 */
int
mdi_prop_update_byte(mdi_pathinfo_t *pip, char *name, uchar_t data)
{
	int rv;

	if (pip == NULL) {
		return (DDI_PROP_INVAL_ARG);
	}
	ASSERT(!MDI_PI_LOCKED(pip));
	MDI_PI_LOCK(pip);
	if (MDI_PI(pip)->pi_prop == NULL) {
		MDI_PI_UNLOCK(pip);
		return (