/*
 * 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 2004 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_devconfig.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_STRIPE_C

static int compose_stripe(
	devconfig_t	*request,
	uint64_t	nbytes,
	dlist_t		*disks,
	int		max,
	int		min,
	dlist_t		*othervols,
	devconfig_t	**stripe);

static int compose_stripe_within_hba(
	devconfig_t	*request,
	dlist_t		*hbas,
	uint64_t	nbytes,
	uint16_t	min,
	uint16_t	max,
	devconfig_t	**stripe);

static int assemble_stripe(
	devconfig_t	*request,
	dlist_t		*comps,
	devconfig_t	**stripe);

static dlist_t *
order_stripe_components_alternate_hbas(
	dlist_t *comps);

static int compute_usable_stripe_capacity(
	dlist_t		*comps,
	uint64_t	ilace,
	uint64_t	*nbytes);

/*
 * FUNCTION:	layout_stripe(devconfig_t *request, uint64_t nbytes,
 *			dlist_t **results)
 *
 * INPUT:	request	- pointer to a devconfig_t of the current request
 *		nbytes	- the desired capacity of the stripe
 *
 * OUPUT:	results	- pointer to a list of composed volumes
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Main layout driver for composing stripe volumes.
 *
 *		Attempts to construct a stripe of size nbytes.
 *
 *		Basic goal of all strategies is to build wide-thin stripes:
 *		build widest stripe possible across as many HBAs as possible.
 *
 *		Several different layout strategies are tried in order
 *		of preference until one succeeds or there are none left.
 *
 *		1 - stripe across similar HBAs
 *		    . number of components is driven by # of HBAs
 *		    . requires mincomp available HBAs
 *
 *		2 - stripe within a single HBA
 *		    . number of components is driven by # of disks
 *		    . requires at least 1 HBA with mincomp disks
 *
 *		3 - stripe across all available disks on similar HBAs
 *		    . number of components is driven by # of disk
 *		    . requires at least mincomp disks
 *
 *		4 - stripe across all available HBAs
 *		    . number of components is driven by # of HBAs
 *		    . requires at least mincomp HBAs
 *
 *		5 - stripe across all available disks on all HBAs
 *		    . number of components is driven by # of disks
 *		    . requires at least mincomp disks
 *
 *		Each strategy tries to compose a stripe with the
 *		maximum number of components first then reduces the
 *		number of components down to mincomp.
 *
 *		get allowed minimum number of stripe components
 *		get allowed maximum number of stripe components
 *		get available HBAs
 *
 *		group HBAs by characteristics
 *		for (each HBA grouping) and (stripe not composed) {
 *		    select next HBA group
 *		    for (strategy[1,2,3]) and (stripe not composed) {
 *			compose stripe using HBAs in group
 *		    }
 *		}
 *
 *		if (stripe not composed) {
 *		    for (strategy[4,5]) and (stripe not composed) {
 *			compose stripe using all HBAs
 *		    }
 *		}
 *
 *		if (stripe composed) {
 *		    append composed stripe to results
 *		}
 *
 */
