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