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