/*
 * 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 2008 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

#ifndef _SYS_USB_USBSER_USBSER_RSEQ_H
#define _SYS_USB_USBSER_USBSER_RSEQ_H


/*
 * Reversible sequence (rseq) is a data-driven mechanism to execute several
 * subfunctions, called steps, and subsequently execute them in the reverse
 * order - these opposite actions are further referred to as 'do' and 'undo'.
 * If one of the intermediate steps fails, the previously executed steps are
 * undone in reverse order. Debugging facilities are also provided.
 *
 * rseq is primarily aimed to simplify multistep driver attach()/detach()
 * implementations, where each step can potentially fail and undoing previous
 * ones typically involve either goto's or bit-fields (indicating what has been
 * done so far).
 */

#include <sys/types.h>
#include <sys/note.h>

#ifdef  __cplusplus
extern "C" {
#endif

typedef struct rseq rseq_t;

/*
 * rseq function type
 *
 * uintptr_t is used to accomodate both integer and pointer argument types
 */
typedef uintptr_t (*rseq_func_t)(uintptr_t);

/* step callback is called after each step */
typedef int (*rseq_cb_t)(rseq_t *rseq, int num, uintptr_t arg);

/* values returned by step callback */
enum {
        RSEQ_OK         = 0,    /* continue to execute steps */
        RSEQ_UNDO       = 1,    /* rseq_do() only: step failed, undo all */
        RSEQ_ABORT      = 2     /* stop rseq execution and return immediately */
};

/*
 * rseq step
 */
typedef struct rseq_step {
        rseq_func_t     s_func;         /* step function; ignored if NULL */
        char            *s_name;        /* step name string */
        rseq_cb_t       s_cb;           /* step callback; NULL is equivalent */
                                        /* to a callback returning RSEQ_OK */
        uintptr_t       s_rval;         /* s_func's return value */
} rseq_step_t;

/*
 * rseq entry
 */
struct rseq {
        rseq_step_t     r_do;   /* do step */
        rseq_step_t     r_undo; /* undo step */
};

_NOTE(SCHEME_PROTECTS_DATA("one per call", rseq rseq_step))

/*
 * rseq_do(), rseq_undo()
 *
 * Arguments:
 *      rseq    - array of rseq entries;
 *      num     - number of entries in the array;
 *      arg     - argument passed to the step functions;
 *      flags   - should be 0, no flags defined yet;
 *
 * Return values:
 *      If an intermediate step failed, value returned by respective callback.
 *      Otherwise RSEQ_OK.
 */
int rseq_do(rseq_t *rseq, int num, uintptr_t arg, int flags);
int rseq_undo(rseq_t *rseq, int num, uintptr_t arg, int flags);


/*
 * To use rseq debugging, rseq_do_debug() and rseq_undo_debug() are provided.
 * They are similar to their non-debug counterparts, except for additional
 * arguments: scenario type and scenario arguments.
 */
int rseq_do_debug(rseq_t *rseq, int num, uintptr_t arg, int flags,
                int scenario, uintptr_t sarg1, uintptr_t sarg2);
int rseq_undo_debug(rseq_t *rseq, int num, uintptr_t arg, int flags,
                int scenario, uintptr_t sarg1, uintptr_t sarg2);

/*
 * Debug scenarios
 */
enum {
        /*
         * simulate step failure: instead of executing step number sarg2,
         * rseq will set s_rval to sarg1 and invoke the step callback.
         */
        RSEQ_DBG_FAIL_ONE,
        /*
         * same as RSEQ_DBG_FAIL_ONE, but step number is chosen randomly.
         */
        RSEQ_DBG_FAIL_ONE_RANDOM,
        /*
         * simulate each step failure one-by-one, to cover all failure paths.
         * in pseudo code:
         *
         * for i = 0..num
         *      RSEQ_DBG_FAIL_ONE of the i-th step;
         *
         */
        RSEQ_DBG_FAIL_ONEBYONE
};


/*
 * convenience macros for rseq definition
 */
#define RSEQT(func, cb) { (rseq_func_t)(uintptr_t)(func), #func, \
        (rseq_cb_t)(uintptr_t)(cb), 0 }
#define RSEQE(f1, cb1, f2, cb2) { RSEQT(f1, cb1), RSEQT(f2, cb2) }

/*
 * Example:
 *
 * #define MY_RSEQ(f1, f2) RSEQE(f1, my_do_cb, f2, my_undo_cb)
 *
 * rseq_t my_rseq[] = {
 *      MY_RSEQ(my_first_do, my_first_undo),
 *      MY_RSEQ(my_second_do, my_second_undo),
 *      ...
 * };
 *
 * int my_do_cb(rseq_t *rseq, int num)
 *      { return (rseq[num].rval == 0) ? RSEQ_OK : RSEQ_UNDO; }
 *
 * int my_undo_cb(rseq_t *rseq, int num)
 *      { return RSEQ_OK; }
 */

#ifdef  __cplusplus
}
#endif

#endif  /* _SYS_USB_USBSER_USBSER_RSEQ_H */