path: root/usr/src/cmd/lvm/metassist/layout/layout_request.c

/*
 * 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.
 */

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

#include <assert.h>
#include <string.h>
#include <libintl.h>

#include "volume_error.h"
#include "volume_defaults.h"
#include "volume_dlist.h"
#include "volume_output.h"
#include "volume_request.h"

#include "layout_device_cache.h"
#include "layout_discovery.h"
#include "layout_dlist_util.h"
#include "layout_request.h"
#include "layout_slice.h"
#include "layout_validate.h"

#define	_LAYOUT_REQUEST_C

static char *_request_diskset = NULL;
static devconfig_t *_toplevel_request = NULL;
static defaults_t *_defaults = NULL;

/*
 * This file contains code which handles various aspects of the
 * request and defaults devconfig_t structs passed to the layout
 * module.
 *
 * Functions are provided which determine what devices are available
 * for use by the various volume layout mechanisms. These are based
 * on the user specified available/unavailable devices included in
 * a request or in the defaults associated with the destination diskset.
 */

/*
 * A struct to hold device "specifications" extracted from a user
 * specified device name.  This struct is used to compare the user's
 * available and unavailable device specifications against physical
 * devices attached to the system.
 *
 * The spec struct holds one of two different specifications: if the
 * user supplied device name is parsable as a CTD name, it is parsed
 * into the component ids.  Otherwise, it is stored as is.
 *
 * The CTD name space implies a device hierarchy and metassist
 * supports an implied wildcarding scheme for the CTD name space.
 * A CTD specification from the user is of the form cX, cXdX,
 * cXdXsX, cXtX, cXtXdX, or cXtXdXsX, so it may or may nor
 * correspond to an individual physical device depending on
 * the context.
 *
 * For example, "c1" can mean the controller/HBA with the
 * name "c1" or it can mean all devices attached to the
 * controller named "c1".
 *
 * The ctd specs make matching physical devices against a
 * user specification easier since the matching is based on
 * the numeric values extracted from the cXtXdXsX string
 * and not on the strings themselves.  The strings are
 * troublesome because of situations like "c1" being
 * compared to "c11t1d0s0" and getting false matches.
 *
 * The ID_UNSPECIFIED value is used to flag components
 * that were not in the CTD name:
 *
 * "c3" -> { ctrl=3, target=ID_UNSPECIFIED,
 *		lun=ID_UNSPECIFIED, slice=ID_UNSPECIFIED }
 *
 * "c3t2" -> { ctrl=3, target=2,
 *		lun=ID_UNSPECIFIED, slice=ID_UNSPECIFIED }
 */

#define	ID_UNSPECIFIED	-1
typedef struct {
	int	ctrl;
	int	target;
	int	lun;
	int	slice;
	boolean_t is_ide;
} ctd_spec_t;

typedef enum {
	SPEC_TYPE_CTD = 0,
	SPEC_TYPE_RAW,
	SPEC_TYPE_OTHER
} spec_type_t;

typedef struct {
	spec_type_t type;
	union {
		ctd_spec_t *ctd;
		char	*raw;
	} data;
} device_spec_t;

static int get_spec_for_name(
	char	*name,
	device_spec_t **id);

static int create_device_spec(
	char	*name,
	device_spec_t **spec);

static int create_device_ctd_spec(
	char	*name,
	device_spec_t **spec);

static int create_device_raw_spec(
	char	*name,
	device_spec_t **spec);

static void destroy_device_spec(
	device_spec_t *spec);

static boolean_t ctd_spec_includes_device(
	device_spec_t *spec,
	device_spec_t *device);

static boolean_t raw_spec_includes_device(
	device_spec_t *spec,
	device_spec_t *device);

/*
 * get_spec_for_name builds up a cached mapping of device
 * names to the corresponding device_spec_t structs.
 *
 * This saves repeatedly converting the device names, which
 * could get expensive since devices are checked against the
 * user specified available/unavailable devices a lot.
 *
 * The cache is implemented as a list of these structs:
 */
typedef struct {

	char		*name;
	device_spec_t	*device_spec;

} spec_cache_t;

static dlist_t	*_spec_cache = NULL;

static int destroy_spec_cache();
static int compare_name_to_spec_cache_name(
	void *name, void *list_item);

/*
 * The user specified available/unavailable devices are
 * accessed frequently during layout. To make this more
 * efficient, the char *arrays of available/unavailable
 * specifications for a request or defaults devconfig_t
 * object are converted to device_spec_ts the first time
 * they're accessed and then cached using this struct:
 */
typedef struct {

	devconfig_t	*request;

	/*
	 * avail_specs_list is a list of device spec_t
	 * corresponding to available devices specified
	 * in the request object
	 */
	dlist_t *avail_specs_list;

	/*
	 * unavail_specs_list is a list of device spec_t
	 * corresponding to unavailable devices specified
	 * in the request object
	 */
	dlist_t *unavail_specs_list;

} request_spec_list_t;

dlist_t *_request_spec_list_cache = NULL;

static int destroy_request_spec_list_cache();
static void destroy_request_spec_list_entry(void *obj);

static int compare_request_to_request_spec_list_request(
	void *object,
	void *list_item);

static int convert_usernames_to_specs(
	char **specs,
	dlist_t **list);

/* other private functions */
static int is_device_avail(
	dm_descriptor_t	desc,
	devconfig_t	*request,
	boolean_t	*avail);

static int is_named_device_avail(
	devconfig_t	*request,
	char		*device_name,
	boolean_t	check_aliases,
	boolean_t	*avail);

static int avail_list_includes_device_name(
	dlist_t		*list,
	char		*device_name,
	boolean_t	check_aliases,
	boolean_t	*includes);

static int unavail_list_includes_device_name(
	dlist_t		*list,
	char		*device_name,
	boolean_t	check_aliases,
	boolean_t	*includes);

static int spec_includes_device_name(
	device_spec_t *spec,
	char		 *device_name,
	boolean_t	check_aliases,
	boolean_t	*includes);

static boolean_t spec_includes_device(
	device_spec_t *spec,
	device_spec_t *device);

static int disk_get_avail_space(
	devconfig_t	*request,
	dm_descriptor_t disk,
	uint64_t	*avail);

static int compare_hba_n_avail_disks(
	void		*obj1,
	void		*obj2);

/*
 * FUNCTION:	release_request_caches()
 *
 * RETURNS:	0
 *
 * PURPOSE:	cleanup the module private caches.
 */
int
release_request_caches()
{
	(void) destroy_request_spec_list_cache();
	(void) destroy_spec_cache();

	return (0);
}
/*
 * FUNCTION:	int set_request_diskset(char *)
 *
 * INPUT:	char * - pointer to the diskset name
 * OUTPUT:	0 - success
 *		!0 - validation failure
 * RETURNS:
 *
 * PURPOSE:	set the module global diskset name.
 */
int
set_request_diskset(
	char	*dsname)
{
	_request_diskset = dsname;

	if (dsname == NULL || dsname[0] == '\0') {
	    volume_set_error(
		    gettext("No disk set specified in request\n"));
	    return (-1);
	}

	return (0);
}

/*
 * FUNCTION:	char *get_request_diskset()
 *
 * INPUT:	none   -
 * OUTPUT:	none   -
 * RETURNS:	char * - pointer to the currently set diskset name
 *
 * PURPOSE:	get the global name of the current diskset.
 */
char *
get_request_diskset()
{
	return (_request_diskset);
}

/*
 * FUNCTION:	void unset_request_diskset()
 *
 * PURPOSE:	unset the module global diskset name.
 */
void
unset_request_diskset(
	char	*dsname)
{
	_request_diskset = NULL;
}

/*
 * FUNCTION:	int set_toplevel_request(devconfig_t *)
 *
 * INPUT:	devconfig_t * - pointer to the diskset request
 * OUTPUT:	0 - success
 *		!0 - validation failure
 * RETURNS:
 *
 * PURPOSE:	set the module global toplevel request struct.
 *		this will be set within the only public entry
 *		point to the module -- get_layout()
 *
 * SIDEEFFECT:	The devconfig_t's list of available and unavailable
 * 		devices will be validated.
 */
int
set_toplevel_request(
	devconfig_t	*req)
{
	_toplevel_request = req;

	return (validate_request_avail_unavail(req));
}

/*
 * FUNCTION:	void unset_toplevel_request()
 *
 * PURPOSE:	unset the layout module global toplevel request struct.
 *
 */
void
unset_toplevel_request()
{
	_toplevel_request = NULL;
}

/*
 * FUNCTION:	int set_defaults(devconfig_t *)
 *
 * INPUT:	devconfig_t * - pointer to the global defaults devconfig_t
 * OUTPUT:	0 - success
 *		!0 - validation failure
 * RETURNS:
 *
 * PURPOSE:	set the module global defaults struct.
 *		this will be set within the only public entry
 *		point to the module -- get_layout()
 *
 * SIDEEFFECT:	The devconfig_t's list of available and unavailable
 * 		devices will be validated.
 */
int
set_request_defaults(
	defaults_t *defaults)
{
	int	error = 0;
	devconfig_t *diskset = NULL;

	_defaults = defaults;

	if ((error = defaults_get_diskset_by_name(
	    _defaults, get_request_diskset(), &diskset)) == 0) {

	    error = validate_request_avail_unavail(diskset);

	} else if (error == ENOENT) {
	    /* no defaults to verify */
	    error = 0;
	}

	return (error);
}

/*
 * FUNCTION:	void unset_request_defaults()
 *
 * PURPOSE:	unset the layout module global defaults struct.
 *
 */
void
unset_request_defaults()
{
	_defaults = NULL;
}

/*
 * FUNCTION:	get_stripe_min_comp(devconfig_t *req, uint16_t *val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a uint64_t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the minimum of components
 *		for striped volumes satisfying the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 */