int
layout_stripe(
	devconfig_t	*request,
	uint64_t	nbytes,
	dlist_t		**results)
{
	/*
	 * these enums define the # of strategies and the preference order
	 * in which they are tried
	 */
	typedef enum {
		STRIPE_ACROSS_SIMILAR_HBAS_DISK_PER = 0,
		STRIPE_WITHIN_SIMILAR_HBA,
		STRIPE_ACROSS_SIMILAR_HBAS,
		N_SIMILAR_HBA_STRATEGIES
	} similar_hba_strategy_order_t;

	typedef enum {
		STRIPE_ACROSS_ANY_HBAS_DISK_PER = 0,
		STRIPE_ACROSS_ANY_HBAS,
		N_ANY_HBA_STRATEGIES
	} any_hba_strategy_order_t;


	dlist_t		*usable_hbas = NULL;
	dlist_t		*similar_hba_groups = NULL;
	dlist_t		*iter = NULL;
	devconfig_t	*stripe = NULL;

	uint16_t	mincomp	= 0;
	uint16_t	maxcomp	= 0;

	int		error = 0;

	(error = get_usable_hbas(&usable_hbas));
	if (error != 0) {
	    return (error);
	}

	print_layout_volume_msg(devconfig_type_to_str(TYPE_STRIPE), nbytes);

	if (dlist_length(usable_hbas) == 0) {
	    print_no_hbas_msg();
	    volume_set_error(gettext("There are no usable HBAs."));
	    return (-1);
	}

	((error = group_similar_hbas(usable_hbas, &similar_hba_groups)) != 0) ||

	/*
	 * determine the min/max number of stripe components
	 * based on the request, the diskset defaults or the
	 * global defaults.  These are absolute limits, the
	 * actual values are determined by the number of HBAs
	 * and/or disks available.
	 */
	(error = get_stripe_min_comp(request, &mincomp)) ||
	(error = get_stripe_max_comp(request, &maxcomp));
	if (error != 0) {
	    return (error);
	}

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

	    dlist_t *hbas = (dlist_t *)iter->obj;

	    similar_hba_strategy_order_t order;

	    for (order = STRIPE_ACROSS_SIMILAR_HBAS_DISK_PER;
		(order < N_SIMILAR_HBA_STRATEGIES) &&
			(stripe == NULL) && (error == 0);
		order++) {

		dlist_t *selhbas = NULL;
		dlist_t	*disks = NULL;
		int	n = 0;

		switch (order) {

		case STRIPE_ACROSS_SIMILAR_HBAS_DISK_PER:

		    error = select_hbas_with_n_disks(
			    request, hbas, 1, &selhbas, &disks);

		    if (error == 0) {

/* BEGIN CSTYLED */
oprintf(OUTPUT_TERSE,
gettext("  -->Strategy 1: use 1 disk from %d-%d similar HBAs - stripe across HBAs\n"),
	mincomp, maxcomp);
/* END CSTYLED */

			if ((n = dlist_length(selhbas)) >= mincomp) {
			    n = ((n > maxcomp) ? maxcomp : n);
			    error = compose_stripe(
				    request, nbytes, disks, n,
				    mincomp, NULL, &stripe);
			} else {
			    print_insufficient_hbas_msg(n);
			}
		    }

		    break;

		case STRIPE_WITHIN_SIMILAR_HBA:

		    error = select_hbas_with_n_disks(
			    request, hbas, mincomp, &selhbas, &disks);

		    if (error == 0) {

/* BEGIN CSTYLED */
oprintf(OUTPUT_TERSE,
gettext("  -->Strategy 2: use %d-%d disks from any single HBA - stripe within HBA\n"),
	mincomp, maxcomp);
/* END CSTYLED */

			if ((n = dlist_length(selhbas)) > 0) {
			    error = compose_stripe_within_hba(
				    request, selhbas, nbytes,
				    mincomp, maxcomp, &stripe);
			} else {
			    print_insufficient_disks_msg(n);
			}
		    }

		    break;

		case STRIPE_ACROSS_SIMILAR_HBAS:

		    error = select_hbas_with_n_disks(
			    request, hbas, 1, &selhbas, &disks);

		    if (error == 0) {

/* BEGIN CSTYLED */
oprintf(OUTPUT_TERSE,
gettext("  -->Strategy 3: use %d-%d disks from %d similar HBAs - stripe across HBAs\n"),
	mincomp, maxcomp, dlist_length(hbas));
/* END CSTYLED */

			if ((n = dlist_length(selhbas)) > 0) {
			    if ((n = dlist_length(disks)) >= mincomp) {
				n = ((n > maxcomp) ? maxcomp : n);
				error = compose_stripe(
					request, nbytes, disks, n,
					mincomp, NULL, &stripe);
			    } else {
				print_insufficient_disks_msg(n);
			    }
			} else {
			    print_insufficient_hbas_msg(n);
			}
		    }

		    break;

		default:
		    break;
		}

		dlist_free_items(disks, NULL);
		dlist_free_items(selhbas, NULL);
	    }
	}

	for (iter = similar_hba_groups; iter != NULL; iter = iter->next) {
	    dlist_free_items((dlist_t *)iter->obj, NULL);
	}
	dlist_free_items(similar_hba_groups, NULL);

	/*
	 * if striping within similar HBA groups failed,
	 * try across all available HBAs
	 */
	if ((stripe == NULL) && (error == 0)) {

	    any_hba_strategy_order_t order;

	    for (order = STRIPE_ACROSS_ANY_HBAS_DISK_PER;
		(order < N_ANY_HBA_STRATEGIES) &&
			(stripe == NULL) && (error == 0);
		order++) {

		dlist_t	*selhbas = NULL;
		dlist_t	*disks = NULL;
		int	n = 0;

		switch (order) {

		case STRIPE_ACROSS_ANY_HBAS_DISK_PER:

		    error = select_hbas_with_n_disks(
			    request, usable_hbas, 1, &selhbas, &disks);

		    if (error == 0) {

/* BEGIN CSTYLED */
oprintf(OUTPUT_TERSE,
gettext("  -->Strategy 4: use 1 disk from %d-%d available HBAs - stripe across any HBAs\n"),
	mincomp, maxcomp);
/* END CSTYLED */

			if ((n = dlist_length(selhbas)) >= mincomp) {

			    n = ((n > maxcomp) ? maxcomp : n);
			    error = compose_stripe(
				    request, nbytes, disks, n,
				    mincomp, NULL, &stripe);

			} else {
			    print_insufficient_hbas_msg(n);
			}
		    }

		    break;

		case STRIPE_ACROSS_ANY_HBAS:

		    error = select_hbas_with_n_disks(
			    request, usable_hbas, 1, &selhbas, &disks);

		    if (error == 0) {

/* BEGIN CSTYLED */
oprintf(OUTPUT_TERSE,
gettext("  -->Strategy 5: use %d-%d disks from %d available HBA - stripe across any HBAs\n"),
	mincomp, maxcomp, dlist_length(selhbas));
/* END CSTYLED */

			if ((n = dlist_length(disks)) >= mincomp) {

			    n = ((n > maxcomp) ? maxcomp : n);
			    error = compose_stripe(
				    request, nbytes, disks, n,
				    mincomp, NULL, &stripe);

			} else {
			    print_insufficient_disks_msg(n);
			}
		    }

		    break;
		}

		dlist_free_items(disks, NULL);
		dlist_free_items(selhbas, NULL);
	    }
	}

	if (stripe != NULL) {

	    dlist_t *item = NULL;
	    if ((item = dlist_new_item(stripe)) == NULL) {
		error = ENOMEM;
	    } else {
		*results = dlist_append(item, *results, AT_TAIL);
		print_layout_success_msg();
	    }

	} else if (error != 0) {

	    print_debug_failure_msg(
		    devconfig_type_to_str(TYPE_STRIPE),
		    get_error_string(error));

	} else {

	    print_insufficient_resources_msg(
		    devconfig_type_to_str(TYPE_STRIPE));
	    error = -1;
	}

	return (error);
}

