sys/cddl/compat/opensolaris/sys/callb.h

   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  * $FreeBSD$
  23  */
  24 /*
  25  * Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
  26  * Use is subject to license terms.
  27  */
  28
  29 #ifndef _SYS_CALLB_H
  30 #define _SYS_CALLB_H
  31
  32 #pragma ident   "@(#)callb.h    1.29    05/06/23 SMI"
  33
  34 #include <sys/kcondvar.h>
  35
  36 #ifdef  __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /*
  41  * definitions of callback classes (c_class)
  42  *
  43  * Callbacks belong in the same class if (1) their callback routines
  44  * do the same kind of processing (ideally, using the same callback function)
  45  * and (2) they can/should be executed at the same time in a cpr
  46  * suspend/resume operation.
  47  *
  48  * Note: The DAEMON class, in particular, is for stopping kernel threads
  49  * and nothing else.  The CALLB_* macros below should be used to deal
  50  * with kernel threads, and the callback function should be callb_generic_cpr.
  51  * Another idiosyncrasy of the DAEMON class is that if a suspend operation
  52  * fails, some of the callback functions may be called with the RESUME
  53  * code which were never called with SUSPEND.  Not a problem currently,
  54  * but see bug 4201851.
  55  */
  56 #define CB_CL_CPR_DAEMON        0
  57 #define CB_CL_CPR_VM            1
  58 #define CB_CL_CPR_CALLOUT       2
  59 #define CB_CL_CPR_OBP           3
  60 #define CB_CL_CPR_FB            4
  61 #define CB_CL_PANIC             5
  62 #define CB_CL_CPR_RPC           6
  63 #define CB_CL_CPR_PROMPRINTF    7
  64 #define CB_CL_UADMIN            8
  65 #define CB_CL_CPR_PM            9
  66 #define CB_CL_HALT              10
  67 #define CB_CL_CPR_DMA           11
  68 #define CB_CL_CPR_POST_USER     12
  69 #define CB_CL_UADMIN_PRE_VFS    13
  70 #define CB_CL_MDBOOT            CB_CL_UADMIN
  71 #define CB_CL_ENTER_DEBUGGER    14
  72 #define CB_CL_CPR_POST_KERNEL   15
  73 #define NCBCLASS                16 /* CHANGE ME if classes are added/removed */
  74
  75 /*
  76  * CB_CL_CPR_DAEMON class specific definitions are given below:
  77  */
  78
  79 /*
  80  * code for CPR callb_execute_class
  81  */
  82 #define CB_CODE_CPR_CHKPT       0
  83 #define CB_CODE_CPR_RESUME      1
  84
  85 typedef void *          callb_id_t;
  86 /*
  87  * Per kernel thread structure for CPR daemon callbacks.
  88  * Must be protected by either a existing lock in the daemon or
  89  * a new lock created for such a purpose.
  90  */
  91 typedef struct callb_cpr {
  92         kmutex_t        *cc_lockp;      /* lock to protect this struct */
  93         char            cc_events;      /* various events for CPR */
  94         callb_id_t      cc_id;          /* callb id address */
  95         kcondvar_t      cc_callb_cv;    /* cv for callback waiting */
  96         kcondvar_t      cc_stop_cv;     /* cv to checkpoint block */
  97 } callb_cpr_t;
  98
  99 /*
 100  * cc_events definitions
 101  */
 102 #define CALLB_CPR_START         1       /* a checkpoint request's started */
 103 #define CALLB_CPR_SAFE          2       /* thread is safe for CPR */
 104 #define CALLB_CPR_ALWAYS_SAFE   4       /* thread is ALWAYS safe for CPR */
 105
 106 /*
 107  * Used when checking that all kernel threads are stopped.
 108  */
 109 #define CALLB_MAX_RETRY         3       /* when waiting for kthread to sleep */
 110 #define CALLB_THREAD_DELAY      10      /* ticks allowed to reach sleep */
 111 #define CPR_KTHREAD_TIMEOUT_SEC 90      /* secs before callback times out -- */
 112                                         /* due to pwr mgmt of disks, make -- */
 113                                         /* big enough for worst spinup time */
 114
 115 #ifdef  _KERNEL
 116 /*
 117  *
 118  * CALLB_CPR_INIT macro is used by kernel threads to add their entry to
 119  * the callback table and perform other initialization.  It automatically
 120  * adds the thread as being in the callback class CB_CL_CPR_DAEMON.
 121  *
 122  *      cp    - ptr to the callb_cpr_t structure for this kernel thread
 123  *
 124  *      lockp - pointer to mutex protecting the callb_cpr_t stuct
 125  *
 126  *      func  - pointer to the callback function for this kernel thread.
 127  *              It has the prototype boolean_t <func>(void *arg, int code)
 128  *              where: arg      - ptr to the callb_cpr_t structure
 129  *                     code     - not used for this type of callback
 130  *              returns: B_TRUE if successful; B_FALSE if unsuccessful.
 131  *
 132  *      name  - a string giving the name of the kernel thread
 133  *
 134  * Note: lockp is the lock to protect the callb_cpr_t (cp) structure
 135  * later on.  No lock held is needed for this initialization.
 136  */
 137 #define CALLB_CPR_INIT(cp, lockp, func, name)   {                       \
 138                 strlcpy(curthread->td_name, (name),                     \
 139                     sizeof(curthread->td_name));                        \
 140                 strlcpy(curthread->td_proc->p_comm, (name),             \
 141                     sizeof(curthread->td_proc->p_comm));                \
 142                 bzero((caddr_t)(cp), sizeof (callb_cpr_t));             \
 143                 (cp)->cc_lockp = lockp;                                 \
 144                 (cp)->cc_id = callb_add(func, (void *)(cp),             \
 145                         CB_CL_CPR_DAEMON, name);                        \
 146         }
 147
 148 #ifndef __lock_lint
 149 #define CALLB_CPR_ASSERT(cp)    ASSERT(MUTEX_HELD((cp)->cc_lockp));
 150 #else
 151 #define CALLB_CPR_ASSERT(cp)
 152 #endif
 153 /*
 154  * Some threads (like the idle threads) do not adhere to the callback
 155  * protocol and are always considered safe.  Such threads must never exit.
 156  * They register their presence by calling this macro during their
 157  * initialization.
 158  *
 159  * Args:
 160  *      t       - thread pointer of the client kernel thread
 161  *      name    - a string giving the name of the kernel thread
 162  */
 163 #define CALLB_CPR_INIT_SAFE(t, name) {                                  \
 164                 (void) callb_add_thread(callb_generic_cpr_safe,         \
 165                 (void *) &callb_cprinfo_safe, CB_CL_CPR_DAEMON,         \
 166                     name, t);                                           \
 167         }
 168 /*
 169  * The lock to protect cp's content must be held before
 170  * calling the following two macros.
 171  *
 172  * Any code region between CALLB_CPR_SAFE_BEGIN and CALLB_CPR_SAFE_END
 173  * is safe for checkpoint/resume.
 174  */
 175 #define CALLB_CPR_SAFE_BEGIN(cp) {                      \
 176                 CALLB_CPR_ASSERT(cp)                    \
 177                 (cp)->cc_events |= CALLB_CPR_SAFE;      \
 178                 if ((cp)->cc_events & CALLB_CPR_START)  \
 179                         cv_signal(&(cp)->cc_callb_cv);  \
 180         }
 181 #define CALLB_CPR_SAFE_END(cp, lockp) {                         \
 182                 CALLB_CPR_ASSERT(cp)                            \
 183                 while ((cp)->cc_events & CALLB_CPR_START)       \
 184                         cv_wait(&(cp)->cc_stop_cv, lockp);      \
 185                 (cp)->cc_events &= ~CALLB_CPR_SAFE;             \
 186         }
 187 /*
 188  * cv_destroy is nop right now but may be needed in the future.
 189  */
 190 #define CALLB_CPR_EXIT(cp) {                            \
 191                 CALLB_CPR_ASSERT(cp)                    \
 192                 (cp)->cc_events |= CALLB_CPR_SAFE;      \
 193                 if ((cp)->cc_events & CALLB_CPR_START)  \
 194                         cv_signal(&(cp)->cc_callb_cv);  \
 195                 mutex_exit((cp)->cc_lockp);             \
 196                 (void) callb_delete((cp)->cc_id);       \
 197                 cv_destroy(&(cp)->cc_callb_cv);         \
 198                 cv_destroy(&(cp)->cc_stop_cv);          \
 199         }
 200
 201 extern callb_cpr_t callb_cprinfo_safe;
 202 extern callb_id_t callb_add(boolean_t  (*)(void *, int), void *, int, char *);
 203 extern callb_id_t callb_add_thread(boolean_t (*)(void *, int),
 204     void *, int, char *, kthread_id_t);
 205 extern int      callb_delete(callb_id_t);
 206 extern void     callb_execute(callb_id_t, int);
 207 extern void     *callb_execute_class(int, int);
 208 extern boolean_t callb_generic_cpr(void *, int);
 209 extern boolean_t callb_generic_cpr_safe(void *, int);
 210 extern boolean_t callb_is_stopped(kthread_id_t, caddr_t *);
 211 extern void     callb_lock_table(void);
 212 extern void     callb_unlock_table(void);
 213 #endif
 214
 215 #ifdef  __cplusplus
 216 }
 217 #endif
 218
 219 #endif  /* _SYS_CALLB_H */