/*

 * CDDL HEADER START

 *

 * The contents of this file are subject to the terms of the

 * Common Development and Distribution License, Version 1.0 only

 * (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 2005 Sun Microsystems, Inc.  All rights reserved.

 * Use is subject to license terms.

 */

#ifndef	_SYS_MDI_IMPLDEFS_H

#define	_SYS_MDI_IMPLDEFS_H

#pragma ident	"%Z%%M%	%I%	%E% SMI"

#include <sys/note.h>

#include <sys/sunmdi.h>

#ifdef	__cplusplus

extern "C" {

#endif

#ifdef _KERNEL

/*

 * Multipath Driver Interfaces

 *

 * The multipathing framework is provided in two modules.  The 'mpxio' misc.

 * module provides the core multipath framework and the 'scsi_vhci' nexus

 * driver provides the SCSI-III command set driver functionality for

 * managing Fibre-Channel storage devices.

 *

 * As in any multipathing solution there are three major problems to solve:

 *

 * 1) Identification and enumeration of multipath client devices.

 * 2) Optimal path selection when routing I/O requests.

 * 3) Observability interfaces to snapshot the multipath configuration,

 *    and infrastructure to provide performance and error statistics.

 *

 * The mpxio framework consists of several major components:

 *

 * 1) The MDI is the Multiplexed Device Interface; this is the core glue which

 *    holds the following components together.

 * 2) vHCI (Virtual Host Controller Interconnect) drivers provide multipathing

 *    services for a given bus technology (example: 'scsi_vhci' provides

 *    multipathing support for SCSI-III fibre-channel devices).

 * 3) pHCI (Physical Host Controller Interconnect) drivers provide transport

 *    services for a given host controller (example: 'fcp' provides transport

 *    for fibre-channel devices).

 * 4) Client Devices are standard Solaris target (or leaf) drivers

 *    (example: 'ssd' is the standard disk driver for fibre-channel arrays).

 * 5) Multipath information nodes ('pathinfo' nodes) connect client device

 *    nodes and pHCI device nodes in the device tree.

 *

 * With the scsi_vhci, a QLC card, and mpxio enabled, the device tree might

 * look like this:

 *

 *	+-----------+   +-----------+

 *      | scsi_vhci |   |  pci@1f,0 |

 *      +-----------+   +-----------+

 *         /     \               \

 * +----------+ +-----------+    +-------------+

 * | ssd1     | | ssd2	    |    | qlc@0,0     |

 * +----------+ +-----------+    +-------------+

 *   |          |                  /        \

 *   |          |        +-------------+   +------------+

 *   |          |        | pHCI 1      |   |  pHCI 2    |

 *   |          |        +-------------+   +------------+

 *   |          |          /        |      /          |

 *   |          |    +------+       |    +------+     |

 *   |          |    |  ssd |       |    |  ssd |     |

 *   |          |    | (OBP)|       |    | (OBP)|     |

 *   |          |    +------+       |    +------+     |

 *   |          |                   |                 |

 *   |          |               +-------+           +--------+

 *   |          +-------------->| path  |---------->| path   |

 *   |                          | info  |           | info   |

 *   |                          | node 1|           | node 3 |

 *   |                          +-------+           +--------+

 *   |                              |                 |

 *   |                          +-------+           +--------+

 *   +------------------------->| path  |---------->| path   |

 *                              | info  |           | info   |

 *                              | node 2|           | node 4 |

 *                              +-------+           +--------+

 *

 * The multipath information nodes (mdi_pathinfo nodes) establish the

 * relationship between the pseudo client driver instance nodes and the

 * physical host controller interconnect (pHCI drivers) forming a matrix

 * structure.

 *

 * The mpxio module implements locking at multiple granularity levels to

 * support the needs of various consumers.  The multipath matrix can be

 * globally locked, column locked, or row locked depending on the consumer.

 * The intention is to balance simplicity and performance.

 *

 * Locking:

 *

 * The current implementation utilizes the following locks:

 *

 *   mdi_mutex: protects the vHCI list, per-vHCI structure and the

 *   list of pHCIs and Client devices registered against them (protection

 *   against multi-threaded add/remove).

 *

 *   devinfo_tree_lock (rw): protects system wide creation/removal of

 *   mdi_pathinfo nodes into the multipath matrix.  Consumers (like the devinfo

 *   driver) can freeze the configuration by acquiring this as a reader.

 *

 *   per-pHCI (mutex) lock: protects the column (pHCI-mdi_pathinfo node list)

 *   and per-pHCI structure fields.  mdi_pathinfo node creation, deletion and

 *   child mdi_pathinfo node state changes are serialized on per pHCI basis

 *   (Protection against DR).

 *

 *   per-client (mutex) lock: protects the row (client-mdi_pathinfo node list)

 *   and per-client structure fields.  The client-mdi_pathinfo node list is

 *   typically walked to select an optimal path when routing I/O requests.

 *

 *   per-mdi_pathinfo (mutex) lock: protects the mdi_pathinfo node structure

 *   fields.

 *

 * Note that per-Client structure and per-pHCI fields are freely readable when

 * corresponding mdi_pathinfo locks are held, since holding an mdi_pathinfo

 * node guarantees that its corresponding client and pHCI devices will not be

 * freed.

 */

/*

 * MDI Client global unique identifier property name string definition

 */

extern const char			*mdi_client_guid_prop;

#define	MDI_CLIENT_GUID_PROP		(char *)mdi_client_guid_prop

/*

 * MDI Client load balancing policy definitions

 *

 * Load balancing policies are determined on a per-vHCI basis and are

 * configurable via the vHCI's driver.conf file.

 */

typedef enum {

	LOAD_BALANCE_NONE,		/* Alternate pathing		*/

	LOAD_BALANCE_RR,		/* Round Robin			*/

	LOAD_BALANCE_LBA		/* Logical Block Addressing	*/

} client_lb_t;

typedef struct {

	int region_size;

}client_lb_args_t;

/*

 * MDI client load balancing property name/value string definitions

 */

extern const char			*mdi_load_balance;

extern const char			*mdi_load_balance_none;

extern const char			*mdi_load_balance_ap;

extern const char			*mdi_load_balance_rr;

extern const char			*mdi_load_balance_lba;

#define	LOAD_BALANCE_PROP		(char *)mdi_load_balance

#define	LOAD_BALANCE_PROP_NONE		(char *)mdi_load_balance_none

#define	LOAD_BALANCE_PROP_AP		(char *)mdi_load_balance_ap

#define	LOAD_BALANCE_PROP_RR		(char *)mdi_load_balance_rr

#define	LOAD_BALANCE_PROP_LBA		(char *)mdi_load_balance_lba

/* default for region size */

#define	LOAD_BALANCE_DEFAULT_REGION_SIZE	18

/*

 * vHCI drivers:

 *

 * vHCI drivers are pseudo nexus drivers which implement multipath services

 * for a specific command set or bus architecture ('class').  There is a

 * single instance of the vHCI driver for each command set which supports

 * multipath devices.

 *

 * Each vHCI driver registers the following callbacks from attach(9e).

 */

#define	MDI_VHCI_OPS_REV_1		1

/*

 * Change MDI_VHCI_OPS_REV_NAME as per MDI_VHCI_OPS_REV

 */

#define	MDI_VHCI_OPS_REV	MDI_VHCI_OPS_REV_1

#define	MDI_VHCI_OPS_REV_NAME	"1"

typedef struct mdi_vhci_ops {

	/* revision management */

	int	vo_revision;

	/* mdi_pathinfo node init callback */

	int	(*vo_pi_init)(dev_info_t *vdip, mdi_pathinfo_t *pip, int flags);

	/* mdi_pathinfo node uninit callback */

	int	(*vo_pi_uninit)(dev_info_t *vdip, mdi_pathinfo_t *pip,

		    int flags);

	/* mdi_pathinfo node state change callback */

	int	(*vo_pi_state_change)(dev_info_t *vdip, mdi_pathinfo_t *pip,

		    mdi_pathinfo_state_t state, uint32_t, int flags);

	/* Client path failover callback */

	int	(*vo_failover)(dev_info_t *vdip, dev_info_t *cdip, int flags);

} mdi_vhci_ops_t;

/*

 * An mdi_vhci structure is created and bound to the devinfo node of every

 * registered vHCI class driver; this happens when a vHCI registers itself from

 * attach(9e).  This structure is unbound and freed when the vHCI unregisters

 * at detach(9e) time;

 *

 * Each vHCI driver is associated with a vHCI class name; this is the handle

 * used to register and unregister pHCI drivers for a given transport.

 *

 * Locking: This structure is guarded by the mdi_mutex; however, depending

 * on the context, some of the fields can be freely read without holding any

 * locks (ex. holding a child's lock also guarantees that the vHCI (parent)

 * cannot be unexpectedly freed).

 */

typedef struct mdi_vhci {

	struct mdi_vhci		*vh_next;	/* next link		*/

	struct mdi_vhci		*vh_prev;	/* prev link		*/

	int			vh_flags;	/* Operation flags	*/

	dev_info_t		*vh_dip;	/* devi handle		*/

	char			*vh_class;	/* Class name		*/

	struct mdi_vhci_ops	*vh_ops;	/* Callback vectors	*/

	client_lb_t		vh_lb;		/* Global cache		*/

	int			vh_phci_count;	/* pHCI device count	*/

	struct mdi_phci		*vh_phci_head;	/* pHCI list head	*/

	struct mdi_phci		*vh_phci_tail;	/* pHCI list tail	*/

	int			vh_client_count;	/* Client count	*/

	struct client_hash	*vh_client_table;	/* Client hash	*/

} mdi_vhci_t;

/*

 * GUID Hash definitions

 *

 * Since all the mpxio managed devices for a given class are enumerated under

 * the single vHCI instance for that class, sequentially walking through the

 * client device link to find a client would be prohibitively slow.

 */

#define	CLIENT_HASH_TABLE_SIZE	(32)	/* GUID hash */

/*

 * Client hash table structure

 */

struct client_hash {

	struct mdi_client	*ct_hash_head;	/* Client hash head	*/

	int			ct_hash_count;	/* Client hash count	*/

};

/*

 * pHCI Drivers:

 *

 * Physical HBA drivers provide transport services for mpxio-managed devices.

 * As each pHCI instance is attached, it must register itself with the mpxio

 * framework using mdi_phci_register().  When the pHCI is detached it must

 * similarly call mdi_phci_unregister().

 *

 * The framework maintains a list of registered pHCI device instances for each

 * vHCI.  This list is vHCI->vh_phci_count, vHCI->vh_phci_head,

 * vHCI->vh_phci_tail and pHCI->ph_next.  This list is protected by the global

 * mdi_mutex.

 *

 * Locking order:

 *

 * _NOTE(LOCK_ORDER(mdi_mutex, mdi_phci::ph_mutex))

 * _NOTE(LOCK_ORDER(mdi_phci::ph_mutex devinfo_tree_lock))

 */

typedef struct mdi_phci {

	kmutex_t		ph_mutex;	/* per-pHCI mutex	*/

	struct mdi_phci		*ph_next;	/* next link		*/

	struct mdi_phci		*ph_prev;	/* prev link		*/

	dev_info_t		*ph_dip;	/* devi handle		*/

	struct mdi_vhci 	*ph_vhci;	/* back ref. to vHCI	*/

	int			ph_flags;	/* pHCI operation flags	*/

	int			ph_path_count;	/* child pi count	*/

	mdi_pathinfo_t		*ph_path_head;	/* pi list head		*/

	mdi_pathinfo_t		*ph_path_tail;	/* pi list tail		*/

	int			ph_unstable;	/* Paths in transient state */

	kcondvar_t		ph_unstable_cv;	/* Paths in transient state */

	kcondvar_t		ph_powerchange_cv;

						/* Paths in transient state */

	void			*ph_vprivate;	/* vHCI driver private	*/

} mdi_phci_t;

/*

 * A pHCI device is 'unstable' while one or more paths are in a transitional

 * state.  Hotplugging is prevented during this state.

 */

#define	MDI_PHCI_UNSTABLE(ph)		(ph)->ph_unstable++;

#define	MDI_PHCI_STABLE(ph) { \

	(ph)->ph_unstable--; \

	if ((ph)->ph_unstable == 0) { \

		cv_broadcast(&(ph)->ph_unstable_cv); \

	} \

}