/*
 * FUNCTION:	populate_stripe(devconfig_t *request, uint64_t nbytes,
 *			dlist_t *disks, uint16_t ncomp, dlist_t *othervols,
 *			devconfig_t **stripe)
 *
 * INPUT:	request	- pointer to a request devconfig_t
 *		nbytes	- desired stripe size
 *		disks	- pointer to a list of availalb disks
 *		ncomp	- number of components desired
 *		othervols - pointer to a list of other volumes whose
 *				composition may affect this stripe
 *				(e.g., submirrors of the same mirror)
 *
 * OUTPUT:	stripe	- pointer to a devconfig_t to hold resulting stripe
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Helper to populate a stripe with the specified number of
 *		components and aggregate capacity using slices on disks
 *		in the input list.
 *
 *		If the othervols list is not empty, the slice components
 *		chosen for the stripe must not on the same disks as any
 *		of the other volumes.
 *
 *		If sufficient slice components can be found, the stripe
 *		is assembled and returned.
 */
int
populate_stripe(
	devconfig_t	*request,
	uint64_t	nbytes,
	dlist_t		*disks,
	uint16_t	ncomp,
	dlist_t		*othervols,
	devconfig_t	**stripe)
{
	uint16_t	npaths = 0;
	uint16_t	ncomps = 0;	/* number of components found */
	uint64_t	rsize = 0;	/* reqd component size */

	dlist_t		*other_hbas = NULL;
	dlist_t		*other_disks = NULL;

	dlist_t		*slices = NULL;
	dlist_t		*comps = NULL;

	int		error = 0;

	*stripe = NULL;

	((error = disks_get_avail_slices(request, disks, &slices)) != 0) ||
	(error = get_volume_npaths(request, &npaths));
	if (error != 0) {
	    return (error);
	}

	print_populate_volume_ncomps_msg(
		devconfig_type_to_str(TYPE_STRIPE), nbytes, ncomp);

	if (slices == NULL) {
	    print_populate_no_slices_msg();
	    return (0);
	}

	/* determine HBAs and disks used by othervols */
	error = get_hbas_and_disks_used_by_volumes(othervols,
		&other_hbas, &other_disks);
	if (error != 0) {
	    dlist_free_items(other_hbas, NULL);
	    dlist_free_items(other_disks, NULL);
	    return (error);
	}

	print_populate_choose_slices_msg();

	/*
	 * each stripe component needs to be this size.
	 * Note that the stripe interlace doesn't need to be
	 * taken into account in this computation because any
	 * slice selected as a stripe component will be oversized
	 * to account for interlace and cylinder rounding done
	 * by libmeta.
	 */
	rsize = nbytes / ncomp;

	/*
	 * need to select 'ncomp' slices that are at least 'rsize'
	 * large in order to reach the desired capacity.
	 */
	ncomps = 0;
	while ((ncomps < ncomp) && (error == 0)) {

	    devconfig_t	*comp = NULL;
	    dlist_t	*item = NULL;
	    dlist_t	*rmvd = NULL;
	    char	*cname = NULL;

	    /* BEGIN CSTYLED */
	    /*
	     * 1st B_TRUE: require a different disk than those used by
	     *		comps and othervols
	     * 2nd B_TRUE: requested size is minimum acceptable
	     * 3rd B_TRUE: add an extra cylinder to the resulting slice, this is
	     *		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(rsize, npaths, slices, comps,
		    other_hbas, other_disks, B_TRUE, B_TRUE, B_TRUE, &comp);

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

		++ncomps;

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

		    /* add selected component to comp list */
		    comps = dlist_insert_ordered(
			    item,
			    comps,
			    ASCENDING,
			    compare_devconfig_sizes);

		    /* remove it from the available list */
		    slices = dlist_remove_equivalent_item(slices, (void *) comp,
			    compare_devconfig_and_descriptor_names, &rmvd);

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

		    /* add the component slice to the used list */
		    if ((error = devconfig_get_name(comp, &cname)) == 0) {
			error = add_used_slice_by_name(cname);
		    }
		}
	    } else if (comp == NULL) {
		/* no possible slice */
		break;
	    }
	}

	dlist_free_items(slices, NULL);
	dlist_free_items(other_hbas, NULL);
	dlist_free_items(other_disks, NULL);

	if (ncomps == ncomp) {

	    if ((error = assemble_stripe(request, comps, stripe)) == 0) {
		print_populate_success_msg();
	    } else {
		dlist_free_items(comps, free_devconfig_object);
	    }

	} else if (error == 0) {

	    if (ncomps > 0) {
		print_insufficient_components_msg(ncomps);
		dlist_free_items(comps, free_devconfig_object);
	    } else {
		print_populate_no_slices_msg();
	    }

	}
	return (error);
}

