17c478bd9Sstevel@tonic-gate /* 27c478bd9Sstevel@tonic-gate * CDDL HEADER START 37c478bd9Sstevel@tonic-gate * 47c478bd9Sstevel@tonic-gate * The contents of this file are subject to the terms of the 5d29f5a71Szhigang lu - Sun Microsystems - Beijing China * Common Development and Distribution License (the "License"). 6d29f5a71Szhigang lu - Sun Microsystems - Beijing China * You may not use this file except in compliance with the License. 77c478bd9Sstevel@tonic-gate * 87c478bd9Sstevel@tonic-gate * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 97c478bd9Sstevel@tonic-gate * or http://www.opensolaris.org/os/licensing. 107c478bd9Sstevel@tonic-gate * See the License for the specific language governing permissions 117c478bd9Sstevel@tonic-gate * and limitations under the License. 127c478bd9Sstevel@tonic-gate * 137c478bd9Sstevel@tonic-gate * When distributing Covered Code, include this CDDL HEADER in each 147c478bd9Sstevel@tonic-gate * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 157c478bd9Sstevel@tonic-gate * If applicable, add the following below this CDDL HEADER, with the 167c478bd9Sstevel@tonic-gate * fields enclosed by brackets "[]" replaced with your own identifying 177c478bd9Sstevel@tonic-gate * information: Portions Copyright [yyyy] [name of copyright owner] 187c478bd9Sstevel@tonic-gate * 197c478bd9Sstevel@tonic-gate * CDDL HEADER END 207c478bd9Sstevel@tonic-gate */ 217c478bd9Sstevel@tonic-gate /* 22d29f5a71Szhigang lu - Sun Microsystems - Beijing China * Copyright 2008 Sun Microsystems, Inc. All rights reserved. 237c478bd9Sstevel@tonic-gate * Use is subject to license terms. 247c478bd9Sstevel@tonic-gate */ 257c478bd9Sstevel@tonic-gate 267c478bd9Sstevel@tonic-gate #ifndef _SYS_USB_USBSER_USBSER_RSEQ_H 277c478bd9Sstevel@tonic-gate #define _SYS_USB_USBSER_USBSER_RSEQ_H 287c478bd9Sstevel@tonic-gate 297c478bd9Sstevel@tonic-gate 307c478bd9Sstevel@tonic-gate /* 317c478bd9Sstevel@tonic-gate * Reversible sequence (rseq) is a data-driven mechanism to execute several 327c478bd9Sstevel@tonic-gate * subfunctions, called steps, and subsequently execute them in the reverse 337c478bd9Sstevel@tonic-gate * order - these opposite actions are further referred to as 'do' and 'undo'. 347c478bd9Sstevel@tonic-gate * If one of the intermediate steps fails, the previously executed steps are 357c478bd9Sstevel@tonic-gate * undone in reverse order. Debugging facilities are also provided. 367c478bd9Sstevel@tonic-gate * 377c478bd9Sstevel@tonic-gate * rseq is primarily aimed to simplify multistep driver attach()/detach() 387c478bd9Sstevel@tonic-gate * implementations, where each step can potentially fail and undoing previous 397c478bd9Sstevel@tonic-gate * ones typically involve either goto's or bit-fields (indicating what has been 407c478bd9Sstevel@tonic-gate * done so far). 417c478bd9Sstevel@tonic-gate */ 427c478bd9Sstevel@tonic-gate 437c478bd9Sstevel@tonic-gate #include <sys/types.h> 447c478bd9Sstevel@tonic-gate #include <sys/note.h> 457c478bd9Sstevel@tonic-gate 467c478bd9Sstevel@tonic-gate #ifdef __cplusplus 477c478bd9Sstevel@tonic-gate extern "C" { 487c478bd9Sstevel@tonic-gate #endif 497c478bd9Sstevel@tonic-gate 507c478bd9Sstevel@tonic-gate typedef struct rseq rseq_t; 517c478bd9Sstevel@tonic-gate 527c478bd9Sstevel@tonic-gate /* 537c478bd9Sstevel@tonic-gate * rseq function type 547c478bd9Sstevel@tonic-gate * 557c478bd9Sstevel@tonic-gate * uintptr_t is used to accomodate both integer and pointer argument types 567c478bd9Sstevel@tonic-gate */ 577c478bd9Sstevel@tonic-gate typedef uintptr_t (*rseq_func_t)(uintptr_t); 587c478bd9Sstevel@tonic-gate 597c478bd9Sstevel@tonic-gate /* step callback is called after each step */ 607c478bd9Sstevel@tonic-gate typedef int (*rseq_cb_t)(rseq_t *rseq, int num, uintptr_t arg); 617c478bd9Sstevel@tonic-gate 627c478bd9Sstevel@tonic-gate /* values returned by step callback */ 637c478bd9Sstevel@tonic-gate enum { 647c478bd9Sstevel@tonic-gate RSEQ_OK = 0, /* continue to execute steps */ 657c478bd9Sstevel@tonic-gate RSEQ_UNDO = 1, /* rseq_do() only: step failed, undo all */ 667c478bd9Sstevel@tonic-gate RSEQ_ABORT = 2 /* stop rseq execution and return immediately */ 677c478bd9Sstevel@tonic-gate }; 687c478bd9Sstevel@tonic-gate 697c478bd9Sstevel@tonic-gate /* 707c478bd9Sstevel@tonic-gate * rseq step 717c478bd9Sstevel@tonic-gate */ 727c478bd9Sstevel@tonic-gate typedef struct rseq_step { 737c478bd9Sstevel@tonic-gate rseq_func_t s_func; /* step function; ignored if NULL */ 747c478bd9Sstevel@tonic-gate char *s_name; /* step name string */ 757c478bd9Sstevel@tonic-gate rseq_cb_t s_cb; /* step callback; NULL is equivalent */ 767c478bd9Sstevel@tonic-gate /* to a callback returning RSEQ_OK */ 777c478bd9Sstevel@tonic-gate uintptr_t s_rval; /* s_func's return value */ 787c478bd9Sstevel@tonic-gate } rseq_step_t; 797c478bd9Sstevel@tonic-gate 807c478bd9Sstevel@tonic-gate /* 817c478bd9Sstevel@tonic-gate * rseq entry 827c478bd9Sstevel@tonic-gate */ 837c478bd9Sstevel@tonic-gate struct rseq { 847c478bd9Sstevel@tonic-gate rseq_step_t r_do; /* do step */ 857c478bd9Sstevel@tonic-gate rseq_step_t r_undo; /* undo step */ 867c478bd9Sstevel@tonic-gate }; 877c478bd9Sstevel@tonic-gate 887c478bd9Sstevel@tonic-gate _NOTE(SCHEME_PROTECTS_DATA("one per call", rseq rseq_step)) 897c478bd9Sstevel@tonic-gate 907c478bd9Sstevel@tonic-gate /* 917c478bd9Sstevel@tonic-gate * rseq_do(), rseq_undo() 927c478bd9Sstevel@tonic-gate * 937c478bd9Sstevel@tonic-gate * Arguments: 947c478bd9Sstevel@tonic-gate * rseq - array of rseq entries; 957c478bd9Sstevel@tonic-gate * num - number of entries in the array; 967c478bd9Sstevel@tonic-gate * arg - argument passed to the step functions; 977c478bd9Sstevel@tonic-gate * flags - should be 0, no flags defined yet; 987c478bd9Sstevel@tonic-gate * 997c478bd9Sstevel@tonic-gate * Return values: 1007c478bd9Sstevel@tonic-gate * If an intermediate step failed, value returned by respective callback. 1017c478bd9Sstevel@tonic-gate * Otherwise RSEQ_OK. 1027c478bd9Sstevel@tonic-gate */ 1037c478bd9Sstevel@tonic-gate int rseq_do(rseq_t *rseq, int num, uintptr_t arg, int flags); 1047c478bd9Sstevel@tonic-gate int rseq_undo(rseq_t *rseq, int num, uintptr_t arg, int flags); 1057c478bd9Sstevel@tonic-gate 1067c478bd9Sstevel@tonic-gate 1077c478bd9Sstevel@tonic-gate /* 1087c478bd9Sstevel@tonic-gate * To use rseq debugging, rseq_do_debug() and rseq_undo_debug() are provided. 1097c478bd9Sstevel@tonic-gate * They are similar to their non-debug counterparts, except for additional 1107c478bd9Sstevel@tonic-gate * arguments: scenario type and scenario arguments. 1117c478bd9Sstevel@tonic-gate */ 1127c478bd9Sstevel@tonic-gate int rseq_do_debug(rseq_t *rseq, int num, uintptr_t arg, int flags, 1137c478bd9Sstevel@tonic-gate int scenario, uintptr_t sarg1, uintptr_t sarg2); 1147c478bd9Sstevel@tonic-gate int rseq_undo_debug(rseq_t *rseq, int num, uintptr_t arg, int flags, 1157c478bd9Sstevel@tonic-gate int scenario, uintptr_t sarg1, uintptr_t sarg2); 1167c478bd9Sstevel@tonic-gate 1177c478bd9Sstevel@tonic-gate /* 1187c478bd9Sstevel@tonic-gate * Debug scenarios 1197c478bd9Sstevel@tonic-gate */ 1207c478bd9Sstevel@tonic-gate enum { 1217c478bd9Sstevel@tonic-gate /* 1227c478bd9Sstevel@tonic-gate * simulate step failure: instead of executing step number sarg2, 1237c478bd9Sstevel@tonic-gate * rseq will set s_rval to sarg1 and invoke the step callback. 1247c478bd9Sstevel@tonic-gate */ 1257c478bd9Sstevel@tonic-gate RSEQ_DBG_FAIL_ONE, 1267c478bd9Sstevel@tonic-gate /* 1277c478bd9Sstevel@tonic-gate * same as RSEQ_DBG_FAIL_ONE, but step number is chosen randomly. 1287c478bd9Sstevel@tonic-gate */ 1297c478bd9Sstevel@tonic-gate RSEQ_DBG_FAIL_ONE_RANDOM, 1307c478bd9Sstevel@tonic-gate /* 1317c478bd9Sstevel@tonic-gate * simulate each step failure one-by-one, to cover all failure paths. 1327c478bd9Sstevel@tonic-gate * in pseudo code: 1337c478bd9Sstevel@tonic-gate * 1347c478bd9Sstevel@tonic-gate * for i = 0..num 1357c478bd9Sstevel@tonic-gate * RSEQ_DBG_FAIL_ONE of the i-th step; 1367c478bd9Sstevel@tonic-gate * 1377c478bd9Sstevel@tonic-gate */ 1387c478bd9Sstevel@tonic-gate RSEQ_DBG_FAIL_ONEBYONE 1397c478bd9Sstevel@tonic-gate }; 1407c478bd9Sstevel@tonic-gate 1417c478bd9Sstevel@tonic-gate 1427c478bd9Sstevel@tonic-gate /* 1437c478bd9Sstevel@tonic-gate * convenience macros for rseq definition 1447c478bd9Sstevel@tonic-gate */ 145*b79609a5SToomas Soome #define RSEQT(func, cb) { (rseq_func_t)(uintptr_t)(func), #func, \ 146*b79609a5SToomas Soome (rseq_cb_t)(uintptr_t)(cb), 0 } 1477c478bd9Sstevel@tonic-gate #define RSEQE(f1, cb1, f2, cb2) { RSEQT(f1, cb1), RSEQT(f2, cb2) } 1487c478bd9Sstevel@tonic-gate 1497c478bd9Sstevel@tonic-gate /* 1507c478bd9Sstevel@tonic-gate * Example: 1517c478bd9Sstevel@tonic-gate * 1527c478bd9Sstevel@tonic-gate * #define MY_RSEQ(f1, f2) RSEQE(f1, my_do_cb, f2, my_undo_cb) 1537c478bd9Sstevel@tonic-gate * 1547c478bd9Sstevel@tonic-gate * rseq_t my_rseq[] = { 1557c478bd9Sstevel@tonic-gate * MY_RSEQ(my_first_do, my_first_undo), 1567c478bd9Sstevel@tonic-gate * MY_RSEQ(my_second_do, my_second_undo), 1577c478bd9Sstevel@tonic-gate * ... 1587c478bd9Sstevel@tonic-gate * }; 1597c478bd9Sstevel@tonic-gate * 1607c478bd9Sstevel@tonic-gate * int my_do_cb(rseq_t *rseq, int num) 161*b79609a5SToomas Soome * { return (rseq[num].rval == 0) ? RSEQ_OK : RSEQ_UNDO; } 1627c478bd9Sstevel@tonic-gate * 1637c478bd9Sstevel@tonic-gate * int my_undo_cb(rseq_t *rseq, int num) 1647c478bd9Sstevel@tonic-gate * { return RSEQ_OK; } 1657c478bd9Sstevel@tonic-gate */ 1667c478bd9Sstevel@tonic-gate 1677c478bd9Sstevel@tonic-gate #ifdef __cplusplus 1687c478bd9Sstevel@tonic-gate } 1697c478bd9Sstevel@tonic-gate #endif 1707c478bd9Sstevel@tonic-gate 1717c478bd9Sstevel@tonic-gate #endif /* _SYS_USB_USBSER_USBSER_RSEQ_H */ 172