/*

 * per-pHCI lock macros

 */

#define	MDI_PHCI_LOCK(ph)		mutex_enter(&((ph))->ph_mutex)

#define	MDI_PHCI_TRYLOCK(ph)		mutex_tryenter(&((ph))->ph_mutex)

#define	MDI_PHCI_UNLOCK(ph)		mutex_exit(&((ph))->ph_mutex)

/*

 * pHCI state definitions and macros to track the pHCI driver instance state

 */

#define	MDI_PHCI_FLAGS_OFFLINE		0x1	/* pHCI is offline */

#define	MDI_PHCI_FLAGS_SUSPEND		0x2	/* pHCI is suspended */

#define	MDI_PHCI_FLAGS_POWER_DOWN	0x4	/* pHCI is power down */

#define	MDI_PHCI_FLAGS_DETACH		0x8	/* pHCI is detached */

#define	MDI_PHCI_FLAGS_USER_DISABLE	0x10	/* pHCI is disabled,user */

#define	MDI_PHCI_FLAGS_D_DISABLE	0x20	/* pHCI is disabled,driver */

#define	MDI_PHCI_FLAGS_D_DISABLE_TRANS	0x40	/* pHCI is disabled,transient */

#define	MDI_PHCI_FLAGS_POWER_TRANSITION	0x80	/* pHCI is power transition */

