xref: /illumos-gate/usr/src/uts/common/os/errorq.c (revision c5bab7026b8e0ac44b25ee08507ea360f177d844)

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

/*
 * Kernel Error Queues
 *
 * A common problem when handling hardware error traps and interrupts is that
 * these errors frequently must be handled at high interrupt level, where
 * reliably producing error messages and safely examining and manipulating
 * other kernel state may not be possible.  The kernel error queue primitive is
 * a common set of routines that allow a subsystem to maintain a queue of
 * errors that can be processed by an explicit call from a safe context or by a
 * soft interrupt that fires at a specific lower interrupt level.  The queue
 * management code also ensures that if the system panics, all in-transit
 * errors are logged prior to reset.  Each queue has an associated kstat for
 * observing the number of errors dispatched and logged, and mdb(1) debugging
 * support is provided for live and post-mortem observability.
 *
 * Memory Allocation
 *
 * 	All of the queue data structures are allocated in advance as part of
 * 	the errorq_create() call.  No additional memory allocations are
 * 	performed as part of errorq_dispatch(), errorq_reserve(),
 *	errorq_commit() or errorq_drain().  This design
 * 	facilitates reliable error queue processing even when the system is low
 * 	on memory, and ensures that errorq_dispatch() can be called from any
 * 	context.  When the queue is created, the maximum queue length is
 * 	specified as a parameter to errorq_create() and errorq_nvcreate().  This
 *	length should represent a reasonable upper bound on the number of
 *	simultaneous errors.  If errorq_dispatch() or errorq_reserve() is
 *	invoked and no free queue elements are available, the error is
 *	dropped and will not be logged.  Typically, the queue will only be
 *	exhausted by an error storm, and in this case
 * 	the earlier errors provide the most important data for analysis.
 * 	When a new error is dispatched, the error data is copied into the
 * 	preallocated queue element so that the caller's buffer can be reused.
 *
 *	When a new error is reserved, an element is moved from the free pool
 *	and returned to the caller.  The element buffer data, eqe_data, may be
 *	managed by the caller and dispatched to the errorq by calling
 *	errorq_commit().  This is useful for additions to errorq's
 *	created with errorq_nvcreate() to handle name-value pair (nvpair) data.
 *	See below for a discussion on nvlist errorq's.
 *
 * Queue Drain Callback
 *
 *      When the error queue is drained, the caller's queue drain callback is
 *      invoked with a pointer to the saved error data.  This function may be
 *      called from passive kernel context or soft interrupt context at or
 *      below LOCK_LEVEL, or as part of panic().  As such, the callback should
 *      basically only be calling cmn_err (but NOT with the CE_PANIC flag).
 *      The callback must not call panic(), attempt to allocate memory, or wait
 *      on a condition variable.  The callback may not call errorq_destroy()
 *      or errorq_drain() on the same error queue that called it.
 *
 *      The queue drain callback will always be called for each pending error
 *      in the order in which errors were enqueued (oldest to newest).  The
 *      queue drain callback is guaranteed to provide at *least* once semantics
 *      for all errors that are successfully dispatched (i.e. for which
 *      errorq_dispatch() has successfully completed).  If an unrelated panic
 *      occurs while the queue drain callback is running on a vital queue, the
 *      panic subsystem will continue the queue drain and the callback may be
 *      invoked again for the same error.  Therefore, the callback should
 *      restrict itself to logging messages and taking other actions that are
 *      not destructive if repeated.
 *
 * Name-Value Pair Error Queues
 *
 *	During error handling, it may be more convenient to store error
 *	queue element data as a fixed buffer of name-value pairs.  The
 *	nvpair library allows construction and destruction of nvlists
 *	in pre-allocated memory buffers.
 *
 *	Error queues created via errorq_nvcreate() store queue element
 *	data as fixed buffer nvlists (ereports).  errorq_reserve()
 *	allocates an errorq element from eqp->eq_bitmap and returns a valid
 *	pointer	to a errorq_elem_t (queue element) and a pre-allocated
 *	fixed buffer nvlist.  errorq_elem_nvl() is used to gain access
 *	to the nvlist to add name-value ereport members prior to
 *	dispatching the error queue element in errorq_commit().
 *
 *	Once dispatched, the drain function will return the element to
 *	eqp->eq_bitmap and reset the associated nv_alloc structure.
 *	error_cancel() may be called to cancel an element reservation
 *	element that was never dispatched (committed).  This is useful in
 *	cases where a programming error prevents a queue element from being
 *	dispatched.
 *
 * Queue Management
 *
 *      The queue element structures and error data buffers are allocated in
 *      two contiguous chunks as part of errorq_create() or errorq_nvcreate().
 *	Each queue element structure contains a next pointer,
 *	a previous pointer, and a pointer to the corresponding error data
 *	buffer.  The data buffer for a nvlist errorq is a shared buffer
 *	for the allocation of name-value pair lists. The elements are kept on
 *      one of four lists:
 *
 *	Unused elements are kept in the free pool, managed by eqp->eq_bitmap.
 *	The eqe_prev and eqe_next pointers are not used while in the free pool
 *	and will be set to NULL.
 *
 *      Pending errors are kept on the pending list, a singly-linked list
 *      pointed to by eqp->eq_pend, and linked together using eqe_prev.  This
 *      list is maintained in order from newest error to oldest.  The eqe_next
 *      pointer is not used by the pending list and will be set to NULL.
 *
 *      The processing list is a doubly-linked list pointed to by eqp->eq_phead
 *      (the oldest element) and eqp->eq_ptail (the newest element).  The
 *      eqe_next pointer is used to traverse from eq_phead to eq_ptail, and the
 *      eqe_prev pointer is used to traverse from eq_ptail to eq_phead.  Once a
 *      queue drain operation begins, the current pending list is moved to the
 *      processing list in a two-phase commit fashion (eq_ptail being cleared
 *	at the beginning but eq_phead only at the end), allowing the panic code
 *      to always locate and process all pending errors in the event that a
 *      panic occurs in the middle of queue processing.
 *
 *	A fourth list is maintained for nvlist errorqs.  The dump list,
 *	eq_dump is used to link all errorq elements that should be stored
 *	in a crash dump file in the event of a system panic.  During
 *	errorq_panic(), the list is created and subsequently traversed
 *	in errorq_dump() during the final phases of a crash dump.
 *
 * Platform Considerations
 *
 *      In order to simplify their implementation, error queues make use of the
 *      C wrappers for compare-and-swap.  If the platform itself does not
 *      support compare-and-swap in hardware and the kernel emulation routines
 *      are used instead, then the context in which errorq_dispatch() can be
 *      safely invoked is further constrained by the implementation of the
 *      compare-and-swap emulation.  Specifically, if errorq_dispatch() is
 *      called from a code path that can be executed above ATOMIC_LEVEL on such
 *      a platform, the dispatch code could potentially deadlock unless the
 *      corresponding error interrupt is blocked or disabled prior to calling
 *      errorq_dispatch().  Error queues should therefore be deployed with
 *      caution on these platforms.
 *
 * Interfaces
 *
 * errorq_t *errorq_create(name, func, private, qlen, eltsize, ipl, flags);
 * errorq_t *errorq_nvcreate(name, func, private, qlen, eltsize, ipl, flags);
 *
 *      Create a new error queue with the specified name, callback, and
 *      properties.  A pointer to the new error queue is returned upon success,
 *      or NULL is returned to indicate that the queue could not be created.
 *      This function must be called from passive kernel context with no locks
 *      held that can prevent a sleeping memory allocation from occurring.
 *      errorq_create() will return failure if the queue kstats cannot be
 *      created, or if a soft interrupt handler cannot be registered.
 *
 *      The queue 'name' is a string that is recorded for live and post-mortem
 *      examination by a debugger.  The queue callback 'func' will be invoked
 *      for each error drained from the queue, and will receive the 'private'
 *      pointer as its first argument.  The callback must obey the rules for
 *      callbacks described above.  The queue will have maximum length 'qlen'
 *      and each element will be able to record up to 'eltsize' bytes of data.
 *      The queue's soft interrupt (see errorq_dispatch(), below) will fire
 *      at 'ipl', which should not exceed LOCK_LEVEL.  The queue 'flags' may
 *      include the following flag:
 *
 *      ERRORQ_VITAL    - This queue contains information that is considered
 *         vital to problem diagnosis.  Error queues that are marked vital will
 *         be automatically drained by the panic subsystem prior to printing
 *         the panic messages to the console.
 *
 * void errorq_destroy(errorq);
 *
 *      Destroy the specified error queue.  The queue is drained of any
 *      pending elements and these are logged before errorq_destroy returns.
 *      Once errorq_destroy() begins draining the queue, any simultaneous
 *      calls to dispatch errors will result in the errors being dropped.
 *      The caller must invoke a higher-level abstraction (e.g. disabling
 *      an error interrupt) to ensure that error handling code does not
 *      attempt to dispatch errors to the queue while it is being freed.
 *
 * void errorq_dispatch(errorq, data, len, flag);
 *
 *      Attempt to enqueue the specified error data.  If a free queue element
 *      is available, the data is copied into a free element and placed on a
 *      pending list.  If no free queue element is available, the error is
 *      dropped.  The data length (len) is specified in bytes and should not
 *      exceed the queue's maximum element size.  If the data length is less
 *      than the maximum element size, the remainder of the queue element is
 *      filled with zeroes.  The flag parameter should be one of:
 *
 *      ERRORQ_ASYNC    - Schedule a soft interrupt at the previously specified
 *         IPL to asynchronously drain the queue on behalf of the caller.
 *
 *      ERRORQ_SYNC     - Do not schedule a soft interrupt to drain the queue.
 *         The caller is presumed to be calling errorq_drain() or panic() in
 *         the near future in order to drain the queue and log the error.
 *
 *      The errorq_dispatch() function may be called from any context, subject
 *      to the Platform Considerations described above.
 *
 * void errorq_drain(errorq);
 *
 *      Drain the error queue of all pending errors.  The queue's callback
 *      function is invoked for each error in order from oldest to newest.
 *      This function may be used at or below LOCK_LEVEL or from panic context.
 *
 * errorq_elem_t *errorq_reserve(errorq);
 *
 *	Reserve an error queue element for later processing and dispatching.
 *	The element is returned to the caller who may add error-specific data
 *	to element.  The element is retured to the free pool when either
 *	errorq_commit() is called and the element asynchronously processed
 *	or immediately when errorq_cancel() is called.
 *
 * void errorq_commit(errorq, errorq_elem, flag);
 *
 *	Commit an errorq element (eqep) for dispatching, see
 *	errorq_dispatch().
 *
 * void errorq_cancel(errorq, errorq_elem);
 *
 *	Cancel a pending errorq element reservation.  The errorq element is
 *	returned to the free pool upon cancelation.
 */

