metassist/layout/layout_hsp.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 <string.h>

#include <libintl.h>

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

#include "layout_device_cache.h"
#include "layout_device_util.h"
#include "layout_discovery.h"
#include "layout_dlist_util.h"
#include "layout_messages.h"
#include "layout_request.h"
#include "layout_slice.h"
#include "layout_svm_util.h"

#define	_LAYOUT_HSP_C

static int layout_explicit_hsp(
	devconfig_t 	*hsprequest,
	dlist_t		*devices,
	devconfig_t 	**hsp);

static int layout_default_hsp(
	devconfig_t 	*request,
	dlist_t		*devices,
	devconfig_t 	**hsp);

static int populate_hsp(
	devconfig_t	*request,
	devconfig_t	*hsp,
	dlist_t		*devices);

static int assemble_hsp(
	devconfig_t 	*hsp,
	dlist_t		*newspares,
	dlist_t		*devices);

static int get_uniquely_sized_slices(
	dlist_t 	*devices,
	dlist_t 	**unique);

static int remove_undersized_slices(
	dlist_t 	*unique,
	dlist_t 	**avail);

static int find_spare_for_component(
	devconfig_t 	*component,
	dlist_t		*all_spares,
	dlist_t		*hbas,
	dlist_t		*disks,
	boolean_t 	*found);

static int choose_spare_for_component(
	devconfig_t 	*comp,
	dlist_t 	**all_spares,
	dlist_t 	**new_spares,
	dlist_t 	**avail,
	dlist_t 	*used_hbas,
	dlist_t 	*used_disks,
	uint16_t	npaths);

/*
 * FUNCTION:	layout_hsp(devconfig_t *request, devconfig_t hsprequest,
 *			dlist_t *devices, dlist_t **results)
 *
 * INPUT:	request	- pointer to the toplevel request devconfig_t
 *		hsp	- pointer to the optional HSP request devconfig_t
 *		devices - pointer to a list of devices to be served by the HSP
 *
 * OUTPUT:	results - pointer to a list result devconfig_t, if the HSP
 *			to service the input list of devices needs to be
 *			created or modified, it will be appended to the list.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Main layout driver for HSP, attempts to build/populate a
 *		single HSP to service the list of devices.
 *
 *		If the input hsprequest is NULL, use the default HSP scheme:
 *		a. use the first HSP in the diskset
 *		b. create an HSP if the diskset has none
 *
 *		If the hsprequest is not NULL:
 *		a. if the request names an HSP and it already exists, use it
 *		b. if the request names an HSP and it does not exist, create it
 *		c. if the request specifies components, use them
 */