#define	MDI_PHCI_DISABLE_MASK	(~(MDI_PHCI_FLAGS_USER_DISABLE | \

				MDI_PHCI_FLAGS_D_DISABLE | \

				MDI_PHCI_FLAGS_D_DISABLE_TRANS))

#define	MDI_PHCI_IS_READY(ph) \

	(((ph)->ph_flags &  (MDI_PHCI_DISABLE_MASK)) == 0)

#define	MDI_PHCI_SET_OFFLINE(ph) \

	    ((ph)->ph_flags |= MDI_PHCI_FLAGS_OFFLINE)

#define	MDI_PHCI_SET_ONLINE(ph) \

	    ((ph)->ph_flags &= ~MDI_PHCI_FLAGS_OFFLINE)

#define	MDI_PHCI_SET_SUSPEND(ph) \

	    ((ph)->ph_flags |= MDI_PHCI_FLAGS_SUSPEND)

#define	MDI_PHCI_SET_RESUME(ph) \

	    ((ph)->ph_flags &= ~MDI_PHCI_FLAGS_SUSPEND)

#define	MDI_PHCI_IS_OFFLINE(ph) \

	    ((ph)->ph_flags & MDI_PHCI_FLAGS_OFFLINE)

#define	MDI_PHCI_IS_SUSPENDED(ph) \

	    ((ph)->ph_flags & MDI_PHCI_FLAGS_SUSPEND)