#include <sys/errorq_impl.h>
#include <sys/sysmacros.h>
#include <sys/machlock.h>
#include <sys/cmn_err.h>
#include <sys/atomic.h>
#include <sys/systm.h>
#include <sys/kmem.h>
#include <sys/conf.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>
#include <sys/bootconf.h>
#include <sys/spl.h>
#include <sys/dumphdr.h>
#include <sys/compress.h>
#include <sys/time.h>
#include <sys/panic.h>
#include <sys/bitmap.h>
#include <sys/fm/protocol.h>
#include <sys/fm/util.h>

static struct errorq_kstat errorq_kstat_template = {
	{ "dispatched", KSTAT_DATA_UINT64 },
	{ "dropped", KSTAT_DATA_UINT64 },
	{ "logged", KSTAT_DATA_UINT64 },
	{ "reserved", KSTAT_DATA_UINT64 },
	{ "reserve_fail", KSTAT_DATA_UINT64 },
	{ "committed", KSTAT_DATA_UINT64 },
	{ "commit_fail", KSTAT_DATA_UINT64 },
	{ "cancelled", KSTAT_DATA_UINT64 }
};

static uint64_t errorq_lost = 0;
static errorq_t *errorq_list = NULL;
static kmutex_t errorq_lock;
static uint64_t errorq_vitalmin = 5;