int
layout_hsp(
	devconfig_t	*request,
	devconfig_t	*hsprequest,
	dlist_t		*devices,
	dlist_t		**results)
{
	int		error = 0;
	devconfig_t  	*hsp = NULL;

	oprintf(OUTPUT_TERSE,
		gettext("  ->Layout a %s\n"),
		devconfig_type_to_str(TYPE_HSP));

	if (hsprequest == NULL) {
	    error = layout_default_hsp(request, devices, &hsp);
	} else {
	    error = layout_explicit_hsp(hsprequest, devices, &hsp);
	}

	if (error != 0) {
	    print_debug_failure_msg(devconfig_type_to_str(TYPE_HSP),
		    get_error_string(error));
	} else if (hsp != NULL) {

	    if (devconfig_get_components(hsp) == NULL) {
		/* HSP is usable as it is */
		free_devconfig(hsp);
		hsp = NULL;
	    } else {
		dlist_t *item = NULL;
		if ((item = dlist_new_item(hsp)) == NULL) {
		    error = ENOMEM;
		} else {
		    *results = dlist_append(item, *results, AT_TAIL);
		    print_layout_success_msg();
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	layout_default_hsp(devconfig_t *request,
 *			dlist_t *devices, devconfig_t **hsp)
 *
 * INPUT:	request	- pointer to the toplevel request devconfig_t
 *		devices - pointer to a list of devices to be served by the HSP
 *
 * OUTPUT:	hsp	- pointer to a devconfig_t to hold the resulting HSP
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Layout driver for default HSP construction.
 *
 *		a. use the first HSP in the diskset
 *		b. create an HSP if the diskset has none
 *		c. add spares to the HSP to service the list of input devices.
 */
static int
layout_default_hsp(
	devconfig_t 	*request,
	dlist_t		*devices,
	devconfig_t 	**hsp)
{
	char		*dsname = get_request_diskset();
	char		*hspname = NULL;
	boolean_t	free_hspname = B_FALSE;
	devconfig_t	*default_hsp = NULL;
	int		error = 0;

	oprintf(OUTPUT_TERSE,
		gettext("  -->Using default HSP scheme...\n"));

	if ((error = get_default_hsp_name(request, &hspname)) != 0) {
	    volume_set_error(
		    gettext("error getting HSP name from defaults\n"));
	    return (error);
	}

	if (hspname != NULL) {
	    if ((error = hsp_get_by_name(dsname, hspname, &default_hsp)) != 0) {
		volume_set_error(
			gettext("error getting default HSP by name\n"));
		return (error);
	    }
	} else {
	    /* no default HSP name, get diskset's default HSP */
	    if ((error = hsp_get_default_for_diskset(dsname,
		&default_hsp)) != 0) {
		volume_set_error(
			gettext("error getting default HSP\n"));
		return (error);
	    }

	    if (default_hsp == NULL) {
		/* no default HSP name, no default HSP, make one */
		if ((error = get_next_hsp_name(&hspname)) != 0) {
		    volume_set_error(
			    gettext("error making default HSP name\n"));
		    return (error);
		}
		free_hspname = B_TRUE;
	    }
	}

	if (default_hsp != NULL) {

	    /* Found existing default HSP, copy it */
	    dlist_t *spares = devconfig_get_components(default_hsp);

	    ((error = devconfig_get_name(default_hsp, &hspname)) != 0) ||
	    (error = new_devconfig(hsp, TYPE_HSP)) ||
	    (error = devconfig_set_name(*hsp, hspname));

	    if (error == 0) {
		devconfig_set_components(*hsp, spares);
		devconfig_set_components(default_hsp, NULL);

		oprintf(OUTPUT_TERSE,
			gettext("  --->Using %s from disk set %s...\n"),
			hspname, dsname);
	    } else {
		free_devconfig(*hsp);
		*hsp = NULL;
	    }

	} else {

	    /* no existing default HSP, make it */
	    ((error = new_devconfig(hsp, TYPE_HSP)) != 0) ||
	    (error = devconfig_set_name(*hsp, hspname));
	    if (error == 0) {
		oprintf(OUTPUT_VERBOSE,
			gettext("  --->Created %s for disk set %s...\n "),
			hspname, dsname);
	    } else {
		free_devconfig(*hsp);
		*hsp = NULL;
	    }

	    if (free_hspname == B_TRUE) {
		free(hspname);
	    }
	}

	if (error == 0) {
	    error = populate_hsp(request, *hsp, devices);
	}

	return (error);
}

/*
 * FUNCTION:	layout_explicit_hsp(devconfig_t *hsprequest,
 *			dlist_t *devices, devconfig_t **hsp)
 *
 * INPUT:	hsprequest - pointer to the explicit HSP request devconfig_t
 *		devices - pointer to a list of devices to be served by the HSP
 *
 * OUTPUT:	hsp	- pointer to a HSP devconfig_t to hold resulting HSP
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Layout driver for an explicit HSP request.
 *
 *		a. if the request names an HSP and it already exists, use it
 *		b. if the request names an HSP and it does not exist, create it
 *		c. if the request specifies components, use them
 *		   otherwise, add new spares to handle the input list
 *		   of devices.
 */
static int
layout_explicit_hsp(
	devconfig_t	*hsprequest,
	dlist_t		*devices,
	devconfig_t 	**hsp)
{
	char		*dsname = get_request_diskset();
	char		*hspname = NULL;
	dlist_t		*rspares = NULL;
	int		error = 0;

	oprintf(OUTPUT_VERBOSE,
		gettext("  --->Explicit HSP request...\n"));

	(void) devconfig_get_name(hsprequest, &hspname);
	if (hspname != NULL) {

	    (void) hsp_get_by_name(dsname, hspname, hsp);
	    if (*hsp != NULL) {

		oprintf(OUTPUT_VERBOSE,
			gettext("  --->Using %s...\n"),
			hspname);
	    } else {

		/* named HSP doesn't exist, create it */
		((error = new_devconfig(hsp, TYPE_HSP)) != 0) ||
		(error = devconfig_set_name(*hsp, hspname));
		if (error == 0) {
		    oprintf(OUTPUT_VERBOSE,
			    gettext("  --->%s does not exist, "
				    "created...\n"), hspname);
		} else {
		    free_devconfig(*hsp);
		    *hsp = NULL;
		}
		free(hspname);
	    }
	}

	if (error == 0) {

	    /* does the hsprequest specify spares? */
	    rspares = devconfig_get_components(hsprequest);
	    if (rspares != NULL) {

		/* put requested spares into HSP */
		dlist_t	*list = NULL;
		dlist_t *iter = NULL;

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

		    dlist_t *item = NULL;
		    if ((dlist_new_item(iter->obj)) == NULL) {
			error = ENOMEM;
		    } else {
			list = dlist_append(item, list, AT_TAIL);
		    }
		}

		if (error == 0) {
		    error = assemble_hsp(*hsp, rspares, devices);
		}

	    } else {

		/* select new spares */
		error = populate_hsp(hsprequest, *hsp, devices);
	    }
	}

	return (error);
}

/*
 * FUNCTION:	populate_hsp(devconfig_t *request, devconfig_t *hsp,
 *			dlist_t *devices)
 *
 * INPUT:	request	- pointer to a request devconfig_t
 *		hsp	- pointer to a HSP devconfig_t
 *		devices - pointer to a list of devices to be served by the HSP
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Processes the input HSP request and add spares sufficient
 *		to service the input list of devices.
 *
 *		Determine the available HBAs, disks, and slices.
 *		Sort thru the input list of devices and determine
 *		    the unique component sizes which need to be spared.
 *		Filter the available slices and remove those that are
 *		    too small to serve as spares.
 *
 *		Iterate each device and its components and see if the
 *		    HSP currently has a sufficient spare, if not, try
 *		    to select one from the available slices.
 *
 *		If a spare cannot be found for any device component,
 *		    the HSP layout process stops.
 *
 *              If spares are found for all device components, add
 *		    any required new ones to the HSP.
 */
static int
populate_hsp(
	devconfig_t	*request,
	devconfig_t	*hsp,
	dlist_t		*devices)
{
	int		error = 0;
	uint16_t	npaths	= 0;

	dlist_t		*usable_hbas = NULL;
	dlist_t		*sel_hbas = NULL;
	dlist_t		*disks = NULL;
	dlist_t		*iter = NULL;

	dlist_t		*avail = NULL;	/* available slices */
	dlist_t		*slices = NULL;	/* avail slices of sufficient size */
	dlist_t		*unique = NULL;	/* volume slices that need spares */
	dlist_t		*curspares = NULL; /* current spares in the HSP */
	dlist_t		*newspares = NULL; /* slices to add to HSP */
	dlist_t		*allspares = NULL; /* current and new spares */

	((error = get_usable_hbas(&usable_hbas)) != 0) ||
	(error = select_hbas_with_n_disks(request, usable_hbas, 1, &sel_hbas,
		&disks)) ||
	(error = disks_get_avail_slices(request, disks, &avail)) ||
	(error = get_volume_npaths(request, &npaths));
	if (error != 0) {
	    dlist_free_items(sel_hbas, NULL);
	    dlist_free_items(disks, NULL);
	    dlist_free_items(avail, NULL);
	    return (error);
	}

	if (disks == NULL || dlist_length(disks) == 0) {
	    /* all disks have been consumed by the devices */
	    volume_set_error(
		    gettext("  no available disks to populate HSP\n"));
	    dlist_free_items(sel_hbas, NULL);
	    dlist_free_items(avail, NULL);
	    return (-1);
	}

	if (avail == NULL || dlist_length(avail) == 0) {
	    /* all slices have been consumed by the devices */
	    volume_set_error(
		    gettext("  no available slices to populate HSP\n"));
	    dlist_free_items(sel_hbas, NULL);
	    dlist_free_items(disks, NULL);
	    return (-1);
	}

	dlist_free_items(sel_hbas, NULL);
	dlist_free_items(disks, NULL);

	/* build list of slices needing to be spared */
	((error = get_uniquely_sized_slices(devices, &unique)) != 0) ||

	/* and list of slices of sufficient size to spare for them */
	(error = remove_undersized_slices(unique, &avail));

	if (error != 0) {
	    dlist_free_items(avail, NULL);
	    dlist_free_items(unique, NULL);
	    dlist_free_items(slices, NULL);
	    return (error);
	}

	/* get spares currently in the HSP */
	curspares = devconfig_get_components(hsp);

	/* clone current spares list */
	for (iter = curspares;
	    (iter != NULL) && (error == 0);
	    iter = iter->next) {
	    dlist_t *item = dlist_new_item(iter->obj);
	    if (item == NULL) {
		error = ENOMEM;
	    } else {
		allspares = dlist_append(item, allspares, AT_TAIL);
	    }
	}

	if (error != 0) {
	    dlist_free_items(avail, NULL);
	    dlist_free_items(unique, NULL);
	    dlist_free_items(slices, NULL);
	    dlist_free_items(allspares, NULL);
	    return (error);
	}

	/*
	 * examine device component slices and see if the HSP already
	 * has a suitable spare. If not, select the best available
	 * of the same (or larger) size
	 */
	for (iter = devices;
	    (iter != NULL) && (error == 0);
	    iter = iter->next) {

	    devconfig_t *device = (devconfig_t *)iter->obj;
	    dlist_t *components = devconfig_get_components(device);
	    dlist_t *hbas = NULL;
	    dlist_t *disks = NULL;
	    dlist_t *iter1;

	    error = get_hbas_and_disks_used_by_volume(device, &hbas, &disks);
	    for (iter1 = components; (iter1 != NULL) && (error == 0);
		iter1 = iter1->next) {

		devconfig_t	*comp = (devconfig_t *)iter1->obj;
		boolean_t	found = B_FALSE;

		if ((error = find_spare_for_component(
		    comp, allspares, hbas, disks, &found)) == 0) {
		    if (found != B_TRUE) {
			error = choose_spare_for_component(
				comp, &allspares, &newspares,
				&avail, hbas, disks, npaths);
		    }
		}
	    }
	    dlist_free_items(disks, NULL);
	    dlist_free_items(hbas, NULL);
	}

	if (error == 0) {
	    /* existing spares are no longer needed */
	    dlist_free_items(curspares, free_devconfig_object);
	    curspares = NULL;

	    error = assemble_hsp(hsp, newspares, devices);
	} else {
	    dlist_free_items(newspares, free_devconfig_object);
	    newspares = NULL;
	}

	dlist_free_items(avail, NULL);
	dlist_free_items(slices, NULL);
	dlist_free_items(unique, NULL);
	dlist_free_items(allspares, NULL);

	return (error);
}

/*
 * FUNCTION:	assemble_hsp(devconfig_t *hsp, dlist_t *newspares,
 *			dlist_t *devices)
 *
 * INPUT:	request	- pointer to a HSP devconfig_t
 *		newspare - pointer to a list of new spares for the HSP
 *		devices - pointer to a list of devices to be served by the HSP
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Final assembly of an HSP. Attach new spare components
 *		and associate the HSP with each device in the input list.
 */
static int
assemble_hsp(
	devconfig_t 	*hsp,
	dlist_t		*newspares,
	dlist_t		*devices)
{
	dlist_t		*iter;
	char		*hspname = NULL;
	int		error = 0;

	/* add new spares to HSP */
	(void) devconfig_set_components(hsp, newspares);
	(void) devconfig_get_name(hsp, &hspname);

	/* associate HSP with each of the devices */
	for (iter = devices;
	    (iter != NULL) && (error == 0);
	    iter = iter->next) {

	    devconfig_t *dev = iter->obj;
	    devconfig_t *hspcomp = NULL;
	    dlist_t	*item = NULL;
	    char	*devname = NULL;

	    ((error = devconfig_get_name(dev, &devname)) != 0) ||
	    (error = new_devconfig(&hspcomp, TYPE_HSP)) ||
	    (error = devconfig_set_name(hspcomp, hspname));

	    if (error != 0) {

		free_devconfig(hspcomp);

	    } else if ((item = dlist_new_item(hspcomp)) == NULL) {

		free_devconfig(hspcomp);
		error = ENOMEM;

	    } else {

		dlist_t	*comps = devconfig_get_components(dev);
		comps = dlist_append(comps, item, AT_TAIL);
		(void) devconfig_set_components(dev, comps);

		oprintf(OUTPUT_VERBOSE,
			gettext("  --->volume %s will use HSP %s\n"),
			devname, hspname);
	    }
	}

	return (error);
}

/*
 * FUNCTION:	get_uniquely_sized_slices(dlist_t *devices,
 *			dlist_t **unique)
 *
 * INPUT:	devices	- pointer to a list of devconfig_t devices
 *
 * OUTPUT:	unique	- pointer to a list of uniquely size slices
 *			from the input list of devices.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Examine each device's slice components and build a list
 *		of uniquely sized slices.
 */
static int
get_uniquely_sized_slices(
	dlist_t 	*devices,
	dlist_t 	**unique)
{
	int		error = 0;
	dlist_t		*iter = NULL;

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

	    dlist_t *iter1;
	    for (iter1 = devconfig_get_components((devconfig_t *)iter->obj);
		(iter1 != NULL) && (error == 0);
		iter1 = iter1->next) {

		devconfig_t *comp = (devconfig_t *)iter1->obj;
		if (dlist_contains(*unique, comp,
		    compare_devconfig_sizes) != B_TRUE) {

		    dlist_t *item = NULL;
		    if ((item = dlist_new_item(comp)) == NULL) {
			error = ENOMEM;
		    } else {
			*unique = dlist_insert_ordered(item, *unique,
				ASCENDING, compare_devconfig_sizes);
		    }
		}
	    }
	}

	return (error);
}

/*
 * FUNCTION:	remove_undersized_slices(dlist_t *unique,
 *			dlist_t **avail)
 *
 * INPUT:	avail	- pointer to a list of available slices
 * 		unique	- pointer to a list of uniquely size slices
 *
 * OUTPUT:	avail - pointer to an updated list of available slices
 *			that are at least as large as slices in the
 *			unique list.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	filter available slices and remove those that aren't
 *		large enough for the device components which need spares.
 *
 *		For each uniquely sized slice, find all available slices
 *		that are larger and add them to the filtered list.
 */
static int
remove_undersized_slices(
	dlist_t		*unique,
	dlist_t		**avail)
{
	dlist_t		*filtered = NULL;
	dlist_t		*iter = NULL;
	int		error = 0;

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

	    devconfig_t	*uslice = (devconfig_t *)iter->obj;
	    uint64_t	usize = 0;
	    dlist_t	*iter2 = NULL;

	    error = devconfig_get_size(uslice, &usize);

	    for (iter2 = *avail;
		(iter2 != NULL) && (error == 0);
		iter2 = iter2->next) {

		dm_descriptor_t	aslice = (uintptr_t)iter2->obj;
		uint64_t	asize = 0;

		error = slice_get_size(aslice, &asize);
		if (asize >= usize) {

		    /* this slice is large enough */
		    dlist_t *item = NULL;
		    if ((item = dlist_new_item((void *)(uintptr_t)aslice)) ==
			NULL) {
			error = ENOMEM;
		    } else {
			filtered = dlist_insert_ordered(item, filtered,
				ASCENDING, compare_slice_sizes);
		    }

		}
	    }
	}

	if (error == 0) {
	    dlist_free_items(*avail, NULL);
	    *avail = filtered;
	} else {
	    dlist_free_items(filtered, NULL);
	}

	return (error);
}

/*
 * FUNCTION:	find_spare_for_component(devconfig_t *component,
 *			dlist_t *all_spares, dlist_t *hbas, dlist_t *disks,
 *			boolean_t *found)
 *
 * INPUT:	comp	- pointer to a devconfig_t slice compenent that
 *				needs to be spared
 * 		all_spares - pointer to a list of spares currently
 *				in the pool or that will be added
 * 		hbas	- pointer to a list of HBAs the component's
 *				parent device utilizes
 * 		disks	- pointer to a list of disks the component's
 *				parent device utilizes
 *
 * OUTPUT:	found - pointer to a boolean_t to hold the result.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Find a spare for the input component.
 *
 *		Searches the input list of spares to see if one is
 *		sufficient.
 *
 *		A suffcient spare is one that is large enough to spare
 *		for the input component and not on the same disk as any
 *		of the components in the parent device.
 *
 *		The optimal spare would be on a different controller/HBA
 *		as the component and any of the components in the parent
 *		device.  We settle for sufficient.
 */
static int
find_spare_for_component(
	devconfig_t	*component,
	dlist_t		*all_spares,
	dlist_t		*hbas,
	dlist_t		*disks,
	boolean_t	*found)
{
	dlist_t		*iter = NULL;
	uint64_t	csize = 0;
	int		error = 0;

	*found = B_FALSE;

	(void) devconfig_get_size(component, &csize);

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

	    devconfig_t		*spare = (devconfig_t *)iter->obj;
	    char 		*spname = NULL;
	    uint64_t 		spsize = 0;

	    if (((error = devconfig_get_name(spare, &spname)) != 0) ||
		((error = devconfig_get_size(spare, &spsize)) != 0)) {
		continue;
	    }

	    if (spsize >= csize) {

		dm_descriptor_t	disk = NULL;

		/* see if spare's disk is independent of the volume */
		error = get_disk_for_named_slice(spname, &disk);
		if ((error == 0) && (dlist_contains(disks,
		    (void *)(uintptr_t)disk, compare_descriptor_names) ==
		    B_FALSE)) {
		    *found = B_TRUE;
		}
	    }
	}

	if ((*found == B_TRUE) && (get_max_verbosity() >= OUTPUT_DEBUG)) {
	    char *cname = NULL;
	    (void) devconfig_get_name(component, &cname);
	    oprintf(OUTPUT_DEBUG,
		    gettext("    found existing spare for: %s (%llu)\n"),
		    cname, csize);
	}

	return (error);
}