/*
 * FUNCTION:	populate_explicit_stripe(devconfig_t *request,
 *			dlist_t **results)
 *
 * INPUT:	request	- pointer to a request devconfig_t
 *
 * OUTPUT:	results	- pointer to a list of volume devconfig_t results
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Processes the input stripe request that specifies explicit
 *		slice components.
 *
 *		The components have already been validated and reserved,
 *		all that is required is to create devconfig_t structs
 *		for each requested slice.
 *
 *		The net size of the stripe is determined by the slice
 *		components.
 *
 *		The stripe devconfig_t is assembled and appended to the
 *		results list.
 *
 *		This function is also called from
 *		    layout_mirror.populate_explicit_mirror()
 */
int
populate_explicit_stripe(
	devconfig_t	*request,
	dlist_t		**results)
{
	devconfig_t	*stripe = NULL;
	int		error = 0;

	dlist_t		*comps = NULL;
	dlist_t		*iter = NULL;
	dlist_t		*item = NULL;

	print_layout_explicit_msg(devconfig_type_to_str(TYPE_STRIPE));

	/* assemble components */
	iter = devconfig_get_components(request);
	for (; (iter != NULL) && (error == 0); iter = iter->next) {
	    devconfig_t	*rqst = (devconfig_t *)iter->obj;
	    dm_descriptor_t rqst_slice = NULL;
	    char	*rqst_name = NULL;
	    devconfig_t	*comp = NULL;

	    /* slice components have been validated */
	    /* turn each into a devconfig_t */
	    ((error = devconfig_get_name(rqst, &rqst_name)) != 0) ||
	    (error = slice_get_by_name(rqst_name, &rqst_slice)) ||
	    (error = create_devconfig_for_slice(rqst_slice, &comp));

	    if (error == 0) {

		print_layout_explicit_added_msg(rqst_name);

		item = dlist_new_item((void *)comp);
		if (item == NULL) {
		    error = ENOMEM;
		} else {
		    comps = dlist_append(item, comps, AT_TAIL);
		}
	    }
	}

	if (error == 0) {
	    error = assemble_stripe(request, comps, &stripe);
	}

	if (error == 0) {
	    if ((item = dlist_new_item(stripe)) == NULL) {
		error = ENOMEM;
	    } else {
		*results = dlist_append(item, *results, AT_TAIL);
		print_populate_success_msg();
	    }
	} else {
	    dlist_free_items(comps, free_devconfig);
	}

	return (error);
}