static uint_t
errorq_intr(caddr_t eqp)
{
	errorq_drain((errorq_t *)eqp);
	return (DDI_INTR_CLAIMED);
}

/*
 * Create a new error queue with the specified properties and add a software
 * interrupt handler and kstat for it.  This function must be called from
 * passive kernel context with no locks held that can prevent a sleeping
 * memory allocation from occurring.  This function will return NULL if the
 * softint or kstat for this queue cannot be created.
 */
errorq_t *
errorq_create(const char *name, errorq_func_t func, void *private,
    ulong_t qlen, size_t size, uint_t ipl, uint_t flags)
{
	errorq_t *eqp = kmem_alloc(sizeof (errorq_t), KM_SLEEP);
	ddi_iblock_cookie_t ibc = (ddi_iblock_cookie_t)(uintptr_t)ipltospl(ipl);
	dev_info_t *dip = ddi_root_node();

	errorq_elem_t *eep;
	ddi_softintr_t id = NULL;
	caddr_t data;

	ASSERT(qlen != 0 && size != 0);
	ASSERT(ipl > 0 && ipl <= LOCK_LEVEL);

	/*
	 * If a queue is created very early in boot before device tree services
	 * are available, the queue softint handler cannot be created.  We
	 * manually drain these queues and create their softint handlers when
	 * it is safe to do so as part of errorq_init(), below.
	 */
	if (modrootloaded && ddi_add_softintr(dip, DDI_SOFTINT_FIXED, &id,
	    &ibc, NULL, errorq_intr, (caddr_t)eqp) != DDI_SUCCESS) {
		cmn_err(CE_WARN, "errorq_create: failed to register "
		    "IPL %u softint for queue %s", ipl, name);
		kmem_free(eqp, sizeof (errorq_t));
		return (NULL);
	}

	if ((eqp->eq_ksp = kstat_create("unix", 0, name, "errorq",
	    KSTAT_TYPE_NAMED, sizeof (struct errorq_kstat) /
	    sizeof (kstat_named_t), KSTAT_FLAG_VIRTUAL)) == NULL) {
		cmn_err(CE_WARN, "errorq_create: failed to create kstat "
		    "for queue %s", name);
		if (id != NULL)
			ddi_remove_softintr(id);
		kmem_free(eqp, sizeof (errorq_t));
		return (NULL);
	}

	bcopy(&errorq_kstat_template, &eqp->eq_kstat,
	    sizeof (struct errorq_kstat));
	eqp->eq_ksp->ks_data = &eqp->eq_kstat;
	eqp->eq_ksp->ks_private = eqp;
	kstat_install(eqp->eq_ksp);

	(void) strncpy(eqp->eq_name, name, ERRORQ_NAMELEN);
	eqp->eq_name[ERRORQ_NAMELEN] = '\0';
	eqp->eq_func = func;
	eqp->eq_private = private;
	eqp->eq_data = kmem_alloc(qlen * size, KM_SLEEP);
	eqp->eq_qlen = qlen;
	eqp->eq_size = size;
	eqp->eq_ipl = ipl;
	eqp->eq_flags = flags | ERRORQ_ACTIVE;
	eqp->eq_id = id;
	mutex_init(&eqp->eq_lock, NULL, MUTEX_DEFAULT, NULL);
	eqp->eq_elems = kmem_alloc(qlen * sizeof (errorq_elem_t), KM_SLEEP);
	eqp->eq_phead = NULL;
	eqp->eq_ptail = NULL;
	eqp->eq_pend = NULL;
	eqp->eq_dump = NULL;
	eqp->eq_bitmap = kmem_zalloc(BT_SIZEOFMAP(qlen), KM_SLEEP);
	eqp->eq_rotor = 0;

	/*
	 * Iterate over the array of errorq_elem_t structures and set its
	 * data pointer.
	 */
	for (eep = eqp->eq_elems, data = eqp->eq_data; qlen > 1; qlen--) {
		eep->eqe_next = NULL;
		eep->eqe_dump = NULL;
		eep->eqe_prev = NULL;
		eep->eqe_data = data;
		data += size;
		eep++;
	}
	eep->eqe_next = NULL;
	eep->eqe_prev = NULL;
	eep->eqe_data = data;
	eep->eqe_dump = NULL;

	/*
	 * Once the errorq is initialized, add it to the global list of queues,
	 * and then return a pointer to the new queue to the caller.
	 */
	mutex_enter(&errorq_lock);
	eqp->eq_next = errorq_list;
	errorq_list = eqp;
	mutex_exit(&errorq_lock);

	return (eqp);
}