#define	MDI_PHCI_SET_DETACH(ph) \

	    ((ph)->ph_flags |= MDI_PHCI_FLAGS_DETACH)

#define	MDI_PHCI_SET_ATTACH(ph) \

	    ((ph)->ph_flags &= ~MDI_PHCI_FLAGS_DETACH)

#define	MDI_PHCI_SET_POWER_DOWN(ph) \

	    ((ph)->ph_flags |= MDI_PHCI_FLAGS_POWER_DOWN)

#define	MDI_PHCI_SET_POWER_UP(ph) \

	    ((ph)->ph_flags &= ~MDI_PHCI_FLAGS_POWER_DOWN)

#define	MDI_PHCI_SET_USER_ENABLE(ph) \

		((ph)->ph_flags &= ~MDI_PHCI_FLAGS_USER_DISABLE)

#define	MDI_PHCI_SET_USER_DISABLE(ph) \

		((ph)->ph_flags |= MDI_PHCI_FLAGS_USER_DISABLE)

#define	MDI_PHCI_SET_DRV_ENABLE(ph)	\

		((ph)->ph_flags &= ~MDI_PHCI_FLAGS_D_DISABLE)

#define	MDI_PHCI_SET_DRV_DISABLE(ph)	\

		((ph)->ph_flags |= MDI_PHCI_FLAGS_D_DISABLE)