int
get_stripe_min_comp(
	devconfig_t	*req,
	uint16_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_stripe_mincomp(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	}

	if (*val == 0) {
	    if ((error = defaults_get_stripe_mincomp(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_stripe_max_comp(devconfig_t *req, uint16_t *val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a uint64_t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the maximum number of components
 *		for striped volumes satisfying the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 */
int
get_stripe_max_comp(
	devconfig_t	*req,
	uint16_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_stripe_maxcomp(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	}

	if (*val == 0) {
	    if ((error = defaults_get_stripe_maxcomp(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_stripe_interlace(devconfig_t *req, uint64_t *val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a uint64_t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the interlace value for striped
 *		volumes satisfying the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 *
 *		If no value is explictly specified, ERR_ATTR_UNSET is
 *		returned.
 */
int
get_stripe_interlace(
	devconfig_t	*req,
	uint64_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_stripe_interlace(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	    error = 0;
	}

	if (*val == 0) {
	    if ((error = defaults_get_stripe_interlace(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_mirror_read_strategy(devconfig_t *req,
 *			mirror_read_strategy_t *val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a mirror_read_strategy_t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the write strategy mirrored volumes
 *		should have for volumes satisfying the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 *
 *		If no value is explictly specified, ERR_ATTR_UNSET is
 *		returned.
 */
int
get_mirror_read_strategy(
	devconfig_t	*req,
	mirror_read_strategy_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_mirror_read(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	}

	if (*val == 0) {
	    if ((error = defaults_get_mirror_read(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_mirror_write_strategy(devconfig_t *req,
 *			mirror_write_strategy_t *val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a mirror_write_strategy_t to hold result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the write strategy mirrored volumes
 *		should have for volumes satisfying the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 *
 *		If no value is explictly specified, ERR_ATTR_UNSET is
 *		returned.
 */
int
get_mirror_write_strategy(
	devconfig_t	*req,
	mirror_write_strategy_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_mirror_write(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	}

	if (*val == 0) {
	    if ((error = defaults_get_mirror_write(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_mirror_pass(devconfig_t *req, uint16_t *val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a uint16_t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the resync pass mirrored volumes
 *		should have for volumes satisfying the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 *
 *		If no value is explictly specified, ERR_ATTR_UNSET is
 *		returned.
 */
int
get_mirror_pass(
	devconfig_t	*req,
	uint16_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_mirror_pass(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	}

	if (*val == 0) {
	    if ((error = defaults_get_mirror_pass(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_mirror_nsubs(devconfig_t *req, uint16_t *val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a uint16_t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines how many submirrors mirrored
 *		volumes should have for volumes satisfying the input
 *		request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 */
int
get_mirror_nsubs(
	devconfig_t	*req,
	uint16_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_mirror_nsubs(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	}

	if (*val == 0) {
	    if ((error = defaults_get_mirror_nsubs(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_volume_faultrecov(devconfig_t *req, boolean_t *val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a boolean_t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines whether data redundant volumes
 *		should also have fault recovery (e.g., HSPs) for volumes
 *		satisfying the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 */
int
get_volume_faultrecov(
	devconfig_t	*req,
	boolean_t	*val)
{
	int		error = 0;

	*val = B_FALSE;

	if ((error = devconfig_get_volume_usehsp(req, val)) != 0) {
	    if (error == ERR_ATTR_UNSET) {
		component_type_t	type = TYPE_UNKNOWN;
		(void) devconfig_get_type(req, &type);

		switch (type) {
		case TYPE_MIRROR:
		    error = defaults_get_mirror_usehsp(
			    _defaults, get_request_diskset(), val);
		    break;

		case TYPE_STRIPE:
		    error = defaults_get_stripe_usehsp(
			    _defaults, get_request_diskset(), val);
		    break;

		case TYPE_CONCAT:
		    error = defaults_get_concat_usehsp(
			    _defaults, get_request_diskset(), val);
		    break;

		case TYPE_VOLUME:
		    error = defaults_get_volume_usehsp(
			    _defaults, get_request_diskset(), val);
		    break;
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_volume_redundancy_level(devconfig_t *req, uint16_t val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a uint16-t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the appropriate level of data
 *		redundancy a volume should have for volumes satisfying
 *		the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 */
int
get_volume_redundancy_level(
	devconfig_t	*req,
	uint16_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_volume_redundancy_level(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	}

	if (*val == 0) {
	    if ((error = defaults_get_volume_redundancy_level(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_volume_npaths(devconfig_t *req, uint16_t val)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		val	- pointer to a uint16-t to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the appropriate level of datapath
 *		redundancy a slice component should have for volumes
 *		satisfying the input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 */
int
get_volume_npaths(
	devconfig_t	*req,
	uint16_t	*val)
{
	int		error = 0;

	*val = 0;

	if ((error = devconfig_get_volume_npaths(req, val)) != 0) {
	    if (error != ERR_ATTR_UNSET) {
		return (error);
	    }
	}

	if (*val == 0) {
	    if ((error = defaults_get_volume_npaths(
		_defaults, get_request_diskset(), val)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    return (error);
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_default_hsp_name(devconfig_t *req, char **hspname)
 * INPUT:	req	- a devconfig_t pointer to the current request
 *		hspname	- pointer to a char * to hold the result, if any
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which determines the default HSP name for the
 *		input request.
 *
 *		The value to use is taken from the input request, the
 *		toplevel diskset request, the diskset defaults or the
 *		global defaults.
 */
int
get_default_hsp_name(
	devconfig_t	*req,
	char		**name)
{
	int		error = 0;

	*name = NULL;

	if ((error = defaults_get_hsp_name(_defaults,
	    get_request_diskset(), name)) != 0) {
	    if (error != ENOENT) {
		return (error);
	    }
	    error = 0;
	}

	return (error);
}

/*
 * FUNCTION:	slice_is_available(char *sname, devconfig_t *request,
 *			boolean_t bool)
 * INPUT:	sname	- a slice name
 *		request	- pointer to a devconfig_t struct representing
 *				the current layout request being processed
 * 		bool	- pointer to a boolean to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	Validation helper which determines if the named slice can
 *		be used as a volume component when satisfying the input
 *		request.
 *
 *		Check if the slice appears in the known slice list,
 *		then check the request's available and unavailable
 *		device specifications.
 */
int
slice_is_available(
	char		*sname,
	devconfig_t	*request,
	boolean_t	*bool)
{
	dm_descriptor_t	slice = (dm_descriptor_t)0;
	int		error = 0;

	*bool = B_FALSE;

	if ((error = slice_get_by_name(sname, &slice)) != 0) {
	    return (error);
	}

	if (slice == (dm_descriptor_t)0) {
	    /* no slice found */
	    return (ENODEV);
	}

	if (error == 0) {
	    error = is_named_device_avail(request, sname, B_TRUE, bool);
	}

	return (error);
}

/*
 * FUNCTION:	get_disks_for_target(char *name, dlist_t **disks)
 *
 * INPUT:	name	- a char* device CTD name
 *
 * OUTPUT:	disks	- disks matching the input target name
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise
 *
 * PURPOSE:	Validation helper function which finds all disks "on" the
 *		input target.
 *
 *		The input name is assumed to be a target name, cXtX, and
 *		the list of known disks is searched to find any disk that
 *		looks to be "on" that target.
 *
 *		"On" is determined by comparing a disk's name and
 *		aliases to the target to see if they match.
 */
int
get_disks_for_target(
	char *name,
	dlist_t **disks)
{
	int error = 0;
	device_spec_t *targetid = NULL;

	error = get_spec_for_name(name, &targetid);
	if (error == 0) {
	    dlist_t *known_disks = NULL;
	    dlist_t *iter = NULL;

	    get_known_disks(&known_disks);
	    for (iter = known_disks;
		(iter != NULL) && (error == 0);
		iter = iter->next) {

		dm_descriptor_t disk = (uintptr_t)iter->obj;
		device_spec_t *diskid = NULL;
		char	*diskname = NULL;
		dlist_t *diskaliases = NULL;
		dlist_t *item;

		((error = get_display_name(disk, &diskname)) != 0) ||
		(error = get_aliases(disk, &diskaliases)) ||
		(error = get_spec_for_name(diskname, &diskid));

		if (error == 0) {
		    if (spec_includes_device(targetid, diskid) == B_TRUE) {
			/* add disk */
			if ((item = dlist_new_item((void *)(uintptr_t)disk)) ==
			    NULL) {
			    error = ENOMEM;
			} else {
			    *disks = dlist_append(item, *disks, AT_HEAD);
			}
		    } else {
			/* check disk's aliases */
			dlist_t *iter2;
			for (iter2 = diskaliases;
			    (iter2 != NULL) && (error == 0);
			    iter2 = iter2->next) {

			    char *aliasname = NULL;
			    device_spec_t *aliasid = NULL;
			    error = get_display_name(disk, &aliasname);
			    error = get_spec_for_name(aliasname, &aliasid);

			    if (spec_includes_device(
					targetid, aliasid) == B_TRUE) {

				/* alias matched, add disk */
				item = dlist_new_item((void *)(uintptr_t)disk);
				if (item == NULL) {
				    error = ENOMEM;
				} else {
				    *disks =
					dlist_append(item, *disks, AT_HEAD);
				}
			    }
			}
		    }
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	select_hbas_with_n_disks(devconfig_t *request,
 *			dlist_t	*hbas, int mindisks, dlist_t **selhbas,
 *			dlist_t **seldisks)
 *
 * INPUT:	request	- pointer to a devconfig_t struct representing
 *				the current layout request being processed
 * 		hbas	- pointer to a list of HBAs
 *		mindisks - minimum number of disks required on the HBAs
 *
 * OUTPUT:	selhbas	- pointer to a list containing the HBAs with at
 *				least mindisks available disks.
 *		seldisks - pointer to a list containing the available disks
 *				for the HBAs in selhbas
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which counts the number of available disks associated
 *		with each of the input HBAs and adds those that have at
 *		least mindisks to the output list.
 *
 *		Only available disks that have available space are counted.
 *
 *		Disks connected thru multiple HBAs are only counted for
 *		the first HBA they're accessed through.
 *
 *		The list of HBAs returned will be in descending order,
 *		i.e., HBAs with more disks come before those with fewer.
 *
 *		The returned lists of HBAs and disks must be passed to
 *		dlist_free_items() to recover the space allocated to hold
 *		each list item.
 *
 *		for (each HBA) {
 *
 *		    select HBA
 *		    get available disks on HBA
 *
 *		    for (each disk) {
 *			if (disk is not in selected disk list)
 *			    add it to the list
 *			else
 *			    count it as a distinct disk on this HBA
 *		    }
 *
 *		    if (this HBA has >= mindisks distinct disks)
 *			add this HBA to the list of returned HBAs
 *
 *		}
 */
int
select_hbas_with_n_disks(
	devconfig_t	*request,
	dlist_t		*hbas,
	int		mindisks,
	dlist_t		**selhbas,
	dlist_t		**seldisks)
{
	dlist_t		*iter = NULL;
	int		error = 0;

	*selhbas = NULL;
	*seldisks = NULL;

	/* for each input HBA */
	for (iter = hbas; (error == 0) && (iter != NULL); iter = iter->next) {

	    dm_descriptor_t hba = (uintptr_t)iter->obj;
	    dlist_t *iter2 = NULL;
	    dlist_t *disks = NULL;
	    uint64_t space = 0;
	    uint16_t ndistinct = 0;

	    error = hba_get_avail_disks_and_space(request, hba, &disks, &space);

	    /* for each of this HBA's disks */
	    for (iter2 = disks;
		(iter2 != NULL) && (error == 0);
		iter2 = iter2->next) {

		dm_descriptor_t disk = (uintptr_t)iter2->obj;

		/* unique disk? has it been seen thru some other HBA? */
		if (dlist_contains(*seldisks, (void *)(uintptr_t)disk,
		    compare_descriptor_names) != B_TRUE) {

		    /* distinct, add to list of all_distinct */
		    dlist_t *item = dlist_new_item((void *)(uintptr_t)disk);
		    if (item == NULL) {
			error = ENOMEM;
		    } else {

			*seldisks =
			    dlist_append(item, *seldisks, AT_HEAD);

			/* increment this HBA's distinct disk count */
			++ndistinct;
		    }
		}
	    }

	    if (ndistinct >= mindisks) {

		/* this HBA has minimum # of disks, add to output list */
		dlist_t	*item = dlist_new_item((void *)(uintptr_t)hba);
		if (item == NULL) {
		    error = ENOMEM;
		} else {
		    *selhbas =
			dlist_insert_ordered(
				item, *selhbas, DESCENDING,
				compare_hba_n_avail_disks);

		    /* save # of disks for ordering the list */
		    hba_set_n_avail_disks(hba, ndistinct);
		}
	    }

	    dlist_free_items(disks, NULL);
	}

	if (error != 0) {
	    oprintf(OUTPUT_TERSE,
		    gettext("failed selecting HBAs with n disks: %d\n"),
		    error);

	    dlist_free_items(*selhbas, NULL);
	    *selhbas = NULL;
	    dlist_free_items(*seldisks, NULL);
	    *seldisks = NULL;
	}

	return (error);
}

/*
 * FUNCTION:	hba_get_avail_disks_and_space(devconfig_t *request,
 *			dm_descriptor_t hba, dlist_t **disks, uint64_t *space)
 *
 * INPUT:	request	- pointer to a devconfig_t struct representing
 *				the current layout request being processed
 * 		hba	- dm_descriptor_t handle for an HBA
 *
 * OUTPUT:	disks	- pointer to a list to hold the computed available
 *				disks
 * 		avail	- pointer to a uint64_t to hold the aggregate
 *				available space on the available disks
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which examines the disks associated with the
 *		input HBA and assembles a list of those that are available.
 *
 *		Available is defined as being in the usable list, having
 *		unused space and not specifically excluded by the request's
 *		list of unavailable devices.
 *
 *		The returned list must be passed to dlist_free_items()
 *		to recover the memory allocated to hold each list item.
 */
int
hba_get_avail_disks_and_space(
	devconfig_t	*request,
	dm_descriptor_t	hba,
	dlist_t		**disks,
	uint64_t	*space)
{
	dlist_t		*usable_disks = NULL;
	dlist_t		*iter = NULL;
	int		error = 0;

	*disks = NULL;

	/* for each usable disk */
	error = get_usable_disks(&usable_disks);
	for (iter = usable_disks;
	    (error == 0) && (iter != NULL);
	    iter = iter->next) {

	    dm_descriptor_t disk = (uintptr_t)iter->obj;
	    boolean_t	avail = B_FALSE;
	    dlist_t	*hbas = NULL;

	    /* is disk attached to HBA in question? */
	    error = disk_get_hbas(disk, &hbas);
	    if (error != 0) {
		continue;
	    }

	    if (dlist_contains(hbas, (void *)(uintptr_t)hba,
			compare_descriptor_names) == B_TRUE) {

		/* is disk available? */
		error = is_device_avail(disk, request, &avail);
		if ((error == 0) && (avail == B_TRUE)) {
		    uint64_t disk_space = 0;

		    /* does disk have available space? */
		    error = disk_get_avail_space(request, disk, &disk_space);
		    if ((error == 0) && (disk_space > 0)) {

			dlist_t *item = dlist_new_item((void *)(uintptr_t)disk);
			if (item == NULL) {
			    error = ENOMEM;
			} else {
			    *disks = dlist_append(item, *disks, AT_HEAD);
			}

			*space += disk_space;
		    }
		}
	    }

	    dlist_free_items(hbas, NULL);
	}

	if (error != 0) {
	    dlist_free_items(*disks, NULL);
	    *disks = NULL;
	}

	return (error);
}

/*
 * FUNCTION:	disk_get_avail_space(devconfig_t *request,
 *			dlist_t *disks, uint64_t space)
 *
 * INPUT:	request	- pointer to a devconfig_t struct representing
 *				the current layout request being processed
 * 		disks	- pointer to a list of disks
 * 		space	- pointer to a uint64_t to hold the computed available
 *				space
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which iterates the input list of disks and determines
 *		the aggregate amount of available space they represent.
 *
 *		Only disk slices that are in the usable slice list and not
 *		specifically excluded by the request's list of unavailable
 *		devices	will contribute to the aggregate space computation.
 */
static int
disk_get_avail_space(
	devconfig_t	*request,
	dm_descriptor_t	disk,
	uint64_t	*space)
{
	dlist_t		*usable_slices = NULL;
	dlist_t		*iter = NULL;
	int		error = 0;

	*space = 0;

	/* for each usable slice */
	error = get_usable_slices(&usable_slices);
	for (iter = usable_slices;
	    (error == 0) && (iter != NULL);
	    iter = iter->next) {

	    dm_descriptor_t slice = (uintptr_t)iter->obj;
	    dm_descriptor_t slice_disk;
	    boolean_t	avail = B_FALSE;
	    boolean_t	reserved = B_FALSE;
	    boolean_t	used = B_FALSE;

	    /* is slice on disk in question? */
	    if (((error = slice_get_disk(slice, &slice_disk)) != 0) ||
		(compare_descriptor_names((void *)(uintptr_t)slice_disk,
			(void *)(uintptr_t)disk) != 0)) {
		continue;
	    }

	    /* is slice reserved by an explicit layout request? */
	    if (((error = is_reserved_slice(slice, &reserved)) != 0) ||
		(reserved == B_TRUE)) {
		continue;
	    }

	    /* is slice used by a pending layout request? */
	    if (((error = is_used_slice(slice, &used)) != 0) ||
		(used == B_TRUE)) {
		continue;
	    }

	    /* is slice available? */
	    if (((error = is_device_avail(slice, request, &avail)) == 0) &&
		(avail == B_TRUE)) {

		/* does slice have usable space? */
		uint64_t size = 0;
		if ((error = slice_get_size(slice, &size)) == 0) {
		    *space += size;
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	disks_get_avail_slices(devconfig_t *request,
 *			dlist_t *disks, dlist_t **slices)
 *
 * INPUT:	request	- pointer to a devconfig_t struct representing
 *				the current layout request being processed
 * 		disks	- pointer to a list of disks
 * 		slices	- pointer to an output list of disks
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	helper which iterates the input list of disks and builds a
 *		new list which contains disks that are determined to be
 * 		available for satisfying the input request.
 *
 *		A disk must contain at least one slice in the available
 * 		slice list as well as have available space in order
 *		to be available.
 */
int
disks_get_avail_slices(
	devconfig_t	*request,
	dlist_t		*disks,
	dlist_t		**slices)
{
	dlist_t		*usable_slices = NULL;
	dlist_t		*iter = NULL;
	int		error = 0;

	*slices = NULL;

	/* for each usable slice */
	error = get_usable_slices(&usable_slices);
	for (iter = usable_slices;
	    (error == 0) && (iter != NULL);
	    iter = iter->next) {

	    dm_descriptor_t slice = (uintptr_t)iter->obj;
	    dm_descriptor_t disk = (dm_descriptor_t)0;
	    boolean_t	avail = B_FALSE;
	    boolean_t	reserved = B_FALSE;
	    boolean_t	used = B_FALSE;

	    /* is slice on a disk in the input list? */
	    if (((error = slice_get_disk(slice, &disk)) != 0) ||
		(dlist_contains(disks, (void *)(uintptr_t)disk,
			compare_descriptor_names) != B_TRUE)) {
		continue;
	    }

	    /* is slice reserved by an explicit layout request? */
	    if (((error = is_reserved_slice(slice, &reserved)) != 0) ||
		(reserved == B_TRUE)) {
		continue;
	    }

	    /* is slice used by a pending layout request? */
	    if (((error = is_used_slice(slice, &used)) != 0) ||
		(used == B_TRUE)) {
		continue;
	    }

	    /* is slice available? */
	    if (((error = is_device_avail(slice, request, &avail)) == 0) &&
		(avail == B_TRUE)) {

		/* does slice have available space? */
		uint64_t size = 0;
		error = slice_get_size(slice, &size);
		if ((error == 0) && (size > 0)) {
		    dlist_t *item = dlist_new_item((void *)(uintptr_t)slice);
		    if (item == NULL) {
			error = ENOMEM;
		    } else {
			*slices = dlist_append(item, *slices, AT_TAIL);
		    }
		}
	    }
	}

	if (error != 0) {
	    dlist_free_items(*slices, NULL);
	    *slices = NULL;
	}

	return (error);
}


/*
 * FUNCTION:	get_hbas_and_disks_used_by_volumes(dlist_t *volumes,
 *			dlist_t **hbas,	dlist_t **disks)
 *
 * INPUT:	volumes	- pointer to a list of devconfig_t volumes
 *
 * OUTPUT:	hbas - a list of HBAs utilized by the input volumes
 *		disks - a list of disks utilized by the input volumes
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise
 *
 * PURPOSE:	An aggregate list of HBAs and disks used by the input volumes
 *		is built up by iterating the list of volumes and calling
 *		get_hbas_disks_used_by_volume() to determine the HBAs and disk
 *		used by each volume.
 *
 *		The returned lists of HBAs and disks may contain duplicates.
 */
int
get_hbas_and_disks_used_by_volumes(
	dlist_t		*volumes,
	dlist_t		**hbas,
	dlist_t		**disks)
{
	dlist_t		*iter = NULL;
	int		error = 0;

	for (iter = volumes;
	    (iter != NULL) && (error == 0);
	    iter = iter->next) {
	    error = get_hbas_and_disks_used_by_volume(
		    (devconfig_t *)iter->obj, hbas, disks);
	}

	return (error);
}

/*
 * FUNCTION:	get_hbas_and_disks_used_by_volume(devconfig_t *volume,
 *			dlist_t **hbas, dlist_t **disks)
 *
 * INPUT:	volume	- pointer to a devconfig_t volume
 *
 * OUTPUT:	hbas - a list of HBAs updated to include those utilized
 *			by the input volume
 *		disks - a list of disks updated to inlclude those utilized
 *			by the input volume
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise
 *
 * PURPOSE:	The volume's components are iterated and the disks and HBAs
 *		for each component are determined and appended to the input
 *		lists of HBAs and disks.
 *
 *		The returned lists of HBAs and disks may contain duplicates.
 */
int
get_hbas_and_disks_used_by_volume(
	devconfig_t	*volume,
	dlist_t		**hbas,
	dlist_t		**disks)
{
	dlist_t		*iter = NULL;
	int		error = 0;

	for (iter = devconfig_get_components(volume);
	    (iter != NULL) && (error == 0);
	    iter = iter->next) {

	    devconfig_t	*dev = (devconfig_t *)iter->obj;
	    if (devconfig_isA(dev, TYPE_SLICE)) {

		dm_descriptor_t	disk = NULL;
		char		*name = NULL;

		/* get disk for component slice */
		((error = devconfig_get_name(dev, &name)) != 0) ||
		(error = get_disk_for_named_slice(name, &disk));
		if (error == 0) {
		    dlist_t *item = dlist_new_item((void *)(uintptr_t)disk);
		    if (item == NULL) {
			error = ENOMEM;
		    } else {
			*disks = dlist_append(item, *disks, AT_HEAD);
		    }
		}

		/* get HBAs for disk */
		if (error == 0) {
		    dlist_t *disk_hbas = NULL;
		    if ((error = disk_get_hbas(disk, &disk_hbas)) == 0) {
			/* the hba list may contain dups, but that's ok */
			*hbas = dlist_append(disk_hbas, *hbas, AT_HEAD);
		    }
		}

	    } else if (devconfig_isA(dev, TYPE_MIRROR)) {

		/* collect info for submirrors */
		dlist_t *iter1;
		for (iter1 = devconfig_get_components(dev);
		    (iter1 != NULL) && (error == 0);
		    iter1 = iter1->next) {
		    error = get_hbas_and_disks_used_by_volume(
			    (devconfig_t *)iter1->obj, hbas, disks);
		}

	    }
	}

	return (error);
}

/*
 * FUNCTION:	compare_hba_n_avail_disks(void *obj1, void *obj2)
 *
 * INPUT:	obj1	- opaque pointer
 * 		obj2	- opaque pointer
 *
 * RETURNS:	int	- <0 - if obj1 has fewer available disks than obj2
 *			   0 - if obj1 has the same # of available disks as obj2
 *			  >0 - if obj1 has more available disks than obj2
 *
 * PURPOSE:	dlist_t helper which compares the number of available disks
 *		for two HBAs represented as dm_descriptor_t handles.
 *
 *		Both input objects are assumed to be dm_descriptor_t handles.
 *
 *		The number of available disks associated with the HBAs was
 *		computed and saved in select_hbas_with_n_disks(), this
 *		function just checks the saved values.
 */
static int
compare_hba_n_avail_disks(
	void		*obj1,
	void		*obj2)
{
	uint16_t	n1 = 0;
	uint16_t	n2 = 0;

	assert(obj1 != NULL);
	assert(obj2 != NULL);

	(void) hba_get_n_avail_disks((uintptr_t)obj1, &n1);
	(void) hba_get_n_avail_disks((uintptr_t)obj2, &n2);

	return ((int)n1 - n2);
}

/*
 * FUNCTION:	is_device_avail(dm_descriptor_t desc,
 *			devconfig_t *request, boolean_t *avail)
 *
 * INPUT:	desc	- a dm_descriptor_t device handle
 *		request	- pointer to a devconfig_t struct representing
 *				the current layout request being processed
 * 		avail	- pointer to a boolean to hold the result
 *
 * RETURNS:	int	-  0 - on success
 *			  !0 - otherwise
 *
 * PURPOSE:	Internal helper which determines if the input device can
 *		be used as a volume component when satisfying the input
 *		request.
 *
 *		The device is assumed to be a known valid device.
 *
 *		The function checks if the device passes the request's
 *		available and unavailable device specifications.
 *
 *		The input device name may be either a DID name or a CTD
 *		name.  All name comparisons are done using the CTD name.
 */
static int
is_device_avail(
	dm_descriptor_t	desc,
	devconfig_t	*request,
	boolean_t	*avail)
{
	char		*name = NULL;
	int		error = 0;

	*avail = B_FALSE;

	if ((error = get_display_name(desc, &name)) == 0) {
	    error = is_named_device_avail(request, name, B_TRUE, avail);
	}

	return (error);
}

/*
 * FUNCTION:	compare_request_to_request_spec_list_request(
 *			void *request, void *list_item)
 *
 * INPUT:	request	- opaque pointer to a devconfig_t
 * 		list_item - opaque pointer to a request_spec_list_t
 *
 * RETURNS:	int	- 0 - if request is the same as list_item->request
 *			  !0 - otherwise
 *
 * PURPOSE:	dlist_t helper which compares the input request pointer
 *		to the list_item's request pointer for equality.
 *
 *		This function is the lookup mechanism for the lists of
 *		cached device_spec_ts representing available/unavailable
 *		devices for a given defaults_t request/defaults struct.
 *
 *		The defaults_t struct pointer is the lookup key.
 */
static int
compare_request_to_request_spec_list_request(
	void *request,
	void *list_item)
{
	request_spec_list_t *entry =
	    (request_spec_list_t *)list_item;

	assert(request != NULL);
	assert(entry != NULL);

	/* compare two devconfig_t pointers, if identical, return 0 */
	return ((devconfig_t *)request != entry->request);
}

/*
 * FUNCTION:	compare_device_spec_specificity(void *spec1, void *spec2)
 *
 * INPUT:	spec1	- opaque pointer to a device_spec_t
 * 		spec2	- opaque pointer to a device_spec_t
 *
 * RETURNS:	int	- <0 - if spec1 is less specific than spec2
 *			   0 - if spec1 is as specific than spec2
 *			  >0 - if spec1 is more specific than spec2
 *
 * PURPOSE:	dlist_t helper which compares the level of specificity
 *		in the two input device_spec_t structs.  The one
 *		which specifies more "components" of a cXtXdXsX device
 *		name is considered more specific.
 */
static int
compare_device_spec_specificity(
	void	*spec1,
	void	*spec2)
{
	if (spec1 == NULL || spec2 == NULL) {
	    return (-1);
	}

	if ((((device_spec_t *)spec1)->data.ctd->slice != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec2)->data.ctd->slice == ID_UNSPECIFIED)) {
	    /* spec1 has slice, spec2 does not, spec1 more specific */
	    return (1);
	}

	if ((((device_spec_t *)spec2)->data.ctd->slice != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec1)->data.ctd->slice == ID_UNSPECIFIED)) {
	    /* spec2 has slice, spec1 does not, spec2 more specific */
	    return (-1);
	}

	if ((((device_spec_t *)spec2)->data.ctd->slice != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec1)->data.ctd->slice != ID_UNSPECIFIED)) {
	    /* both spec1 and spec2 have slice */
	    return (0);
	}

	if ((((device_spec_t *)spec1)->data.ctd->lun != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec2)->data.ctd->lun == ID_UNSPECIFIED)) {
	    /* spec1 has lun, spec2 does not, spec1 more specific */
	    return (1);
	}

	if ((((device_spec_t *)spec2)->data.ctd->lun != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec1)->data.ctd->lun == ID_UNSPECIFIED)) {
	    /* spec2 has lun, spec1 does not, spec2 more specific */
	    return (-1);
	}

	if ((((device_spec_t *)spec2)->data.ctd->lun != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec1)->data.ctd->lun != ID_UNSPECIFIED)) {
	    /* both spec1 and spec2 have lun */
	    return (0);
	}

	if ((((device_spec_t *)spec1)->data.ctd->target != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec2)->data.ctd->target == ID_UNSPECIFIED)) {
	    /* spec1 has target, spec2 does not, spec1 more specific */
	    return (1);
	}

	if ((((device_spec_t *)spec2)->data.ctd->target != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec1)->data.ctd->target == ID_UNSPECIFIED)) {
	    /* spec2 has target, spec1 does not, spec2 more specific */
	    return (-1);
	}

	if ((((device_spec_t *)spec2)->data.ctd->target != ID_UNSPECIFIED) &&
	    (((device_spec_t *)spec1)->data.ctd->target != ID_UNSPECIFIED)) {
	    /* both spec1 and spec2 have target */
	    return (0);
	}

	/* both specify just ctrl */
	return (0);
}

/*
 * FUNCTION:	find_request_spec_list_entry(devconfig_t *request)
 *
 * INPUT:	request	- pointer to a devconfig_t struct
 *
 * RETURNS:	request_spec_list_entry - pointer to a
 *			request_spec_list_entry struct
 *
 * PURPOSE:	Lookup function which encapsulates the details of locating
 *		the device_spec_list_t cache entry for the input request.
 */
static request_spec_list_t *
find_request_spec_list_entry(
	devconfig_t *request)
{
	dlist_t *list_item = NULL;
	request_spec_list_t *entry = NULL;

	list_item = dlist_find(
		_request_spec_list_cache,
		(void *)request,
		compare_request_to_request_spec_list_request);

	if (list_item != NULL) {
	    entry = (request_spec_list_t *)list_item->obj;
	}

	return (entry);
}

/*
 * FUNCTION:	add_request_spec_list_entry(devconfig_t *request,
 *			char **avail_device_specs, char **unavail_device_specs,
 *			request_spec_list_entry_t **entry)
 *
 * INPUT:	entry - pointer to the request_spec_list_entry struct to be
 *			added to the cache.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which encapsulates the details of adding a
 *		device_spec_list_t cache entry.
 */
static int
add_request_spec_list_entry(
	request_spec_list_t *entry)
{
	dlist_t *list_item = dlist_new_item((void *)entry);

	if (list_item == NULL) {
	    return (ENOMEM);
	}

	_request_spec_list_cache = dlist_append(list_item,
		_request_spec_list_cache, AT_HEAD);

	return (0);
}

/*
 * FUNCTION:	make_request_spec_list_entry(devconfig_t *request,
 *			char **avail_device_specs, char **unavail_device_specs,
 *			request_spec_list_entry_t **entry)
 *
 * INPUT:	request	- pointer to a devconfig_t struct
 *		avail_device_specs - char * array of user specified available
 *			devices associated with the input request
 *		unavail_device_specs - char * array of user specified
 *			unavailable devices associated with the input
 *			request
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which encapsulates the details of generating a new
 *		the device_spec_list_t cache entry for the input request
 *		and its lists of avail/unavail devices.
 *
 *		Converts the input arrays of (un)available device names into
 *		equivalent lists of device_spec_t structs.
 *
 *		Creates a new cache entry, populates it and adds it to the
 *		cache.
 */
static int
make_request_spec_list_entry(
	devconfig_t *request,
	char	**avail_device_specs,
	char	**unavail_device_specs,
	request_spec_list_t **entry)
{
	int error = 0;
	dlist_t *list = NULL;

	*entry = calloc(1, sizeof (request_spec_list_t));
	if (*entry == NULL) {
	    return (ENOMEM);
	}

	(*entry)->request = request;

	/*
	 * map the avail_device_name array into a list of device_spec_t
	 * and save the list as the entry's available list
	 */
	error = convert_usernames_to_specs(
		avail_device_specs, &list);

	if (error == 0) {
	    (*entry)->avail_specs_list = list;
	}

	/*
	 * map the unavail_device_name array into a list of device_spec_t
	 * and save the list as the entry's unavailable list
	 */
	list = NULL;
	error = convert_usernames_to_specs(
		unavail_device_specs, &list);

	if (error == 0) {
	    (*entry)->unavail_specs_list = list;
	}

	if (error != 0) {
	    /* delete the partial entry */
	    destroy_request_spec_list_entry((void *)*entry);
	    *entry = NULL;
	}

	return (error);
}

/*
 * FUNCTION:	convert_usernames_to_specs(char **specs, dlist_t **list)
 *
 * INPUT:	specs	- char * array of device CTD names
 *
 * OUTPUT:	list	- pointer to a list of device_spec_t corresponding
 *				to each name in the input array
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which converts the input CTD device names to the
 *		equivalent device_spec_t structs.
 *
 *		Iterates the input array and converts each CTD name to a
 *		device_spec_t using get_spec_for_name().
 */
static int
convert_usernames_to_specs(
	char	**specs,
	dlist_t **list)
{
	int i = 0;
	int error = 0;

	/*
	 * For each spec in the array, get the corresponding
	 * device_spec_t and add it to the list.
	 *
	 * Any spec in the array that looks to be a DID name
	 * is first converted to its equivalent CTD name.
	 */
	for (i = 0;
	    (specs != NULL) && (specs[i] != NULL) && (error == 0);
	    i++) {

	    device_spec_t *spec = NULL;
	    char *userspec = specs[i];

	    error = get_spec_for_name(userspec, &spec);
	    if ((error == 0) && (spec != NULL)) {
		dlist_t *list_item = dlist_new_item((void *)spec);
		if (spec == NULL) {
		    error = ENOMEM;
		} else {
		    *list = dlist_insert_ordered
			(list_item, *list, DESCENDING,
				compare_device_spec_specificity);
		}
	    }
	}

	if (error != 0) {
	    /* the device_spec_t in the list items are maintained */
	    /* in a cache elsewhere, so don't free them here. */
	    dlist_free_items(*list, NULL);
	    *list = NULL;
	}

	return (error);
}

/*
 * FUNCTION:	destroy_request_spec_list_entry(void *entry)
 *
 * INPUT:	entry	- opaque pointer to a request_spec_list_t
 *
 * RETURNS:	nothing
 *
 * PURPOSE:	Function which reclaims memory allocated to a
 *		request_spec_list_t.
 *
 *		Frees memory allocated to the avail_spec_list and
 *		unavail_spec_list.  Entries in the list are not freed,
 *		since they are owned by the device_spec cache.
 */
static void
destroy_request_spec_list_entry(
	void *obj)
{
	request_spec_list_t *entry = (request_spec_list_t *)obj;

	if (entry != NULL) {
	    /* items in the list are in the spec_cache and will */
	    /* be cleaned up when it is destroyed. */
	    dlist_free_items(entry->avail_specs_list, NULL);
	    dlist_free_items(entry->unavail_specs_list, NULL);
	    free(entry);
	}
}

/*
 * FUNCTION:	destroy_request_spec_list_cache()
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which destroys all entries in the request_spec_list
 *		cache.
 */
static int
destroy_request_spec_list_cache()
{
	dlist_free_items(_request_spec_list_cache,
		destroy_request_spec_list_entry);
	_request_spec_list_cache = NULL;

	return (0);
}

/*
 * FUNCTION:	get_request_avail_spec_list(devconfig_t *request,
 *			dlist_t **list)
 *
 * INPUT:	request	- a pointer to a devconfig_t
 *
 * OUTPUT:	list	- pointer to a list of device_spec_t corresponding
 *				to the devices specified as available by the
 *				input request.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which locates or builds the list of device_spec_t
 *		for the available devices specified in the input request.
 *
 *		Looks up the input request in the request_spec_list cache.
 *		If there is currently no entry in the cache for the request,
 *		an entry is built and added.
 *
 *		The entry's list of available device_spec_t is returned.
 */
static int
get_request_avail_spec_list(
	devconfig_t *request,
	dlist_t	    **list)
{
	request_spec_list_t *entry = NULL;
	int error = 0;

	if ((entry = find_request_spec_list_entry(request)) == NULL) {

	    /* create cache entry for this request */
	    error = make_request_spec_list_entry(
		    request,
		    devconfig_get_available(request),
		    devconfig_get_unavailable(request),
		    &entry);

	    if ((error == 0) && (entry != NULL)) {
		if ((error = add_request_spec_list_entry(entry)) != 0) {
		    destroy_request_spec_list_entry(entry);
		    entry = NULL;
		}
	    }
	}

	if ((error == 0) && (entry != NULL)) {
	    *list = entry->avail_specs_list;
	}

	return (error);
}

/*
 * FUNCTION:	get_request_unavail_spec_list(devconfig_t *request,
 *			dlist_t **list)
 *
 * INPUT:	request	- a pointer to a devconfig_t
 *
 * OUTPUT:	list	- pointer to a list of device_spec_t corresponding
 *				to the devices specified as unavailable by the
 *				input request.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which locates or builds the list of device_spec_t
 *		for the unavailable devices specified in the input request.
 *
 *		Looks up the input request in the request_spec_list cache.
 *		If there is currently no entry in the cache for the request,
 *		an entry is built and added.
 *
 *		The entry's list of unavailable device_spec_t is returned.
 */
static int
get_request_unavail_spec_list(
	devconfig_t *request,
	dlist_t	    **list)
{
	request_spec_list_t *entry = NULL;
	int error = 0;

	if ((entry = find_request_spec_list_entry(request)) == NULL) {

	    /* create new entry for this request */
	    error = make_request_spec_list_entry(
		    request,
		    devconfig_get_available(request),
		    devconfig_get_unavailable(request),
		    &entry);

	    if ((error == 0) && (entry != NULL)) {
		if ((error = add_request_spec_list_entry(entry)) != 0) {
		    destroy_request_spec_list_entry(entry);
		    entry = NULL;
		}
	    }
	}

	if ((error == 0) && (entry != NULL)) {
	    *list = entry->unavail_specs_list;
	}

	return (error);
}

/*
 * FUNCTION:	get_default_avail_spec_list(defaults_t *defaults,
 *			char *dsname, dlist_t **list)
 *
 * INPUT:	defaults - a pointer to a defaults_t struct
 *		dsname	- the name of the diskset whose defaults should be used
 *
 * OUTPUT:	list	- pointer to a list of device_spec_t corresponding
 *				to the devices specified as available by the
 *				defaults for the named diskset, or the global
 *				defaults for all disksets.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which locates or builds the list of device_spec_t
 *		for the available devices for the named diskset.
 *
 *		Locates the defaults for the named diskset, if there are none,
 *		locates the global defaults for all disksets.
 *
 *		The defaults devconfig_t struct is then used to look up the
 *		the corresponding entry in the request_spec_list cache.
 *
 *		If there is currently no entry in the cache for the defaults,
 *		an entry is built and added.
 *
 *		The entry's list of available device_spec_t is returned.
 */
static int
get_default_avail_spec_list(
	defaults_t *alldefaults,
	char	*dsname,
	dlist_t	    **list)
{
	request_spec_list_t *entry = NULL;
	devconfig_t *defaults = NULL;
	int error = 0;

	/* Get diskset defaults, or global if none for diskset */
	error = defaults_get_diskset_by_name(
		alldefaults, dsname, &defaults);

	if (error != 0) {
	    if (error == ENOENT) {
		/* to get global defaults, pass a NULL diskset name */
		error = defaults_get_diskset_by_name(
			alldefaults, NULL, &defaults);
	    }

	    if (error != 0) {
		if (error != ENOENT) {
		    oprintf(OUTPUT_DEBUG,
			    gettext("get defaults for %s returned %d\n"),
			    dsname, error);
		} else {
		    error = 0;
		}
	    }
	}

	if ((entry = find_request_spec_list_entry(defaults)) == NULL) {

	    /* create new entry for these defaults */
	    error = make_request_spec_list_entry(
		    defaults,
		    devconfig_get_available(defaults),
		    devconfig_get_unavailable(defaults),
		    &entry);

	    if ((error == 0) && (entry != NULL)) {
		if ((error = add_request_spec_list_entry(entry)) != 0) {
		    destroy_request_spec_list_entry(entry);
		    entry = NULL;
		}
	    }
	}

	if ((error == 0) && (entry != NULL)) {
	    *list = entry->avail_specs_list;
	}

	return (error);
}

/*
 * FUNCTION:	get_default_unavail_spec_list(defaults_t *defaults,
 *			char *dsname, dlist_t **list)
 *
 * INPUT:	defaults - a pointer to a defaults_t struct
 *		dsname	- the name of the diskset whose defaults should be used
 *
 * OUTPUT:	list	- pointer to a list of device_spec_t corresponding
 *				to the devices specified as unavailable by the
 *				defaults for the named diskset, or the global
 *				defaults for all disksets.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which locates or builds the list of device_spec_t
 *		for the unavailable devices for the named diskset.
 *
 *		Locates the defaults for the named diskset, if there are none,
 *		locates the global defaults for all disksets.
 *
 *		The defaults devconfig_t struct is then used to look up the
 *		the corresponding entry in the request_spec_list cache.
 *
 *		If there is currently no entry in the cache for the defaults,
 *		an entry is built and added.
 *
 *		The entry's list of unavailable device_spec_t is returned.
 */
static int
get_default_unavail_spec_list(
	defaults_t *alldefaults,
	char	*dsname,
	dlist_t	    **list)
{
	request_spec_list_t *entry = NULL;
	devconfig_t *defaults = NULL;
	int error = 0;

	/* Get diskset defaults, or global if none for diskset */
	error = defaults_get_diskset_by_name(
		alldefaults, dsname, &defaults);

	if (error != 0) {

	    if (error == ENOENT) {
		/* to get global defaults, pass a NULL diskset name */
		error = defaults_get_diskset_by_name(
			alldefaults, NULL, &defaults);
	    }

	    if (error != 0) {
		if (error != ENOENT) {
		    oprintf(OUTPUT_DEBUG,
			    gettext("get defaults for %s returned %d\n"),
			    dsname, error);
		} else {
		    error = 0;
		}
	    }
	}

	if ((entry = find_request_spec_list_entry(defaults)) == NULL) {

	    /* create new entry for these defaults */
	    error = make_request_spec_list_entry(
		    defaults,
		    devconfig_get_available(defaults),
		    devconfig_get_unavailable(defaults),
		    &entry);

	    if ((error == 0) && (entry != NULL)) {
		if ((error = add_request_spec_list_entry(entry)) != 0) {
		    destroy_request_spec_list_entry(entry);
		    entry = NULL;
		}
	    }
	}

	if ((error == 0) && (entry != NULL)) {
	    *list = entry->unavail_specs_list;
	}

	return (error);
}

/*
 * FUNCTION:	is_named_device_avail(devconfig_t *request, char *device_name,
 *			boolean_t check_aliases, boolean_t *avail)
 *
 * INPUT:	request - the current request devconfig_t
 *		device_name - char * device name
 *		check_aliases - boolean_t which indicates whether the device's
 *			aliases should be considered by the availability checks.
 *
 * OUTPUT:	avail	- a boolean_t * to hold the result
 *
 * RETURNS:	int	- !0 on error
 *
 *		avail is set to B_TRUE if the named device is available for
 * 		the input request, B_FALSE otherwise.
 *
 * PURPOSE:	Determine if the named device can be used to satisfy the
 *		input request.
 *
 *		There are several levels at which device availabiity or
 *		unavailability may be specifed:
 *
 *		1. the volume subrequest,
 *		2. the toplevel (diskset) request,
 *		3. the diskset-specific defaults
 *		4. the global defaults
 *
 *		If the diskset-specific defaults exist, only they are checked.
 *
 *		The precedence ordering that is enforced:
 *
 *		1. if request has an avail list, the name must be in it
 * 			and not in the request's unavail list.
 *		2. if request has an unavail list, the name must not be in it.
 *		3. if toplevel request has an avail list, the name must be
 *			in it and not in the toplevel request's unavailable
 *			list.
 *		4. if toplevel request has an unavail list, the name must
 *			not be in it.
 *		5. if defaults have an avail list, the name must be in it
 *			and not in the defaults unavailable list.
 *		6. if defaults have an unavail list, the name must not be
 *			in it.
 */
static int
is_named_device_avail(
	devconfig_t	*request,
	char		*device_name,
	boolean_t	check_aliases,
	boolean_t	*avail)
{
	typedef enum check_types {
		DEVICE_REQUEST = 0,
		DISKSET_REQUEST,
		DEFAULTS,
		N_CHECKS
	} check_type_t;

	check_type_t	check_type;

	typedef enum list_types {
		AVAIL = 0,
		UNAVAIL,
		N_LISTS
	} list_type_t;

	dlist_t		*lists[N_CHECKS][N_LISTS];
	boolean_t	includes;
	int		error = 0;

	memset(lists, 0, (N_CHECKS * N_LISTS) * sizeof (dlist_t *));

	if (request != NULL) {
	    /* get avail/unavail specs for request */
	    ((error = get_request_avail_spec_list(
		    request, &lists[DEVICE_REQUEST][AVAIL])) != 0) ||
	    (error = get_request_unavail_spec_list(
		    request, &lists[DEVICE_REQUEST][UNAVAIL]));
	}

	if ((error == 0) && (_toplevel_request != NULL)) {
	    /* diskset request */
	    ((error = get_request_avail_spec_list(
		    _toplevel_request, &lists[DISKSET_REQUEST][AVAIL])) != 0) ||
	    (error = get_request_unavail_spec_list(
		    _toplevel_request, &lists[DISKSET_REQUEST][UNAVAIL]));
	}

	if ((error == 0) && (_defaults != NULL)) {
	    /* and diskset/global defaults */
	    ((error = get_default_avail_spec_list(_defaults,
		    get_request_diskset(), &lists[DEFAULTS][AVAIL])) != 0) ||
	    (error = get_default_unavail_spec_list(_defaults,
		    get_request_diskset(), &lists[DEFAULTS][UNAVAIL]));
	}

	if (error != 0) {
	    return (error);
	}

	*avail = B_TRUE;

	for (check_type = DEVICE_REQUEST;
	    (check_type < N_CHECKS) && (error == 0);
	    check_type++) {

	    if (lists[check_type][AVAIL] != NULL) {

		/* does avail spec list include named device? */
		if ((error = avail_list_includes_device_name(
		    lists[check_type][AVAIL], device_name, check_aliases,
		    &includes)) == 0) {

		    if (includes != B_TRUE) {
			*avail = B_FALSE;
		    }

		    if ((includes == B_TRUE) &&
			(lists[check_type][UNAVAIL] != NULL)) {

			/* device is available, is it in the unavail list? */
			if ((error = unavail_list_includes_device_name(
			    lists[check_type][UNAVAIL], device_name,
			    check_aliases, &includes)) == 0) {

			    if (includes == B_TRUE) {
				*avail = B_FALSE;
			    }
			}
		    }
		}

		/* lists at this level checked, skip remainder */
		break;

	    } else if (lists[check_type][UNAVAIL] != NULL) {

		/* does unavail spec list include named device? */
		if ((error = unavail_list_includes_device_name(
		    lists[check_type][UNAVAIL], device_name,
		    check_aliases, &includes)) == 0) {

		    if (includes == B_TRUE) {
			*avail = B_FALSE;
		    }
		}

		/* list at this level checked, skip remainder */
		break;
	    }
	}

	return (error);
}

/*
 * FUNCTION:	avail_list_includes_device_name(dlist_t *list,
 *			char *device_name, boolean_t check_aliases,
 *			boolean_t *includes)
 *
 * INPUT:	list	- a dlist_t list of available device_spec_t
 *		device_name  - a char * device CTD name
 *		check_aliases - boolean_t which indicates if the device's
 *			aliases	should be considered in the availability
 *			checking.
 *
 * OUTPUT:	includes - B_TRUE - if named device is "included" by any
 *				specification in the input list
 *			   B_FALSE - otherwise
 *
 * RETURNS:	int	- 0 on success
 *			- !0 otherwise
 *
 * PURPOSE:	Helper used by is_named_device_avail that determines
 *		if the input list of device specifications "includes"
 *		a specific device.
 *
 *		Iterates the elements of the input array and searches
 *		for a match using spec_includes_device_name().
 */
static int
avail_list_includes_device_name(
	dlist_t	*list,
	char	*device_name,
	boolean_t check_aliases,
	boolean_t *includes)
{
	dlist_t *iter = NULL;
	int	error = 0;

	*includes = B_FALSE;

	for (iter = list;
	    (*includes == B_FALSE) && (iter != NULL) && (error == 0);
	    iter = iter->next) {

	    device_spec_t *spec = (device_spec_t *)iter->obj;
	    error = spec_includes_device_name(spec, device_name,
		    check_aliases, includes);
	}

	return (0);
}

/*
 * FUNCTION:	unavail_list_includes_device_name(dlist_t *list,
 *			char *device_name, boolean_t check_aliases,
 *			boolean_t *includes)
 *
 * INPUT:	list	- a dlist_t list of unavailable device_spec_t
 *		device_name  - a char * device CTD name
 *		check_aliases - boolean_t which indicates if the device's
 *			aliases	should be considered in the availability
 *			checking.
 *
 * OUTPUT:	includes - B_TRUE - if named device is "included" by any
 *				specification in the input list
 *			   B_FALSE - otherwise
 *
 * RETURNS:	int	- 0 on success
 *			- !0 otherwise
 *
 * PURPOSE:	Helper used by is_named_device_avail that determines
 *		if the input list of device specifications "includes"
 *		a specific device.
 *
 *		Iterates the elements of the input array and searches
 *		for a match using spec_includes_device_name_or_alias().
 */
static int
unavail_list_includes_device_name(
	dlist_t	*list,
	char	*device_name,
	boolean_t check_aliases,
	boolean_t *includes)
{
	dlist_t *iter = NULL;
	int	error = 0;
	device_spec_t *unavail_spec;
	boolean_t	check_for_alternate_hba = B_FALSE;

	*includes = B_FALSE;

	/*
	 * the specs in the list are in descending order of specificity.
	 * so a more exact spec will rule the device out before a less
	 * exact spec.
	 *
	 * Meaning: if the list has { "c3t0d0", ..., "c3", ... } and the
	 * input device name is "c3t0d0s0", it will match "c3t0d0"
	 * before "c3".
	 *
	 * This is important for the multi-path alias checking below.
	 * If the input device name is ruled out by a non-controller
	 * specification, it is really unavailable.
	 */
	for (iter = list;
	    (*includes == B_FALSE) && (iter != NULL);
	    iter = iter->next) {

	    unavail_spec = (device_spec_t *)iter->obj;
	    error = spec_includes_device_name(
		    unavail_spec, device_name, check_aliases, includes);

	}

	if ((error == 0) && (*includes == B_TRUE)) {

	    /* matched an unavailable spec, was it a controller/HBA? */
	    oprintf(OUTPUT_DEBUG,
		    "device \"%s\" is unavailable, "
		    "it matched \"c(%d)t(%d)d(%d)s(%d)\"\n",
		    device_name,
		    unavail_spec->data.ctd->ctrl,
		    unavail_spec->data.ctd->target,
		    unavail_spec->data.ctd->lun,
		    unavail_spec->data.ctd->slice);

	    if ((unavail_spec->data.ctd->ctrl != ID_UNSPECIFIED) &&
		(unavail_spec->data.ctd->target == ID_UNSPECIFIED) &&
		(unavail_spec->data.ctd->lun == ID_UNSPECIFIED) &&
		(unavail_spec->data.ctd->slice == ID_UNSPECIFIED)) {

		/*
		 * Need to see if the named device is a disk or slice,
		 * and if so check to see if the it is multipathed
		 * and possibly accessible thru another controller/HBA.
		 */
		check_for_alternate_hba = B_TRUE;
	    }
	}

	if ((error == 0) && (check_for_alternate_hba == B_TRUE)) {

	    dm_descriptor_t slice = (dm_descriptor_t)0;
	    dm_descriptor_t disk = (dm_descriptor_t)0;

	    ((error = slice_get_by_name(device_name, &slice)) != 0) ||
	    (error = disk_get_by_name(device_name, &disk));
	    if (error != 0) {
		return (error);
	    }

	    /* if it is a slice, get its disk */
	    if ((error == 0) && (slice != (dm_descriptor_t)0)) {
		error = slice_get_disk(slice, &disk);
	    }

	    if ((error == 0) && (disk != (dm_descriptor_t)0)) {

		/* see if all the disk's HBAs are unavailable */
		dlist_t *hbas = NULL;
		dlist_t *iter = NULL;

		error = disk_get_hbas(disk, &hbas);

		if (hbas != NULL) {
		    oprintf(OUTPUT_DEBUG,
			    gettext("    checking alternate paths for %s\n"),
			    device_name);
		} else {
		    oprintf(OUTPUT_DEBUG,
			    gettext("    no alternate paths for %s\n"),
			    device_name);
		}

		/* for each of the disk's HBAs */
		for (iter = hbas;
		    (iter != NULL) && (*includes == B_TRUE) && (error == 0);
		    iter = iter->next) {

		    dm_descriptor_t hba = (uintptr_t)iter->obj;
		    device_spec_t *hbaspec;
		    char *hbaname = NULL;
		    dlist_t *iter2 = NULL;

		    *includes = B_FALSE;

		    ((error = get_display_name(hba, &hbaname)) != 0) ||
		    (error = get_spec_for_name(hbaname, &hbaspec));

		    /* is HBA unavailable? */
		    for (iter2 = list;
			(iter2 != NULL) && (error == 0) &&
				(*includes == B_FALSE);
			iter2 = iter2->next) {

			device_spec_t *spec =
			    (device_spec_t *)iter2->obj;

			*includes = spec_includes_device(spec, hbaspec);
		    }
		}
		dlist_free_items(hbas, NULL);

		/* if *includes==B_TRUE here, all HBAs are unavailable */
	    }
	}

	return (error);
}

/*
 * FUNCTION:	spec_includes_device_name(device_spec_t *spec,
 *			char *device_name, boolean_t check_aliases,
 *			boolean_t *includes)
 *
 * INPUT:	spec	- a device_spec_t CTD specification.
 *		device_name  - a char * device CTD name
 *		check_aliases - boolean_t which indicates if the device's
 *			aliases	should be considered in the checking.
 *
 * OUTPUT:	includes - B_TRUE - if device is "included" by the input
 *				specification
 *			    B_FALSE - otherwise
 *
 * RETURNS:	int	- 0 on success
 *			- !0 otherwise
 *
 * PURPOSE:	Helper used by (un)avail_specs_includes_device_name() that
 *		determines if the input device specification "includes"
 *		the named device.
 *
 *		If check_aliases is true and the named device is a slice or
 *		a disk drive, its multi-pathed aliases are also checked
 *		against the spec.
 */
static int
spec_includes_device_name(
	device_spec_t *spec,
	char		 *device_name,
	boolean_t	check_aliases,
	boolean_t	*includes)
{
	device_spec_t *device_spec;
	int error = 0;

	error = get_spec_for_name(device_name, &device_spec);
	if (error == 0) {

	    *includes = spec_includes_device(spec, device_spec);

	    if ((*includes == B_FALSE) && (check_aliases == B_TRUE)) {

		/* spec doesn't include name, check aliases */

		dm_descriptor_t device = (dm_descriptor_t)0;
		dlist_t *aliases = NULL;

		/* only slices and disks have aliases */
		error = slice_get_by_name(device_name, &device);
		if (device != (dm_descriptor_t)0) {
		    error = get_aliases(device, &aliases);
		} else if (error == 0) {
		    error = disk_get_by_name(device_name, &device);
		    if (device != (dm_descriptor_t)0) {
			error = get_aliases(device, &aliases);
		    }
		}

		if ((error == 0) && (aliases != NULL)) {

		    dlist_t *iter;
		    for (iter = aliases;
			(iter != NULL) && (*includes == B_FALSE) &&
				(error == 0);
			iter = iter->next) {

			char *alias = (char *)iter->obj;
			device_spec_t *alias_spec;

			error = get_spec_for_name(alias, &alias_spec);
			if (error == 0) {
			    /* does spec include alias? */
			    *includes =	spec_includes_device(spec, alias_spec);
			}
		    }
		}
		dlist_free_items(aliases, free);
	    }
	}

	return (error);
}

/*
 * FUNCTION:	destroy_device_spec(device_spec_t *spec)
 *
 * INPUT:	spec	- pointer to a device_spec_t
 *
 * RETURNS:	nothing
 *
 * PURPOSE:	Function which reclaims memory allocated to a device_spec_t.
 *
 *		Frees memory allocated to hold the specific data in the spec.
 */
static void
destroy_device_spec(
	device_spec_t *spec)
{
	if (spec != NULL) {
	    if (spec->type == SPEC_TYPE_CTD) {
		free(spec->data.ctd);
	    } else if (spec->type == SPEC_TYPE_RAW) {
		free(spec->data.raw);
	    }
	    free(spec);
	}
}

/*
 * FUNCTION:	create_device_spec(char *name, device_spec_t **spec);
 *
 * INPUT:	name	- pointer to a char* device name
 *
 * OUTPUT:	spec	- pointer to a device_spec_t to hold the result
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise
 *
 * PURPOSE:	Function which creates a device_spec_t for the input
 *		device name.
 *
 */
static int
create_device_spec(
	char	*name,
	device_spec_t **spec)
{
	int error = 0;

	/* allocate the device spec and try various parsing schemes */
	*spec = (device_spec_t *)calloc(1, sizeof (device_spec_t));
	if (*spec == NULL) {
	    error = ENOMEM;
	} else {
	    if (((error = create_device_ctd_spec(name, spec)) != 0) &&
		    (error != ENOMEM)) {
		/* CTD failed, try other parsing schemes */
		error = create_device_raw_spec(name, spec);
	    }
	}

	return (error);
}

/*
 * FUNCTION:	create_device_ctd_spec(char *name, device_spec_t **spec);
 *
 * INPUT:	name	- pointer to a char* device name
 *
 * OUTPUT:	spec	- pointer to a device_spec_t updated with the parsed
 *				CTD spec, if successful
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise
 *
 * PURPOSE:	Function which atttempts to parse the input device name into
 *		cXtXdXsX component ids. The ids are the integer values of each
 *		specified segment of the input name.
 *
 *		If the name doesn't contain a segment, the id is set to
 *		ID_UNSPECIFIED.
 *
 *		The input name must be well-formed.
 *
 *		These are the acceptable forms:
 *
 *		cXtXdXsX
 *		cXtXdX
 *		cXtX
 *		cXdXsX
 *		cXdX
 *		cX
 */
static int
create_device_ctd_spec(
	char	*name,
	device_spec_t **spec)
{
	uint_t	ctrl;
	uint_t	target;
	uint_t	lun;
	uint_t	slice;

	uint_t	nscan;
	uint_t	nchars;

	char	*device_str;
	char	*target_str;
	char	*ctd_str;
	char	*t_ptr;
	char	*d_ptr;
	char	*s_ptr;

	boolean_t is_ide = B_FALSE;
	boolean_t got_slice = B_FALSE;
	boolean_t got_lun = B_FALSE;
	boolean_t got_target = B_FALSE;
	boolean_t got_ctrl = B_FALSE;

	int 	error = 0;

	ctd_str = strdup(name);
	if (ctd_str == NULL) {
	    return (ENOMEM);
	}

	/* trim any leading path (/dev/dsk/cXtXdXsX) */
	if ((device_str = strrchr(ctd_str, '/')) != NULL) {
	    ++device_str;
	} else {
	    device_str = ctd_str;
	}

	/* find each segment start position */
	t_ptr = strrchr(device_str, 't');
	d_ptr = strrchr(device_str, 'd');
	s_ptr = strrchr(device_str, 's');

	/*
	 * scan ids from each existing segment working backwards
	 * so as to leave the device_str in the correct state
	 * for the next expected segment
	 */
	if (s_ptr != NULL) {

	    /* found 's', try to get slice */
	    nchars = strlen(s_ptr);
	    if ((sscanf(s_ptr, "s%u%n", &slice, &nscan) != 1) ||
		(nscan != nchars)) {

		error = -1;
		oprintf(OUTPUT_DEBUG,
			gettext("no slice component in device "
				"name \"%s\".\n"),
			name);

	    } else {
		got_slice = B_TRUE;
		*s_ptr = '\0';
	    }
	}

	if ((error == 0) && (d_ptr != NULL)) {

	    /* found 'd', try to get disk/lun */
	    nchars = strlen(d_ptr);
	    if ((sscanf(d_ptr, "d%u%n", &lun, &nscan) != 1) ||
		(nscan != nchars)) {

		error = -1;
		oprintf(OUTPUT_DEBUG,
			gettext("no disk/lun component "
				"in device name \"%s\".\n"),
			name);

	    } else {
		got_lun = B_TRUE;
		*d_ptr = '\0';
	    }
	}

	if ((error == 0) && (t_ptr != NULL)) {

	    /* found 't', try to get target, it may be a hex WWN id */

	    /* skip leading 't' and add two for the 'OX' */
	    nchars = strlen(t_ptr + 1) + 2;
	    if ((target_str = (char *)malloc(nchars+1)) == NULL) {

		error = ENOMEM;

	    } else {

		strcpy(target_str, "0X");
		strcpy(target_str+2, t_ptr + 1);
		target_str[nchars] = '\0';

		if ((sscanf(target_str, "%x%n", &target, &nscan) != 1) ||
		    (nscan != nchars)) {

		    error = -1;
		    oprintf(OUTPUT_DEBUG,
			    gettext("no target/WWN component "
				    "in device name \"%s\".\n"),
			    name);

		} else {
		    got_target = B_TRUE;
		    *t_ptr = '\0';
		}

		free(target_str);
	    }

	} else {
	    is_ide = B_TRUE;
	}

	if ((error == 0) && (device_str != NULL)) {

	    /* get controller/hba/channel */
	    nchars = strlen(device_str);
	    if ((sscanf(device_str, "c%u%n", &ctrl, &nscan) != 1) ||
		    (nscan != nchars)) {

		error = -1;
		oprintf(OUTPUT_DEBUG,
			gettext("no channel/HBA component "
				"in device name \"%s\".\n"),
			name);

	    } else {
		got_ctrl = B_TRUE;
	    }
	}

	free(ctd_str);

	if (error == 0) {

	    /* allocate the ctd_spec_t struct and store the ids */
	    (*spec)->type = SPEC_TYPE_CTD;
	    (*spec)->data.ctd = (ctd_spec_t *)calloc(1, sizeof (ctd_spec_t));

	    if ((*spec)->data.ctd == NULL) {
		error = ENOMEM;
	    }

	    (*spec)->data.ctd->slice = ID_UNSPECIFIED;
	    (*spec)->data.ctd->lun = ID_UNSPECIFIED;
	    (*spec)->data.ctd->target = ID_UNSPECIFIED;
	    (*spec)->data.ctd->ctrl = ID_UNSPECIFIED;

	    if (got_slice == B_TRUE) {
		(*spec)->data.ctd->slice = slice;
	    }

	    if (got_lun == B_TRUE) {
		(*spec)->data.ctd->lun = lun;
	    }

	    if (got_target == B_TRUE) {
		(*spec)->data.ctd->target = target;
	    }

	    if (got_ctrl == B_TRUE) {
		(*spec)->data.ctd->ctrl = ctrl;
	    }

	    (*spec)->data.ctd->is_ide = is_ide;
	}

	return (error);
}

/*
 * FUNCTION:	create_device_raw_spec(char *name, device_spec_t **spec);
 *
 * INPUT:	name	- pointer to a char* device name
 *
 * OUTPUT:	spec	- pointer to a device_spec_t updated with the raw spec
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise
 *
 * PURPOSE:	Function which creates a "raw" spec for the input name.
 *
 *		This is a last resort if all other spec parsing schemes failed,
 *		the "raw" spec is just the input device name.
 */
static int
create_device_raw_spec(
	char	*name,
	device_spec_t **spec)
{
	int 	error = 0;
	char	*ctd_str = strdup(name);

	if (ctd_str == NULL) {
	    return (ENOMEM);
	}

	(*spec)->type = SPEC_TYPE_RAW;
	(*spec)->data.raw = ctd_str;

	oprintf(OUTPUT_DEBUG,
		gettext("made raw device spec for \"%s\"\n"), ctd_str);

	return (error);
}

/*
 * FUNCTION:	get_spec_for_name(char *name, device_spec_t **id);
 *
 * INPUT:	name	- pointer to a char* device name
 *
 * OUTPUT:	id	- pointer to a device_spec_t to hold the result
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise
 *
 * PURPOSE:	Function which finds the device_spec_t that already
 *		exists for the input name or creates it.
 *
 *		The returned struct should not be freed, it is maintained
 *		in a cache that will be purged when the layout process
 *		is complete.
 */
int
get_spec_for_name(
	char	*name,
	device_spec_t **id)
{
	dlist_t *item;
	int	error = 0;

	item = dlist_find(_spec_cache, (void *)name,
		compare_name_to_spec_cache_name);

	if (item == NULL) {
	    if ((error = create_device_spec(name, id)) == 0) {

		spec_cache_t *entry = (spec_cache_t *)
		    calloc(1, sizeof (spec_cache_t));

		if (entry == NULL) {
		    destroy_device_spec(*id);
		    error = ENOMEM;
		} else {
		    char *dup = strdup(name);
		    if (dup == NULL) {
			free(entry);
			destroy_device_spec(*id);
			*id = NULL;
			error = ENOMEM;
		    } else {
			entry->name = dup;
			entry->device_spec = *id;
		    }

		    if (error == 0) {
			dlist_t *item = dlist_new_item((void *)entry);
			if (item == NULL) {
			    free(entry);
			    destroy_device_spec(*id);
			    *id = NULL;
			    error = ENOMEM;
			} else {
			    _spec_cache =
				dlist_append(item, _spec_cache, AT_HEAD);
			}
		    }
		}
	    }
	} else {
	    *id = ((spec_cache_t *)item->obj)->device_spec;
	}

	return (error);
}

/*
 * FUNCTION:	spec_includes_device(device_spec_t *spec,
 *			device_spec_t *device)
 *
 * INPUT:	spec	- pointer to a device_spec struct
 *		device	- pointer to a device_spec struct
 *
 * RETURNS:	boolean_t - B_TRUE if the device is included in the spec
 *			 B_FALSE otherwise
 *
 * PURPOSE:	Function which determines if the input device matches the
 *		input spec.
 *
 *		If both specs are of the same type, the appropriate
 *		comparison function is called.
 *
 *		If the two specs are of different types, no comparison
 *		is done and B_FALSE is returned.
 */
boolean_t
spec_includes_device(
	device_spec_t *spec,
	device_spec_t *device)
{
	if ((spec->type == SPEC_TYPE_CTD) && (device->type == SPEC_TYPE_CTD)) {
	    return (ctd_spec_includes_device(spec, device));
	} else if ((spec->type == SPEC_TYPE_RAW) &&
	    (device->type == SPEC_TYPE_RAW)) {
	    return (raw_spec_includes_device(spec, device));
	}

	return (B_FALSE);
}

/*
 * FUNCTION:	ctd_spec_includes_device(device_spec_t *spec,
 *			device_spec_t *device)
 *
 * INPUT:	spec	- pointer to a device_spec struct
 *		device	- pointer to a device_spec struct
 *
 * RETURNS:	boolean_t - B_TRUE if the device is included in the spec
 *			 B_FALSE otherwise
 *
 * PURPOSE:	Function which determines if the input CTD device spec
 *		matches the input CTD spec.
 *
 *		The device_spec_t structs contain component "ids" for
 *		both the specification and the device.
 *
 *		The device must match each of the ids in the spec that
 *		are specified.
 *
 *		spec		devices matched
 *		--------------------------------------------------------
 *		cX		cX, cXtX, cXtXdX, cXtXdXsX, cXdX, cXdXsX
 *		cXtX		cXtX, cXtXdX, cXtXdXsX
 *		cXtXdX		cXtXdX, cXtXdXsX
 *		cXtXdXsX	cXtXdXsX
 *		cXdX		cXdX, cXdXsX
 *		cXdXsX		cXdXsX
 */
static boolean_t
ctd_spec_includes_device(
	device_spec_t *spec,
	device_spec_t *device)
{
	boolean_t match = B_FALSE;

	if (spec->data.ctd->is_ide) {

	    /* valid IDE names are cX, cXdX, cXdXsX, no target */

	    if ((spec->data.ctd->ctrl != ID_UNSPECIFIED) &&
		(spec->data.ctd->lun != ID_UNSPECIFIED) &&
		(spec->data.ctd->slice != ID_UNSPECIFIED)) {

		match = (spec->data.ctd->ctrl == device->data.ctd->ctrl) &&
		    (spec->data.ctd->lun == device->data.ctd->lun) &&
		    (spec->data.ctd->slice == device->data.ctd->slice);

	    } else if ((spec->data.ctd->ctrl != ID_UNSPECIFIED) &&
		(spec->data.ctd->lun != ID_UNSPECIFIED)) {

		match = (spec->data.ctd->ctrl == device->data.ctd->ctrl) &&
		    (spec->data.ctd->lun == device->data.ctd->lun);

	    } else if (spec->data.ctd->ctrl != ID_UNSPECIFIED) {

		match = (spec->data.ctd->ctrl == device->data.ctd->ctrl);

	    }

	} else {

	    /* valid names are cX, cXtX, cXtXdX, cXtXdXsX */

	    if ((spec->data.ctd->ctrl != ID_UNSPECIFIED) &&
		(spec->data.ctd->target != ID_UNSPECIFIED) &&
		(spec->data.ctd->lun != ID_UNSPECIFIED) &&
		(spec->data.ctd->slice != ID_UNSPECIFIED)) {

		match = (spec->data.ctd->ctrl == device->data.ctd->ctrl) &&
		    (spec->data.ctd->target == device->data.ctd->target) &&
		    (spec->data.ctd->lun == device->data.ctd->lun) &&
		    (spec->data.ctd->slice == device->data.ctd->slice);

	    } else if ((spec->data.ctd->ctrl != ID_UNSPECIFIED) &&
		(spec->data.ctd->target != ID_UNSPECIFIED) &&
		(spec->data.ctd->lun != ID_UNSPECIFIED)) {

		match = (spec->data.ctd->ctrl == device->data.ctd->ctrl) &&
		    (spec->data.ctd->target == device->data.ctd->target) &&
		    (spec->data.ctd->lun == device->data.ctd->lun);

	    } else if ((spec->data.ctd->ctrl != ID_UNSPECIFIED) &&
		(spec->data.ctd->target != ID_UNSPECIFIED)) {

		match = (spec->data.ctd->ctrl == device->data.ctd->ctrl) &&
		    (spec->data.ctd->target == device->data.ctd->target);

	    } else if (spec->data.ctd->ctrl != ID_UNSPECIFIED) {

		match = (spec->data.ctd->ctrl == device->data.ctd->ctrl);

	    }
	}

	oprintf(OUTPUT_DEBUG,
		gettext("spec: c(%d) t(%d) d(%d) s(%d) "
			"%s: c(%d) t(%d) d(%d) s(%d)\n"),
		spec->data.ctd->ctrl, spec->data.ctd->target,
		spec->data.ctd->lun, spec->data.ctd->slice,
		(match ? gettext("includes") : gettext("does not include")),
		device->data.ctd->ctrl, device->data.ctd->target,
		device->data.ctd->lun, device->data.ctd->slice);

	return (match);
}

/*
 * FUNCTION:	raw_spec_includes_device(device_spec_t *spec,
 *			device_spec_t *device)
 *
 * INPUT:	spec	- pointer to a device_spec struct
 *		device	- pointer to a device_spec struct
 *
 * RETURNS:	boolean_t - B_TRUE if the device is included in the spec
 *			 B_FALSE otherwise
 *
 * PURPOSE:	Function which determines if the input raw device spec
 *		matches the input spec.
 *
 *		The device_spec_t raw elements are checked.
 *
 *		If the spec's raw device name is exactly contained at the
 *		beginning of the device spec's raw name, then the function
 *		evaluates to true.
 */
static boolean_t
raw_spec_includes_device(
	device_spec_t *spec,
	device_spec_t *device)
{
	return (strncasecmp(spec->data.raw,
			device->data.raw, strlen(spec->data.raw)) == 0);
}

/*
 * FUNCTION:	compare_name_to_spec_cache_name(void *name, void *list_item)
 *
 * INPUT:	name	- opaque pointer to a char * device name
 * 		list_item - opaque pointer to a spec_cache_t entry
 *
 * RETURNS:	int	- 0 - if request is the same as list_item->request
 *			  !0 - otherwise
 *
 * PURPOSE:	dlist_t helper which compares the input device name
 *		to the list_item's device name for equality.
 *
 *		This function is the lookup mechanism for the device_spec
 *		associated with the name.
 */
static int
compare_name_to_spec_cache_name(
	void *name,
	void *list_item)
{
	spec_cache_t *entry = (spec_cache_t *)list_item;

	assert(name != NULL);
	assert(entry != NULL);

	return (string_case_compare((char *)name, entry->name));
}

/*
 * FUNCTION:	destroy_spec_cache_entry(void *entry)
 *
 * INPUT:	entry	- opaque pointer to a spec_cache_t
 *
 * RETURNS:	nothing
 *
 * PURPOSE:	Function which reclaims memory allocated to a
 *		spec_cache_t entry.
 *
 *		Frees memory allocated to hold the CTD name and the
 *		corresponding device_spec_t.
 */
static void
destroy_spec_cache_entry(
	void *obj)
{
	spec_cache_t *entry = (spec_cache_t *)obj;

	if (entry != NULL) {
	    free(entry->name);
	    destroy_device_spec(entry->device_spec);
	    free(entry);
	}
}

/*
 * FUNCTION:	destroy_spec_cache()
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Function which destroys all entries in the device_spec
 *		cache.
 */
static int
destroy_spec_cache()
{
	dlist_free_items(_spec_cache, destroy_spec_cache_entry);
	_spec_cache = NULL;

	return (0);
}

/*
 * FUNCTION:	get_device_access_name(devconfig_t *request,
 *			dm_descriptor_t desc, char **name)
 *
 * INPUT:	request	- a devconfig_t request
 *		desc	- a dm_descriptor_t device handle
 *
 * OUTPUT:	name	- a char * pointer to hold the preferred name
 *
 * RETURNS:	int	- 0 - if request is the same as list_item->request
 *			  !0 - otherwise
 *
 * PURPOSE:	Utility function to determine which of the possible device
 *		names should be used to access a known available device.
 *
 *		Devices handled are slices and disks.
 *
 *		If the input device is a multipathed disk or slice, it
 *		can have several possible names.  Determine which of the
 *		names should be used based on the input request's available
 *		or unavailable device specifications.
 *
 */
int
get_device_access_name(
	devconfig_t	*request,
	dm_descriptor_t desc,
	char		**name)
{
	int		error = 0;
	boolean_t	avail = B_FALSE;
	dlist_t		*aliases = NULL;

	assert(desc != (dm_descriptor_t)0);

	*name = NULL;

	if ((error = get_display_name(desc, name)) != 0) {
	    return (error);
	}

	if (is_did_name(*name) == B_TRUE) {
	    oprintf(OUTPUT_DEBUG,
		    gettext("device DID name %s is preferred\n"),
		    *name);
	    return (0);
	}

	error = is_named_device_avail(request, *name, B_FALSE, &avail);
	if (error != 0) {
	    return (error);
	}

	if (avail == B_TRUE) {
	    oprintf(OUTPUT_DEBUG,
		    gettext("device name %s is accessible\n"),
		    *name);
	    return (0);
	}

	/* search aliases for an 'available' name, prefer DID names */
	if ((error = get_aliases(desc, &aliases)) == 0) {

	    dlist_t *iter = aliases;
	    char *availname = NULL;
	    char *didname = NULL;

	    for (; (iter != NULL) && (error == 0); iter = iter->next) {

		char *alias = (char *)iter->obj;
		error = is_named_device_avail(request, alias, B_FALSE, &avail);

		if ((error == 0) && (avail == B_TRUE)) {
		    oprintf(OUTPUT_DEBUG,
			    gettext("device alias %s is accessible for %s\n"),
			    alias, *name);

		    availname = alias;

		    if (is_did_name(availname) == B_TRUE) {
			didname = alias;
			break;
		    }
		}
	    }

	    if (error == 0) {
		if (didname != NULL) {
		    *name = didname;
		} else if (availname != NULL) {
		    *name = availname;
		}
	    }
	}

	return (error);
}