/*
 * Create a new errorq as if by errorq_create(), but set the ERRORQ_NVLIST
 * flag and initialize each element to have the start of its data region used
 * as an errorq_nvelem_t with a nvlist allocator that consumes the data region.
 */
errorq_t *
errorq_nvcreate(const char *name, errorq_func_t func, void *private,
    ulong_t qlen, size_t size, uint_t ipl, uint_t flags)
{
	errorq_t *eqp;
	errorq_elem_t *eep;

	eqp = errorq_create(name, func, private, qlen,
	    size + sizeof (errorq_nvelem_t), ipl, flags | ERRORQ_NVLIST);

	if (eqp == NULL)
		return (NULL);

	mutex_enter(&eqp->eq_lock);

	for (eep = eqp->eq_elems; qlen != 0; eep++, qlen--) {
		errorq_nvelem_t *eqnp = eep->eqe_data;
		eqnp->eqn_buf = (char *)eqnp + sizeof (errorq_nvelem_t);
		eqnp->eqn_nva = fm_nva_xcreate(eqnp->eqn_buf, size);
	}

	mutex_exit(&eqp->eq_lock);
	return (eqp);
}

/*
 * To destroy an error queue, we mark it as disabled and then explicitly drain
 * all pending errors.  Once the drain is complete, we can remove the queue
 * from the global list of queues examined by errorq_panic(), and then free
 * the various queue data structures.  The caller must use some higher-level
 * abstraction (e.g. disabling an error interrupt) to ensure that no one will
 * attempt to enqueue new errors while we are freeing this queue.
 */
void
errorq_destroy(errorq_t *eqp)
{
	errorq_t *p, **pp;
	errorq_elem_t *eep;
	ulong_t i;

	ASSERT(eqp != NULL);
	eqp->eq_flags &= ~ERRORQ_ACTIVE;
	errorq_drain(eqp);

	mutex_enter(&errorq_lock);
	pp = &errorq_list;

	for (p = errorq_list; p != NULL; p = p->eq_next) {
		if (p == eqp) {
			*pp = p->eq_next;
			break;
		}
		pp = &p->eq_next;
	}

	mutex_exit(&errorq_lock);
	ASSERT(p != NULL);

	if (eqp->eq_flags & ERRORQ_NVLIST) {
		for (eep = eqp->eq_elems, i = 0; i < eqp->eq_qlen; i++, eep++) {
			errorq_nvelem_t *eqnp = eep->eqe_data;
			fm_nva_xdestroy(eqnp->eqn_nva);
		}
	}

	mutex_destroy(&eqp->eq_lock);
	kstat_delete(eqp->eq_ksp);

	if (eqp->eq_id != NULL)
		ddi_remove_softintr(eqp->eq_id);

	kmem_free(eqp->eq_elems, eqp->eq_qlen * sizeof (errorq_elem_t));
	kmem_free(eqp->eq_bitmap, BT_SIZEOFMAP(eqp->eq_qlen));
	kmem_free(eqp->eq_data, eqp->eq_qlen * eqp->eq_size);

	kmem_free(eqp, sizeof (errorq_t));
}

/*
 * private version of bt_availbit which makes a best-efforts attempt
 * at allocating in a round-robin fashion in order to facilitate post-mortem
 * diagnosis.
 */