#define	MDI_PHCI_SET_DRV_ENABLE_TRANSIENT(ph)	\

		((ph)->ph_flags &= ~MDI_PHCI_FLAGS_D_DISABLE_TRANS)

#define	MDI_PHCI_SET_DRV_DISABLE_TRANSIENT(ph)	\

		((ph)->ph_flags |= MDI_PHCI_FLAGS_D_DISABLE_TRANS)

#define	MDI_PHCI_IS_USER_DISABLED(ph) \

		((ph)->ph_flags & MDI_PHCI_FLAGS_USER_DISABLE)

#define	MDI_PHCI_IS_DRV_DISABLED_TRANSIENT(ph)	\

		((ph)->ph_flags & MDI_PHCI_FLAGS_D_DISABLE_TRANS)

#define	MDI_PHCI_IS_DRV_DISABLED(ph)	\

		((ph)->ph_flags & MDI_PHCI_FLAGS_D_DISABLE)

#define	MDI_PHCI_IS_POWERED_DOWN(ph) \

	    ((ph)->ph_flags & MDI_PHCI_FLAGS_POWER_DOWN)

#define	MDI_PHCI_SET_POWER_TRANSITION(ph) \

	    ((ph)->ph_flags |= MDI_PHCI_FLAGS_POWER_TRANSITION)

#define	MDI_PHCI_CLEAR_POWER_TRANSITION(ph) \

	    ((ph)->ph_flags &= ~MDI_PHCI_FLAGS_POWER_TRANSITION)

#define	MDI_PHCI_IS_POWER_TRANSITION(ph) \

	    ((ph)->ph_flags & MDI_PHCI_FLAGS_POWER_TRANSITION)

/*

 * mpxio Managed Clients:

 *

 * This framework creates a struct mdi_client for every client device created

 * by the framework as a result of self-enumeration of target devices by the

 * registered pHCI devices.  This structure is bound to client device dev_info

 * node at the time of client device allocation (ndi_devi_alloc(9e)). This

 * structure is unbound from the dev_info node when mpxio framework removes a

 * client device node from the system.

 *

 * This structure is created when a first path is enumerated and removed when

 * last path is de-enumerated from the system.

 *

 * Multipath client devices are instantiated as children of corresponding vHCI

 * driver instance. Each client device is uniquely identified by a GUID

 * provided by target device itself.  The parent vHCI device also maintains a

 * hashed list of client devices, protected by the global mdi_mutex.

 *

 * Typically pHCI devices self-enumerate their child devices using taskq,

 * resulting in multiple paths to the same client device to be enumerated by

 * competing threads.  mdi_mutex is also used to serialize the client device

 * creation.

 *

 * Currently this framework supports two kinds of load-balancing policy

 * configurable through the vHCI driver configuration files.

 *

 * NONE		- Legacy AP mode

 * Round Robin	- Balance the pHCI load in a Round Robin fashion.

 *

 * This framework identifies the client device in three distinct states:

 *

 * OPTIMAL	- Client device has atleast one redundant path.

 * DEGRADED	- No redundant paths (critical).  Failure in the current active

 *                path would result in data access failures.

 * FAILED 	- No paths are available to access this device.

 *

 * Locking order:

 *

 * _NOTE(LOCK_ORDER(mdi_mutex, mdi_client::ct_mutex))

 * _NOTE(LOCK_ORDER(mdi_client::ct_mutex devinfo_tree_lock))

 */