/*
 * FUNCTION:	compose_stripe(devconfig_t *request, uint64_t nbytes,
 *			dlist_t *disks, uint16_t max, uint16_t min,
 *			dlist_t *othervols, devconfig_t **stripe)
 *
 * INPUT:	request	- pointer to a request devconfig_t
 *		nbytes	- desired stripe size
 *		disks	- pointer to a list of availalb disks
 *		max	- maximum number of components allowed
 *		min	- minimum number of components allowed
 *		othervols - pointer to a list of other volumes whose
 *				composition may affect this stripe
 *				(e.g., submirrors of the same mirror)
 *
 * OUTPUT:	stripe	- pointer to a devconfig_t to hold resulting stripe
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Attempt to compose a stripe of capacity nbytes, with
 *		component slices chosen from the input list of disks.
 *		The number of components in the stripe should be in the
 *		range min <= N <= max, more components are preferred.
 *
 *		If a stripe can be composed, a pointer to it will be
 *		returned in the stripe devconfig_t.
 *
 *		This is a loop wrapped around populate_stripe which
 *		varies the number of components between 'max' and 'min'.
 */
static int
compose_stripe(
	devconfig_t	*request,
	uint64_t	nbytes,
	dlist_t		*disks,
	int		max,
	int		min,
	dlist_t		*othervols,
	devconfig_t	**stripe)
{
	int		error = 0;

	*stripe = NULL;

	for (; (error == 0) && (*stripe == NULL) && (max >= min); max--) {
	    error = populate_stripe(
		    request, nbytes, disks, max, othervols, stripe);
	}

	return (error);
}

/*
 * FUNCTION:	compose_stripe_within_hba(devconfig_t *request,
 *			dlist_t *hbas, uint64_t nbytes,
 *			int maxcomp, int mincomp, dlist_t **stripe)
 *
 * INPUT:	request	- pointer to a devconfig_t of the current request
 *		hbas	- pointer to a list of available HBAs
 *		nbytes	- the desired capacity for the stripe
 *		maxcomp - the maximum number of stripe components
 *		mincomp - the minimum number of stripe components
 *
 * OUTPUT:	stripe	- pointer to a stripe devconfig_t result
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Layout function which compose a stripe of the desired size
 *		using available disks within any single HBA from the input list.
 *
 *		The number of components within the composed stripe will be
 *		in the range of min to max, preferring more components
 *		over fewer.
 *
 * 		All input HBAs are expected to have at least mincomp
 *		available disks and total space sufficient for the stripe.
 *
 *		If the stripe can be composed, a pointer to it is returned in
 *		the stripe devconfig_t *.
 *
 *
 *		while (more hbas and stripe not composed) {
 *		    select HBA
 *		    if (not enough available space on this HBA) {
 *			continue;
 *		    }
 *		    get available disks for HBA
 *		    use # disks as max # of stripe components
 *		    try to compose stripe
 *		}
 *
 */