static index_t
errorq_availbit(ulong_t *bitmap, size_t nbits, index_t curindex)
{
	ulong_t bit, maxbit, bx;
	index_t rval, nextindex = curindex + 1;
	index_t nextword = nextindex >> BT_ULSHIFT;
	ulong_t nextbitindex = nextindex & BT_ULMASK;
	index_t maxindex = nbits - 1;
	index_t maxword = maxindex >> BT_ULSHIFT;
	ulong_t maxbitindex = maxindex & BT_ULMASK;

	/*
	 * First check if there are still some bits remaining in the current
	 * word, and see if any of those are available. We need to do this by
	 * hand as the bt_availbit() function always starts at the beginning
	 * of a word.
	 */
	if (nextindex <= maxindex && nextbitindex != 0) {
		maxbit = (nextword == maxword) ? maxbitindex : BT_ULMASK;
		for (bx = 0, bit = 1; bx <= maxbit; bx++, bit <<= 1)
			if (bx >= nextbitindex && !(bitmap[nextword] & bit))
				return ((nextword << BT_ULSHIFT) + bx);
		nextword++;
	}
	/*
	 * Now check if there are any words remaining before the end of the
	 * bitmap. Use bt_availbit() to find any free bits.
	 */
	if (nextword <= maxword)
		if ((rval = bt_availbit(&bitmap[nextword],
		    nbits - (nextword << BT_ULSHIFT))) != -1)
			return ((nextword << BT_ULSHIFT) + rval);
	/*
	 * Finally loop back to the start and look for any free bits starting
	 * from the beginning of the bitmap to the current rotor position.
	 */
	return (bt_availbit(bitmap, nextindex));
}

/*
 * Dispatch a new error into the queue for later processing.  The specified
 * data buffer is copied into a preallocated queue element.  If 'len' is
 * smaller than the queue element size, the remainder of the queue element is
 * filled with zeroes.  This function may be called from any context subject
 * to the Platform Considerations described above.
 */
void
errorq_dispatch(errorq_t *eqp, const void *data, size_t len, uint_t flag)
{
	errorq_elem_t *eep, *old;

	if (eqp == NULL || !(eqp->eq_flags & ERRORQ_ACTIVE)) {
		atomic_inc_64(&errorq_lost);
		return; /* drop error if queue is uninitialized or disabled */
	}

	for (;;) {
		int i, rval;

		if ((i = errorq_availbit(eqp->eq_bitmap, eqp->eq_qlen,
		    eqp->eq_rotor)) == -1) {
			atomic_inc_64(&eqp->eq_kstat.eqk_dropped.value.ui64);
			return;
		}
		BT_ATOMIC_SET_EXCL(eqp->eq_bitmap, i, rval);
		if (rval == 0) {
			eqp->eq_rotor = i;
			eep = &eqp->eq_elems[i];
			break;
		}
	}

	ASSERT(len <= eqp->eq_size);
	bcopy(data, eep->eqe_data, MIN(eqp->eq_size, len));

	if (len < eqp->eq_size)
		bzero((caddr_t)eep->eqe_data + len, eqp->eq_size - len);

	for (;;) {
		old = eqp->eq_pend;
		eep->eqe_prev = old;
		membar_producer();

		if (atomic_cas_ptr(&eqp->eq_pend, old, eep) == old)
			break;
	}

	atomic_inc_64(&eqp->eq_kstat.eqk_dispatched.value.ui64);

	if (flag == ERRORQ_ASYNC && eqp->eq_id != NULL)
		ddi_trigger_softintr(eqp->eq_id);
}

/*
 * Drain the specified error queue by calling eq_func() for each pending error.
 * This function must be called at or below LOCK_LEVEL or from panic context.
 * In order to synchronize with other attempts to drain the queue, we acquire
 * the adaptive eq_lock, blocking other consumers.  Once this lock is held,
 * we must use compare-and-swap to move the pending list to the processing
 * list and to return elements to the free pool in order to synchronize
 * with producers, who do not acquire any locks and only use atomic set/clear.
 *
 * An additional constraint on this function is that if the system panics
 * while this function is running, the panic code must be able to detect and
 * handle all intermediate states and correctly dequeue all errors.  The
 * errorq_panic() function below will be used for detecting and handling
 * these intermediate states.  The comments in errorq_drain() below explain
 * how we make sure each intermediate state is distinct and consistent.
 */