typedef struct mdi_client {

	kmutex_t		ct_mutex;	/* per-client mutex	*/

	struct mdi_client	*ct_hnext;	/* next client		*/

	struct mdi_client	*ct_hprev;	/* prev client		*/

	dev_info_t		*ct_dip;	/* client devi handle	*/

	struct mdi_vhci		*ct_vhci;	/* vHCI back ref	*/

	char			*ct_drvname;	/* client driver name	*/

	char			*ct_guid;	/* client guid		*/

	void			*ct_cprivate;	/* client driver private */

	client_lb_t		ct_lb;		/* load balancing scheme */

	client_lb_args_t	*ct_lb_args; 	/* load balancing args */

	int			ct_flags;	/* Driver op. flags	*/

	int			ct_state;	/* state information	*/

	int			ct_failover_flags;	/* Failover args */

	int			ct_failover_status;	/* last fo status */

	kcondvar_t		ct_failover_cv;	/* Failover status cv	*/

	int			ct_path_count;	/* multi path count	*/

	mdi_pathinfo_t		*ct_path_head;	/* multi path list head	*/

	mdi_pathinfo_t		*ct_path_tail;	/* multi path list tail	*/

	mdi_pathinfo_t		*ct_path_last;	/* last path used for i/o */

	int			ct_unstable;	/* Paths in transient state */

	kcondvar_t		ct_unstable_cv;	/* Paths in transient state */

	int			ct_power_cnt;	/* Hold count on parent power */

	kcondvar_t		ct_powerchange_cv;

					/* Paths in power transient state */

	int			ct_powercnt_held;

					/* ct_power_cnt held in pre_unconfig */

	int			ct_powercnt_reset;

					/* ct_power_cnt was resetted */

	void			*ct_vprivate;	/* vHCI driver private	*/

} mdi_client_t;

/*

 * per-Client device locking definitions

 */

#define	MDI_CLIENT_LOCK(ct)		mutex_enter(&((ct))->ct_mutex)

#define	MDI_CLIENT_TRYLOCK(ct)		mutex_tryenter(&((ct))->ct_mutex)

#define	MDI_CLIENT_UNLOCK(ct)		mutex_exit(&((ct))->ct_mutex)

/*

 * A Client device is in unstable while one or more paths are in transitional

 * state.  We do not allow failover to take place while paths are in transient

 * state. Similarly we do not allow state transition while client device

 * failover is in progress.

 */

#define	MDI_CLIENT_UNSTABLE(ct)		(ct)->ct_unstable++;

#define	MDI_CLIENT_STABLE(ct) { \

	(ct)->ct_unstable--; \

	if ((ct)->ct_unstable == 0) { \

		cv_broadcast(&(ct)->ct_unstable_cv); \

	} \

}

/*

 * Client driver instance state definitions:

 */

#define	MDI_CLIENT_FLAGS_OFFLINE		0x00000001

#define	MDI_CLIENT_FLAGS_SUSPEND		0x00000002

#define	MDI_CLIENT_FLAGS_POWER_DOWN		0x00000004

#define	MDI_CLIENT_FLAGS_DETACH			0x00000008

#define	MDI_CLIENT_FLAGS_FAILOVER		0x00000010

#define	MDI_CLIENT_FLAGS_REPORT_DEV		0x00000020

#define	MDI_CLIENT_FLAGS_PATH_FREE_IN_PROGRESS	0x00000040

#define	MDI_CLIENT_FLAGS_ASYNC_FREE		0x00000080

#define	MDI_CLIENT_FLAGS_DEV_NOT_SUPPORTED	0x00000100

#define	MDI_CLIENT_FLAGS_POWER_TRANSITION	0x00000200

#define	MDI_CLIENT_SET_OFFLINE(ct) \

	    ((ct)->ct_flags |= MDI_CLIENT_FLAGS_OFFLINE)

#define	MDI_CLIENT_SET_ONLINE(ct) \

	    ((ct)->ct_flags &= ~MDI_CLIENT_FLAGS_OFFLINE)

#define	MDI_CLIENT_IS_OFFLINE(ct) \

	    ((ct)->ct_flags & MDI_CLIENT_FLAGS_OFFLINE)