static int
compose_stripe_within_hba(
	devconfig_t	*request,
	dlist_t		*hbas,
	uint64_t	nbytes,
	uint16_t	min,
	uint16_t	max,
	devconfig_t	**stripe)
{
	int		error = 0;

	dlist_t		*iter = NULL;

	*stripe = NULL;

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

	    dm_descriptor_t hba = (uintptr_t)iter->obj;
	    dlist_t	*disks = NULL;
	    uint64_t	space = 0;
	    uint16_t	ncomp = 0;
	    char	*name;

	    ((error = get_display_name(hba, &name)) != 0) ||
	    (error = hba_get_avail_disks_and_space(request,
		    hba, &disks, &space));

	    if (error == 0) {
		if (space >= nbytes) {
		    ncomp = dlist_length(disks);
		    ncomp = ((ncomp > max) ? max : ncomp);
		    error = compose_stripe(
			    request, nbytes, disks, ncomp,
			    min, NULL, stripe);
		} else {
		    print_hba_insufficient_space_msg(name, space);
		}
	    }

	    dlist_free_items(disks, NULL);
	}

	return (error);
}

/*
 * FUNCTION:	assemble_stripe(devconfig_t *request, dlist_t *comps,
 *			devconfig_t **stripe)
 *
 * INPUT:	request	- pointer to a devconfig_t of the current request
 *		comps	- pointer to a list of slice components
 *
 * OUPUT:	stripe	- pointer to a devconfig_t to hold final stripe
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Helper which creates and populates a stripe devconfig_t
 *		struct using information from the input request and the
 *		list of slice components.
 *
 *		Determines the name of the stripe either from the request
 *		or from the default naming scheme.
 *
 *		Sets the interlace for the stripe if a value is specified
 *		in the request.
 *
 *		Attaches the input list of components to the devconfig.
 */
static int
assemble_stripe(
	devconfig_t	*request,
	dlist_t		*comps,
	devconfig_t	**stripe)
{
	uint64_t ilace = 0;
	char	*name = NULL;
	int	error = 0;

	if ((error = new_devconfig(stripe, TYPE_STRIPE)) == 0) {
	    /* set stripe name, use requested name if specified */
	    if ((error = devconfig_get_name(request, &name)) != 0) {
		if (error != ERR_ATTR_UNSET) {
		    volume_set_error(gettext("error getting requested name\n"));
		} else {
		    error = 0;
		}
	    }

	    if (error == 0) {
		if (name == NULL) {
		    if ((error = get_next_volume_name(&name,
			TYPE_STRIPE)) == 0) {
			error = devconfig_set_name(*stripe, name);
			free(name);
		    }
		} else {
		    error = devconfig_set_name(*stripe, name);
		}
	    }
	}

	if (error == 0) {
	    if ((error = get_stripe_interlace(request, &ilace)) == 0) {
		error = devconfig_set_stripe_interlace(*stripe, ilace);
	    } else if (error == ENOENT) {
		ilace = get_default_stripe_interlace();
		error = 0;
	    }
	}

	if (error == 0) {
	    uint64_t	nbytes = 0;
	    if ((error = compute_usable_stripe_capacity(comps,
		ilace, &nbytes)) == 0) {
		error = devconfig_set_size_in_blocks(*stripe, nbytes/DEV_BSIZE);
	    }
	}

	if (error == 0) {
	    comps = order_stripe_components_alternate_hbas(comps);
	    devconfig_set_components(*stripe, comps);
	} else {
	    free_devconfig(*stripe);
	    *stripe = NULL;
	}

	return (error);
}

/*
 * Order the given stripe component list such that the number of
 * slices on the same hba adjacent to each other in the list are
 * minimized.
 *
 * @param       comps
 *              the slice component list to order
 *
 * @return      the first element of the resulting list
 */