void
errorq_drain(errorq_t *eqp)
{
	errorq_elem_t *eep, *dep;

	ASSERT(eqp != NULL);
	mutex_enter(&eqp->eq_lock);

	/*
	 * If there are one or more pending errors, set eq_ptail to point to
	 * the first element on the pending list and then attempt to compare-
	 * and-swap NULL to the pending list.  We use membar_producer() to
	 * make sure that eq_ptail will be visible to errorq_panic() below
	 * before the pending list is NULLed out.  This section is labeled
	 * case (1) for errorq_panic, below.  If eq_ptail is not yet set (1A)
	 * eq_pend has all the pending errors.  If atomic_cas_ptr fails or
	 * has not been called yet (1B), eq_pend still has all the pending
	 * errors.  If atomic_cas_ptr succeeds (1C), eq_ptail has all the
	 * pending errors.
	 */
	while ((eep = eqp->eq_pend) != NULL) {
		eqp->eq_ptail = eep;
		membar_producer();

		if (atomic_cas_ptr(&eqp->eq_pend, eep, NULL) == eep)
			break;
	}

	/*
	 * If no errors were pending, assert that eq_ptail is set to NULL,
	 * drop the consumer lock, and return without doing anything.
	 */
	if (eep == NULL) {
		ASSERT(eqp->eq_ptail == NULL);
		mutex_exit(&eqp->eq_lock);
		return;
	}

	/*
	 * Now iterate from eq_ptail (a.k.a. eep, the newest error) to the
	 * oldest error, setting the eqe_next pointer so that we can iterate
	 * over the errors from oldest to newest.  We use membar_producer()
	 * to make sure that these stores are visible before we set eq_phead.
	 * If we panic before, during, or just after this loop (case 2),
	 * errorq_panic() will simply redo this work, as described below.
	 */
	for (eep->eqe_next = NULL; eep->eqe_prev != NULL; eep = eep->eqe_prev)
		eep->eqe_prev->eqe_next = eep;
	membar_producer();

	/*
	 * Now set eq_phead to the head of the processing list (the oldest
	 * error) and issue another membar_producer() to make sure that
	 * eq_phead is seen as non-NULL before we clear eq_ptail.  If we panic
	 * after eq_phead is set (case 3), we will detect and log these errors
	 * in errorq_panic(), as described below.
	 */
	eqp->eq_phead = eep;
	membar_producer();

	eqp->eq_ptail = NULL;
	membar_producer();

	/*
	 * If we enter from errorq_panic_drain(), we may already have
	 * errorq elements on the dump list.  Find the tail of
	 * the list ready for append.
	 */
	if (panicstr && (dep = eqp->eq_dump) != NULL) {
		while (dep->eqe_dump != NULL)
			dep = dep->eqe_dump;
	}

	/*
	 * Now iterate over the processing list from oldest (eq_phead) to
	 * newest and log each error.  Once an error is logged, we use
	 * atomic clear to return it to the free pool.  If we panic before,
	 * during, or after calling eq_func() (case 4), the error will still be
	 * found on eq_phead and will be logged in errorq_panic below.
	 */

	while ((eep = eqp->eq_phead) != NULL) {
		eqp->eq_func(eqp->eq_private, eep->eqe_data, eep);
		eqp->eq_kstat.eqk_logged.value.ui64++;

		eqp->eq_phead = eep->eqe_next;
		membar_producer();

		eep->eqe_next = NULL;

		/*
		 * On panic, we add the element to the dump list for each
		 * nvlist errorq.  Elements are stored oldest to newest.
		 * Then continue, so we don't free and subsequently overwrite
		 * any elements which we've put on the dump queue.
		 */
		if (panicstr && (eqp->eq_flags & ERRORQ_NVLIST)) {
			if (eqp->eq_dump == NULL)
				dep = eqp->eq_dump = eep;
			else
				dep = dep->eqe_dump = eep;
			membar_producer();
			continue;
		}

		eep->eqe_prev = NULL;
		BT_ATOMIC_CLEAR(eqp->eq_bitmap, eep - eqp->eq_elems);
	}

	mutex_exit(&eqp->eq_lock);
}

/*
 * Now that device tree services are available, set up the soft interrupt
 * handlers for any queues that were created early in boot.  We then
 * manually drain these queues to report any pending early errors.
 */
void
errorq_init(void)
{
	dev_info_t *dip = ddi_root_node();
	ddi_softintr_t id;
	errorq_t *eqp;

	ASSERT(modrootloaded != 0);
	ASSERT(dip != NULL);

	mutex_enter(&errorq_lock);

	for (eqp = errorq_list; eqp != NULL; eqp = eqp->eq_next) {
		ddi_iblock_cookie_t ibc =
		    (ddi_iblock_cookie_t)(uintptr_t)ipltospl(eqp->eq_ipl);

		if (eqp->eq_id != NULL)
			continue; /* softint already initialized */

		if (ddi_add_softintr(dip, DDI_SOFTINT_FIXED, &id, &ibc, NULL,
		    errorq_intr, (caddr_t)eqp) != DDI_SUCCESS) {
			panic("errorq_init: failed to register IPL %u softint "
			    "for queue %s", eqp->eq_ipl, eqp->eq_name);
		}

		eqp->eq_id = id;
		errorq_drain(eqp);
	}

	mutex_exit(&errorq_lock);
}

/*
 * This function is designed to be called from panic context only, and
 * therefore does not need to acquire errorq_lock when iterating over
 * errorq_list.  This function must be called no more than once for each
 * 'what' value (if you change this then review the manipulation of 'dep'.
 */
