1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 /*
22  * Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
23  * Use is subject to license terms.
24  */
25 
26 #ifndef _SYS_USB_USBSER_USBSER_RSEQ_H
27 #define	_SYS_USB_USBSER_USBSER_RSEQ_H
28 
29 
30 /*
31  * Reversible sequence (rseq) is a data-driven mechanism to execute several
32  * subfunctions, called steps, and subsequently execute them in the reverse
33  * order - these opposite actions are further referred to as 'do' and 'undo'.
34  * If one of the intermediate steps fails, the previously executed steps are
35  * undone in reverse order. Debugging facilities are also provided.
36  *
37  * rseq is primarily aimed to simplify multistep driver attach()/detach()
38  * implementations, where each step can potentially fail and undoing previous
39  * ones typically involve either goto's or bit-fields (indicating what has been
40  * done so far).
41  */
42 
43 #include <sys/types.h>
44 #include <sys/note.h>
45 
46 #ifdef	__cplusplus
47 extern "C" {
48 #endif
49 
50 typedef struct rseq rseq_t;
51 
52 /*
53  * rseq function type
54  *
55  * uintptr_t is used to accomodate both integer and pointer argument types
56  */
57 typedef uintptr_t (*rseq_func_t)(uintptr_t);
58 
59 /* step callback is called after each step */
60 typedef int (*rseq_cb_t)(rseq_t *rseq, int num, uintptr_t arg);
61 
62 /* values returned by step callback */
63 enum {
64 	RSEQ_OK		= 0,	/* continue to execute steps */
65 	RSEQ_UNDO	= 1,	/* rseq_do() only: step failed, undo all */
66 	RSEQ_ABORT	= 2	/* stop rseq execution and return immediately */
67 };
68 
69 /*
70  * rseq step
71  */
72 typedef struct rseq_step {
73 	rseq_func_t	s_func;		/* step function; ignored if NULL */
74 	char		*s_name;	/* step name string */
75 	rseq_cb_t	s_cb;		/* step callback; NULL is equivalent */
76 					/* to a callback returning RSEQ_OK */
77 	uintptr_t	s_rval;		/* s_func's return value */
78 } rseq_step_t;
79 
80 /*
81  * rseq entry
82  */
83 struct rseq {
84 	rseq_step_t	r_do;	/* do step */
85 	rseq_step_t	r_undo;	/* undo step */
86 };
87 
88 _NOTE(SCHEME_PROTECTS_DATA("one per call", rseq rseq_step))
89 
90 /*
91  * rseq_do(), rseq_undo()
92  *
93  * Arguments:
94  *	rseq	- array of rseq entries;
95  *	num	- number of entries in the array;
96  *	arg	- argument passed to the step functions;
97  *	flags	- should be 0, no flags defined yet;
98  *
99  * Return values:
100  *	If an intermediate step failed, value returned by respective callback.
101  *	Otherwise RSEQ_OK.
102  */
103 int rseq_do(rseq_t *rseq, int num, uintptr_t arg, int flags);
104 int rseq_undo(rseq_t *rseq, int num, uintptr_t arg, int flags);
105 
106 
107 /*
108  * To use rseq debugging, rseq_do_debug() and rseq_undo_debug() are provided.
109  * They are similar to their non-debug counterparts, except for additional
110  * arguments: scenario type and scenario arguments.
111  */
112 int rseq_do_debug(rseq_t *rseq, int num, uintptr_t arg, int flags,
113 		int scenario, uintptr_t sarg1, uintptr_t sarg2);
114 int rseq_undo_debug(rseq_t *rseq, int num, uintptr_t arg, int flags,
115 		int scenario, uintptr_t sarg1, uintptr_t sarg2);
116 
117 /*
118  * Debug scenarios
119  */
120 enum {
121 	/*
122 	 * simulate step failure: instead of executing step number sarg2,
123 	 * rseq will set s_rval to sarg1 and invoke the step callback.
124 	 */
125 	RSEQ_DBG_FAIL_ONE,
126 	/*
127 	 * same as RSEQ_DBG_FAIL_ONE, but step number is chosen randomly.
128 	 */
129 	RSEQ_DBG_FAIL_ONE_RANDOM,
130 	/*
131 	 * simulate each step failure one-by-one, to cover all failure paths.
132 	 * in pseudo code:
133 	 *
134 	 * for i = 0..num
135 	 *	RSEQ_DBG_FAIL_ONE of the i-th step;
136 	 *
137 	 */
138 	RSEQ_DBG_FAIL_ONEBYONE
139 };
140 
141 
142 /*
143  * convenience macros for rseq definition
144  */
145 #define	RSEQT(func, cb)	{ (rseq_func_t)(uintptr_t)(func), #func, \
146 	(rseq_cb_t)(uintptr_t)(cb), 0 }
147 #define	RSEQE(f1, cb1, f2, cb2) { RSEQT(f1, cb1), RSEQT(f2, cb2) }
148 
149 /*
150  * Example:
151  *
152  * #define MY_RSEQ(f1, f2) RSEQE(f1, my_do_cb, f2, my_undo_cb)
153  *
154  * rseq_t my_rseq[] = {
155  *	MY_RSEQ(my_first_do, my_first_undo),
156  *	MY_RSEQ(my_second_do, my_second_undo),
157  *	...
158  * };
159  *
160  * int my_do_cb(rseq_t *rseq, int num)
161  *	{ return (rseq[num].rval == 0) ? RSEQ_OK : RSEQ_UNDO; }
162  *
163  * int my_undo_cb(rseq_t *rseq, int num)
164  *	{ return RSEQ_OK; }
165  */
166 
167 #ifdef	__cplusplus
168 }
169 #endif
170 
171 #endif	/* _SYS_USB_USBSER_USBSER_RSEQ_H */
172