static dlist_t *
order_stripe_components_alternate_hbas(
	dlist_t *comps)
{
	dlist_t *iter;

	oprintf(OUTPUT_DEBUG,
	    gettext("Stripe components before ordering to alternate HBAs:\n"));

	for (iter = comps; iter != NULL; iter = iter->next) {
	    devconfig_t *slice = (devconfig_t *)(iter->obj);
	    char *name;
	    devconfig_get_name(slice, &name);
	    oprintf(OUTPUT_DEBUG, "  %s\n", name);
	}

	return (dlist_separate_similar_elements(
	    comps, compare_slices_on_same_hba));
}

/*
 * FUNCTION:	compute_usable_stripe_capacity(dlist_t *comps, uint64_t ilace,
 *			uint64_t *nbytes)
 *
 * INPUT:	comps	- pointer to a list of stripe components
 *		ilace	- the expected stripe interlace in bytes
 *
 * OUPUT:	nbytes	- pointer to hold the computed capacity
 *
 * RETURNS:	int	- 0 on success
 *			 !0 otherwise.
 *
 * PURPOSE:	Helper which computes the usable size of a stripe taking
 *		into account the interlace and cylinder rounding that
 *		libmeta uses: a stripe component's size is rounded down to
 *		an integral multiple of the interlace and then rounded down
 *		to a cylinder boundary on VTOC labeled disks.
 *
 *		(These libmeta computations are in the meta_stripe_attach()
 *		 function of .../lib/lvm/libmeta/common/meta_stripe.c and
 *		 meta_adjust_geom() in .../lib/lvm/libmeta/common/meta_init.c)
 *
 *		This function's implementation iterates the input list of
 *		stripe component slices and determines the smallest usable
 *		component capacity.
 *
 *		The usable stripe capacity is then that component capacity
 *		times the number of components.
 */
static int
compute_usable_stripe_capacity(
	dlist_t		*comps,
	uint64_t	ilace,
	uint64_t	*nbytes)
{
	uint64_t	bytes_per_component = 0;
	dlist_t		*iter;
	int		ncomps = 0;
	int		error = 0;

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

	    devconfig_t		*comp = (devconfig_t *)iter->obj;
	    char		*comp_name = NULL;
	    uint64_t 		comp_nbytes = 0;
	    dm_descriptor_t	comp_disk;
	    boolean_t		comp_disk_efi = B_FALSE;
	    uint64_t 		comp_disk_bps = 0; /* disk bytes per sector */

	    ((error = devconfig_get_size(comp, &comp_nbytes)) != 0) ||
	    (error = devconfig_get_name(comp, &comp_name)) ||
	    (error = get_disk_for_named_slice(comp_name, &comp_disk)) ||
	    (error = disk_get_blocksize(comp_disk, &comp_disk_bps)) ||
	    (error = disk_get_is_efi(comp_disk, &comp_disk_efi));
	    if (error == 0) {

		if (comp_disk_efi == B_FALSE) {
		    uint64_t	nhead = 0;
		    uint64_t	nsect = 0;
		    uint64_t	ncyls = 0;

		    /* do cylinder and interlace rounding for non-EFI disks */
		    ((error = disk_get_ncylinders(comp_disk, &ncyls)) != 0) ||
		    (error = disk_get_nheads(comp_disk, &nhead)) ||
		    (error = disk_get_nsectors(comp_disk, &nsect));
		    if (error == 0) {
			/* compute bytes per cyl */
			uint64_t bpc = nhead * nsect * comp_disk_bps;

			/* round nbytes down to a multiple of interlace */
			comp_nbytes = (comp_nbytes / ilace) * ilace;

			/* round nbytes down to a cylinder boundary */
			comp_nbytes = (comp_nbytes / bpc) * bpc;
		    }
		}

		/* save smallest component size */
		if ((bytes_per_component == 0) ||
		    (comp_nbytes < bytes_per_component)) {
		    bytes_per_component = comp_nbytes;
		}

		++ncomps;
	    }
	}

	if (error == 0) {
	    /* size of stripe = smallest component size * n components */
	    *nbytes = (bytes_per_component * ncomps);
	}

	return (error);
}