static uint64_t
errorq_panic_drain(uint_t what)
{
	errorq_elem_t *eep, *nep, *dep;
	errorq_t *eqp;
	uint64_t loggedtmp;
	uint64_t logged = 0;

	for (eqp = errorq_list; eqp != NULL; eqp = eqp->eq_next) {
		if ((eqp->eq_flags & (ERRORQ_VITAL | ERRORQ_NVLIST)) != what)
			continue; /* do not drain this queue on this pass */

		loggedtmp = eqp->eq_kstat.eqk_logged.value.ui64;

		/*
		 * In case (1B) above, eq_ptail may be set but the
		 * atomic_cas_ptr may not have been executed yet or may have
		 * failed.  Either way, we must log errors in chronological
		 * order.  So we search the pending list for the error
		 * pointed to by eq_ptail.  If it is found, we know that all
		 * subsequent errors are also still on the pending list, so
		 * just NULL out eq_ptail and let errorq_drain(), below,
		 * take care of the logging.
		 */
		for (eep = eqp->eq_pend; eep != NULL; eep = eep->eqe_prev) {
			if (eep == eqp->eq_ptail) {
				ASSERT(eqp->eq_phead == NULL);
				eqp->eq_ptail = NULL;
				break;
			}
		}

		/*
		 * In cases (1C) and (2) above, eq_ptail will be set to the
		 * newest error on the processing list but eq_phead will still
		 * be NULL.  We set the eqe_next pointers so we can iterate
		 * over the processing list in order from oldest error to the
		 * newest error.  We then set eq_phead to point to the oldest
		 * error and fall into the for-loop below.
		 */
		if (eqp->eq_phead == NULL && (eep = eqp->eq_ptail) != NULL) {
			for (eep->eqe_next = NULL; eep->eqe_prev != NULL;
			    eep = eep->eqe_prev)
				eep->eqe_prev->eqe_next = eep;

			eqp->eq_phead = eep;
			eqp->eq_ptail = NULL;
		}

		/*
		 * In cases (3) and (4) above (or after case (1C/2) handling),
		 * eq_phead will be set to the oldest error on the processing
		 * list.  We log each error and return it to the free pool.
		 *
		 * Unlike errorq_drain(), we don't need to worry about updating
		 * eq_phead because errorq_panic() will be called at most once.
		 * However, we must use atomic_cas_ptr to update the
		 * freelist in case errors are still being enqueued during
		 * panic.
		 */
		for (eep = eqp->eq_phead; eep != NULL; eep = nep) {
			eqp->eq_func(eqp->eq_private, eep->eqe_data, eep);
			eqp->eq_kstat.eqk_logged.value.ui64++;

			nep = eep->eqe_next;
			eep->eqe_next = NULL;

			/*
			 * On panic, we add the element to the dump list for
			 * each nvlist errorq, stored oldest to newest. Then
			 * continue, so we don't free and subsequently overwrite
			 * any elements which we've put on the dump queue.
			 */
			if (eqp->eq_flags & ERRORQ_NVLIST) {
				if (eqp->eq_dump == NULL)
					dep = eqp->eq_dump = eep;
				else
					dep = dep->eqe_dump = eep;
				membar_producer();
				continue;
			}

			eep->eqe_prev = NULL;
			BT_ATOMIC_CLEAR(eqp->eq_bitmap, eep - eqp->eq_elems);
		}

		/*
		 * Now go ahead and drain any other errors on the pending list.
		 * This call transparently handles case (1A) above, as well as
		 * any other errors that were dispatched after errorq_drain()
		 * completed its first compare-and-swap.
		 */
		errorq_drain(eqp);

		logged += eqp->eq_kstat.eqk_logged.value.ui64 - loggedtmp;
	}
	return (logged);
}

/*
 * Drain all error queues - called only from panic context.  Some drain
 * functions may enqueue errors to ERRORQ_NVLIST error queues so that
 * they may be written out in the panic dump - so ERRORQ_NVLIST queues
 * must be drained last.  Drain ERRORQ_VITAL queues before nonvital queues
 * so that vital errors get to fill the ERRORQ_NVLIST queues first, and
 * do not drain the nonvital queues if there are many vital errors.
 */
void
errorq_panic(void)
{
	ASSERT(panicstr != NULL);

	if (errorq_panic_drain(ERRORQ_VITAL) <= errorq_vitalmin)
		(void) errorq_panic_drain(0);
	(void) errorq_panic_drain(ERRORQ_VITAL | ERRORQ_NVLIST);
	(void) errorq_panic_drain(ERRORQ_NVLIST);
}

/*
 * Reserve an error queue element for later processing and dispatching.  The
 * element is returned to the caller who may add error-specific data to
 * element.  The element is retured to the free pool when either
 * errorq_commit() is called and the element asynchronously processed
 * or immediately when errorq_cancel() is called.
 */
errorq_elem_t *
errorq_reserve(errorq_t *eqp)
{
	errorq_elem_t *eqep;

	if (eqp == NULL || !(eqp->eq_flags & ERRORQ_ACTIVE)) {
		atomic_inc_64(&errorq_lost);
		return (NULL);
	}

	for (;;) {
		int i, rval;

		if ((i = errorq_availbit(eqp->eq_bitmap, eqp->eq_qlen,
		    eqp->eq_rotor)) == -1) {
			atomic_inc_64(&eqp->eq_kstat.eqk_dropped.value.ui64);
			return (NULL);
		}
		BT_ATOMIC_SET_EXCL(eqp->eq_bitmap, i, rval);
		if (rval == 0) {
			eqp->eq_rotor = i;
			eqep = &eqp->eq_elems[i];
			break;
		}
	}

	if (eqp->eq_flags & ERRORQ_NVLIST) {
		errorq_nvelem_t *eqnp = eqep->eqe_data;
		nv_alloc_reset(eqnp->eqn_nva);
		eqnp->eqn_nvl = fm_nvlist_create(eqnp->eqn_nva);
	}

	atomic_inc_64(&eqp->eq_kstat.eqk_reserved.value.ui64);
	return (eqep);
}