/*
 * FUNCTION:	choose_spare_for_component(devconfig_t *component,
 *			dlist_t *all_spares, dlist_t **new_spares,
 *			dlist_t avail, uint16_t npaths, dlist_t *used_hbas,
 *			dlist_t *used_disks)
 *
 * INPUT:	comp	- pointer to a devconfig_t slice compenent that
 *				needs to be spared
 * 		all_spares - pointer to a list of spares currently
 *				in the pool and those to be added
 * 		new_spares - pointer to a list of spares that need to
 *				be added to the pool
 *		avail	- list of available slices
 *		npaths	- required number of paths for the spare
 *		used_hbas - list of HBAs used by the component's parent
 *		used_disks - list of disks used by the component's parent
 *
 * OUTPUT:	all_spares - the possibly updated list of all spares
 *		new_spares - the possibly updated list of spares which
 *			need to be added to the pool.
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Find a new spare for the input component.
 *
 *		Select a spare from the available slice list and add
 *		it to the new_spares list.
 *
 *		The spare slice chosen should be on a unique HBA and
 *		disk relative to the input lists of used HBAs and disks
 *		and any spares in the pool.
 */
static int
choose_spare_for_component(
	devconfig_t	*component,
	dlist_t		**all_spares,
	dlist_t		**new_spares,
	dlist_t		**avail,
	dlist_t		*used_hbas,
	dlist_t		*used_disks,
	uint16_t	npaths)
{
	devconfig_t	*spare = NULL;
	uint64_t	csize = 0;
	int		error = 0;

	(void) devconfig_get_size(component, &csize);

	if (get_max_verbosity() >= OUTPUT_DEBUG) {
	    char *cname = NULL;
	    (void) devconfig_get_name(component, &cname);
	    oprintf(OUTPUT_DEBUG,
		    gettext("    select new spare for: %s (%llu)\n"),
		    cname, csize);
	}

	/*
	 * find a spare for the input component.
	 * select the best one from the available list that
	 * is on a unique disk.
	 */

	/*
	 * 1st B_TRUE: require a different disk than those used by
	 *		all spares and devices
	 * 2nd B_TRUE: requested size is the minimum acceptable
	 * 1st B_FALSE: do not add an extra cylinder when resizing slice,
	 *		this is only necessary for Stripe components whose
	 *		sizes get rounded down to an interlace multiple and
	 *		then down to a cylinder boundary.
	 */
	error = choose_slice(csize, npaths, *avail, *all_spares,
		used_hbas, used_disks, B_TRUE, B_TRUE, B_FALSE, &spare);

	if ((error == 0) && (spare == NULL)) {
	    /* can't find one on a unique disk, try again on any disk */

	    /* BEGIN CSTYLED */
	    /*
	     * 1st B_FALSE: don't require a different disk than those used
	     *		by all spares and devices
	     * 2nd B_TRUE: requested size is still the minimum acceptable
	     * 2nd B_FALSE: do not add an extra cylinder when resizing slice
	     *		this is only necessary for Stripe components whose
	     *		sizes get rounded down to an interlace multiple and
	     *		then down to a cylinder boundary.
	     */
	    /* END CSTYLED */
	    error = choose_slice(
		    csize, npaths, *avail, *all_spares, used_hbas,
		    used_disks, B_FALSE, B_TRUE, B_FALSE, &spare);
	}

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

	    dlist_t	*rmvd = NULL;
	    dlist_t	*item = NULL;
	    char	*spname = NULL;

	    if ((item = dlist_new_item(spare)) == NULL) {
		error = ENOMEM;
	    } else {

		/* add spare to the all spares list */
		*all_spares = dlist_append(item, *all_spares, AT_HEAD);

		if ((item = dlist_new_item(spare)) == NULL) {
		    error = ENOMEM;
		} else {

		    /* add spare to the new spares list */
		    *new_spares = dlist_insert_ordered(
			    item, *new_spares, ASCENDING,
			    compare_devconfig_sizes);

		    /* remove it from the available list */
		    *avail = dlist_remove_equivalent_item(*avail, spare,
			    compare_devconfig_and_descriptor_names,
			    &rmvd);

		    if (rmvd != NULL) {
			free(rmvd);
		    }

		    /* add the spare to the used slice list */
		    error = devconfig_get_name(spare, &spname);
		    if (error == 0) {
			error = add_used_slice_by_name(spname);
		    }
		}
	    }

	} else {

	    /* no spare, give up on layout */
	    oprintf(OUTPUT_TERSE,
		    gettext("  <---Failed: insufficient suitable spares\n"));

	    volume_set_error(
		    gettext("failed to find sufficient spares for HSP\n"));

	    error = -1;
	}

	return (error);
}