/*
 * Commit an errorq element (eqep) for dispatching.
 * This function may be called from any context subject
 * to the Platform Considerations described above.
 */
void
errorq_commit(errorq_t *eqp, errorq_elem_t *eqep, uint_t flag)
{
	errorq_elem_t *old;

	if (eqep == NULL || !(eqp->eq_flags & ERRORQ_ACTIVE)) {
		atomic_inc_64(&eqp->eq_kstat.eqk_commit_fail.value.ui64);
		return;
	}

	for (;;) {
		old = eqp->eq_pend;
		eqep->eqe_prev = old;
		membar_producer();

		if (atomic_cas_ptr(&eqp->eq_pend, old, eqep) == old)
			break;
	}

	atomic_inc_64(&eqp->eq_kstat.eqk_committed.value.ui64);

	if (flag == ERRORQ_ASYNC && eqp->eq_id != NULL)
		ddi_trigger_softintr(eqp->eq_id);
}

/*
 * Cancel an errorq element reservation by returning the specified element
 * to the free pool.  Duplicate or invalid frees are not supported.
 */
void
errorq_cancel(errorq_t *eqp, errorq_elem_t *eqep)
{
	if (eqep == NULL || !(eqp->eq_flags & ERRORQ_ACTIVE))
		return;

	BT_ATOMIC_CLEAR(eqp->eq_bitmap, eqep - eqp->eq_elems);

	atomic_inc_64(&eqp->eq_kstat.eqk_cancelled.value.ui64);
}

/*
 * Write elements on the dump list of each nvlist errorq to the dump device.
 * Upon reboot, fmd(1M) will extract and replay them for diagnosis.
 */
void
errorq_dump(void)
{
	errorq_elem_t *eep;
	errorq_t *eqp;

	if (ereport_dumpbuf == NULL)
		return; /* reboot or panic before errorq is even set up */

	for (eqp = errorq_list; eqp != NULL; eqp = eqp->eq_next) {
		if (!(eqp->eq_flags & ERRORQ_NVLIST) ||
		    !(eqp->eq_flags & ERRORQ_ACTIVE))
			continue; /* do not dump this queue on panic */

		for (eep = eqp->eq_dump; eep != NULL; eep = eep->eqe_dump) {
			errorq_nvelem_t *eqnp = eep->eqe_data;
			size_t len = 0;
			erpt_dump_t ed;
			int err;

			(void) nvlist_size(eqnp->eqn_nvl,
			    &len, NV_ENCODE_NATIVE);

			if (len > ereport_dumplen || len == 0) {
				cmn_err(CE_WARN, "%s: unable to save error "
				    "report %p due to size %lu\n",
				    eqp->eq_name, (void *)eep, len);
				continue;
			}

			if ((err = nvlist_pack(eqnp->eqn_nvl,
			    (char **)&ereport_dumpbuf, &ereport_dumplen,
			    NV_ENCODE_NATIVE, KM_NOSLEEP)) != 0) {
				cmn_err(CE_WARN, "%s: unable to save error "
				    "report %p due to pack error %d\n",
				    eqp->eq_name, (void *)eep, err);
				continue;
			}

			ed.ed_magic = ERPT_MAGIC;
			ed.ed_chksum = checksum32(ereport_dumpbuf, len);
			ed.ed_size = (uint32_t)len;
			ed.ed_pad = 0;
			ed.ed_hrt_nsec = 0;
			ed.ed_hrt_base = panic_hrtime;
			ed.ed_tod_base.sec = panic_hrestime.tv_sec;
			ed.ed_tod_base.nsec = panic_hrestime.tv_nsec;

			dumpvp_write(&ed, sizeof (ed));
			dumpvp_write(ereport_dumpbuf, len);
		}
	}
}

nvlist_t *
errorq_elem_nvl(errorq_t *eqp, const errorq_elem_t *eqep)
{
	errorq_nvelem_t *eqnp = eqep->eqe_data;

	ASSERT(eqp->eq_flags & ERRORQ_ACTIVE && eqp->eq_flags & ERRORQ_NVLIST);

	return (eqnp->eqn_nvl);
}

nv_alloc_t *
errorq_elem_nva(errorq_t *eqp, const errorq_elem_t *eqep)
{
	errorq_nvelem_t *eqnp = eqep->eqe_data;

	ASSERT(eqp->eq_flags & ERRORQ_ACTIVE && eqp->eq_flags & ERRORQ_NVLIST);

	return (eqnp->eqn_nva);
}

/*
 * Reserve a new element and duplicate the data of the original into it.
 */
void *
errorq_elem_dup(errorq_t *eqp, const errorq_elem_t *eqep, errorq_elem_t **neqep)
{
	ASSERT(eqp->eq_flags & ERRORQ_ACTIVE);
	ASSERT(!(eqp->eq_flags & ERRORQ_NVLIST));

	if ((*neqep = errorq_reserve(eqp)) == NULL)
		return (NULL);

	bcopy(eqep->eqe_data, (*neqep)->eqe_data, eqp->eq_size);
	return ((*neqep)->eqe_data);
}