osfmk/kern/simple_lock.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  * Copyright (C) 1998 Apple Computer
  24  * All Rights Reserved
  25  */
  26 /*
  27  * @OSF_COPYRIGHT@
  28  */
  29 /*
  30  * Mach Operating System
  31  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
  32  * All Rights Reserved.
  33  *
  34  * Permission to use, copy, modify and distribute this software and its
  35  * documentation is hereby granted, provided that both the copyright
  36  * notice and this permission notice appear in all copies of the
  37  * software, derivative works or modified versions, and any portions
  38  * thereof, and that both notices appear in supporting documentation.
  39  *
  40  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  41  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  42  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  43  *
  44  * Carnegie Mellon requests users of this software to return to
  45  *
  46  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  47  *  School of Computer Science
  48  *  Carnegie Mellon University
  49  *  Pittsburgh PA 15213-3890
  50  *
  51  * any improvements or extensions that they make and grant Carnegie Mellon
  52  * the rights to redistribute these changes.
  53  */
  54 /*
  55  *      File:   kern/simple_lock.h (derived from kern/lock.h)
  56  *      Author: Avadis Tevanian, Jr., Michael Wayne Young
  57  *      Date:   1985
  58  *
  59  *      Simple Locking primitives definitions
  60  */
  61
  62 #ifndef _SIMPLE_LOCK_H_
  63 #define _SIMPLE_LOCK_H_
  64
  65 /*
  66  * Configuration variables:
  67  *
  68  *
  69  *      MACH_LDEBUG:    record pc and thread of callers, turn on
  70  *                      all lock debugging.
  71  *
  72  *
  73  *      ETAP:           The Event Trace Analysis Package (ETAP) monitors
  74  *                      and records micro-kernel lock behavior and general
  75  *                      kernel events.  ETAP supports two levels of
  76  *                      tracing for locks:
  77  *                              - cumulative (ETAP_LOCK_ACCUMULATE)
  78  *                              - monitored  (ETAP_LOCK_MONITOR)
  79  *
  80  *                      Note: If either level of tracing is configured then
  81  *                            ETAP_LOCK_TRACE is automatically defined to
  82  *                            equal one.
  83  *
  84  *                      Several macros are added throughout the lock code to
  85  *                      allow for convenient configuration.
  86  */
  87
  88 #include <mach/boolean.h>
  89 #include <kern/kern_types.h>
  90
  91 #include <kern/simple_lock_types.h>
  92 #include <mach/etap_events.h>
  93 #include <mach/etap.h>
  94
  95 /*
  96  *      The Mach lock package exports the following simple lock abstractions:
  97  *
  98  *      Lock Type  Properties
  99  *      hw_lock    lowest level hardware abstraction; atomic,
 100  *                 non-blocking, mutual exclusion; supports pre-emption
 101  *      usimple    non-blocking spinning lock, available in all
 102  *                 kernel configurations; may be used from thread
 103  *                 and interrupt contexts; supports debugging,
 104  *                 statistics and pre-emption
 105  *      simple     non-blocking spinning lock, intended for SMP
 106  *                 synchronization (vanishes on a uniprocessor);
 107  *                 supports debugging, statistics and pre-emption
 108  *
 109  *      NOTES TO IMPLEMENTORS:  there are essentially two versions
 110  *      of the lock package.  One is portable, written in C, and
 111  *      supports all of the various flavors of debugging, statistics,
 112  *      uni- versus multi-processor, pre-emption, etc.  The "other"
 113  *      is whatever set of lock routines is provided by machine-dependent
 114  *      code.  Presumably, the machine-dependent package is heavily
 115  *      optimized and meant for production kernels.
 116  *
 117  *      We encourage implementors to focus on highly-efficient,
 118  *      production implementations of machine-dependent lock code,
 119  *      and use the portable lock package for everything else.
 120  */
 121
 122 #ifdef MACH_KERNEL_PRIVATE
 123 /*
 124  *      Mach always initializes locks, even those statically
 125  *      allocated.
 126  *
 127  *      The conditional acquisition call, hw_lock_try,
 128  *      must return non-zero on success and zero on failure.
 129  *
 130  *      The hw_lock_held operation returns non-zero if the
 131  *      lock is set, zero if the lock is clear.  This operation
 132  *      should be implemented using an ordinary memory read,
 133  *      rather than a special atomic instruction, allowing
 134  *      a processor to spin in cache waiting for the lock to
 135  *      be released without chewing up bus cycles.
 136  */
 137 extern void                     hw_lock_init(hw_lock_t);
 138 extern void                     hw_lock_lock(hw_lock_t);
 139 extern void                     hw_lock_unlock(hw_lock_t);
 140 extern unsigned int             hw_lock_to(hw_lock_t, unsigned int);
 141 extern unsigned int             hw_lock_try(hw_lock_t);
 142 extern unsigned int             hw_lock_held(hw_lock_t);
 143 #endif /* MACH_KERNEL_PRIVATE */
 144
 145 /*
 146  * Machine dependent atomic ops.  Probably should be in their own header.
 147  */
 148 extern unsigned int             hw_lock_bit(unsigned int *, unsigned int, unsigned int);
 149 extern unsigned int             hw_cpu_sync(unsigned int *, unsigned int);
 150 extern unsigned int             hw_cpu_wcng(unsigned int *, unsigned int, unsigned int);
 151 extern unsigned int             hw_lock_mbits(unsigned int *, unsigned int, unsigned int,
 152         unsigned int, unsigned int);
 153 void                            hw_unlock_bit(unsigned int *, unsigned int);
 154 extern int                      hw_atomic_add(int *area, int inc);
 155 extern int                      hw_atomic_sub(int *area, int dec);
 156 extern unsigned int             hw_compare_and_store(unsigned int oldValue, unsigned int newValue, unsigned int *area);
 157 extern void                     hw_queue_atomic(unsigned int *anchor, unsigned int *elem, unsigned int disp);
 158 extern void                     hw_queue_atomic_list(unsigned int *anchor, unsigned int *first, unsigned int *last, unsigned int disp);
 159 extern unsigned int             *hw_dequeue_atomic(unsigned int *anchor, unsigned int disp);
 160
 161
 162 /*
 163  *      The remaining locking constructs may have two versions.
 164  *      One version is machine-independent, built in C on top of the
 165  *      hw_lock construct.  This version supports production, debugging
 166  *      and statistics configurations and is portable across architectures.
 167  *
 168  *      Any particular port may override some or all of the portable
 169  *      lock package for whatever reason -- usually efficiency.
 170  *
 171  *      The direct use of hw_locks by machine-independent Mach code
 172  *      should be rare; the preferred spinning lock is the simple_lock
 173  *      (see below).
 174  */
 175
 176 /*
 177  *      A "simple" spin lock, providing non-blocking mutual
 178  *      exclusion and conditional acquisition.
 179  *
 180  *      The usimple_lock exists even in uniprocessor configurations.
 181  *      A data structure is always allocated for it and the following
 182  *      operations are always defined:
 183  *
 184  *              usimple_lock_init       lock initialization (mandatory!)
 185  *              usimple_lock            lock acquisition
 186  *              usimple_unlock          lock release
 187  *              usimple_lock_try        conditional lock acquisition;
 188  *                                      non-zero means success
 189  *      Simple lock DEBUG interfaces
 190  *              usimple_lock_held       verify lock already held by me
 191  *              usimple_lock_none_held  verify no usimple locks are held
 192  *
 193  *      The usimple_lock may be used for synchronization between
 194  *      thread context and interrupt context, or between a uniprocessor
 195  *      and an intelligent device.  Obviously, it may also be used for
 196  *      multiprocessor synchronization.  Its use should be rare; the
 197  *      simple_lock is the preferred spinning lock (see below).
 198  *
 199  *      The usimple_lock supports optional lock debugging and statistics.
 200  *
 201  *      Normally, we expect the usimple_lock data structure to be
 202  *      defined here, with its operations implemented in an efficient,
 203  *      machine-dependent way.  However, any implementation may choose
 204  *      to rely on a C-based, portable  version of the usimple_lock for
 205  *      debugging, statistics, and/or tracing.  Three hooks are used in
 206  *      the portable lock package to allow the machine-dependent package
 207  *      to override some or all of the portable package's features.
 208  *
 209  *      The usimple_lock also handles pre-emption.  Lock acquisition
 210  *      implies disabling pre-emption, while lock release implies
 211  *      re-enabling pre-emption.  Conditional lock acquisition does
 212  *      not assume success:  on success, pre-emption is disabled
 213  *      but on failure the pre-emption state remains the same as
 214  *      the pre-emption state before the acquisition attempt.
 215  */
 216
 217 /*
 218  *      Each usimple_lock has a type, used for debugging and
 219  *      statistics.  This type may safely be ignored in a
 220  *      production configuration.
 221  *
 222  *      The conditional acquisition call, usimple_lock_try,
 223  *      must return non-zero on success and zero on failure.
 224  */
 225 extern void             usimple_lock_init(usimple_lock_t,etap_event_t);
 226 extern void             usimple_lock(usimple_lock_t);
 227 extern void             usimple_unlock(usimple_lock_t);
 228 extern unsigned int     usimple_lock_try(usimple_lock_t);
 229 extern void             usimple_lock_held(usimple_lock_t);
 230 extern void             usimple_lock_none_held(void);
 231
 232
 233 /*
 234  *      Upon the usimple_lock we define the simple_lock, which
 235  *      exists for SMP configurations.  These locks aren't needed
 236  *      in a uniprocessor configuration, so compile-time tricks
 237  *      make them disappear when NCPUS==1.  (For debugging purposes,
 238  *      however, they can be enabled even on a uniprocessor.)  This
 239  *      should be the "most popular" spinning lock; the usimple_lock
 240  *      and hw_lock should only be used in rare cases.
 241  *
 242  *      IMPORTANT:  simple_locks that may be shared between interrupt
 243  *      and thread context must have their use coordinated with spl.
 244  *      The spl level must alway be the same when acquiring the lock.
 245  *      Otherwise, deadlock may result.
 246  */
 247
 248 #if MACH_KERNEL_PRIVATE
 249 #include <cpus.h>
 250 #include <mach_ldebug.h>
 251
 252 #if     NCPUS == 1 && !ETAP_LOCK_TRACE && !USLOCK_DEBUG
 253 /*
 254  *      MACH_RT is a very special case:  in the case that the
 255  *      machine-dependent lock package hasn't taken responsibility
 256  *      but there is no other reason to turn on locks, if MACH_RT
 257  *      is turned on locks denote critical, non-preemptable points
 258  *      in the code.
 259  *
 260  *      Otherwise, simple_locks may be layered directly on top of
 261  *      usimple_locks.
 262  *
 263  *      N.B.  The reason that simple_lock_try may be assumed to
 264  *      succeed under MACH_RT is that the definition only is used
 265  *      when NCPUS==1 AND because simple_locks shared between thread
 266  *      and interrupt context are always acquired with elevated spl.
 267  *      Thus, it is never possible to be interrupted in a dangerous
 268  *      way while holding a simple_lock.
 269  */
 270 /*
 271  *      for locks and there is no other apparent reason to turn them on.
 272  *      So make them disappear.
 273  */
 274 #define simple_lock_init(l,t)
 275 #define simple_lock(l)          disable_preemption()
 276 #define simple_unlock(l)        enable_preemption()
 277 #define simple_lock_try(l)      (disable_preemption(), 1)
 278 #define simple_lock_addr(lock)  ((simple_lock_t)0)
 279 #define __slock_held_func__(l)  preemption_is_disabled()
 280 #endif  /* NCPUS == 1 && !ETAP_LOCK_TRACE && !USLOCK_DEBUG */
 281
 282 #if     ETAP_LOCK_TRACE
 283 extern  void    simple_lock_no_trace(simple_lock_t l);
 284 extern  int     simple_lock_try_no_trace(simple_lock_t l);
 285 extern  void    simple_unlock_no_trace(simple_lock_t l);
 286 #endif  /* ETAP_LOCK_TRACE */
 287
 288 #endif /* MACH_KERNEL_PRIVATE */
 289
 290 /*
 291  * If we got to here and we still don't have simple_lock_init
 292  * defined, then we must either be outside the osfmk component,
 293  * running on a true SMP, or need debug.
 294  */
 295 #if !defined(simple_lock_init)
 296 #define simple_lock_init(l,t)   usimple_lock_init(l,t)
 297 #define simple_lock(l)          usimple_lock(l)
 298 #define simple_unlock(l)        usimple_unlock(l)
 299 #define simple_lock_try(l)      usimple_lock_try(l)
 300 #define simple_lock_addr(l)     (&(l))
 301 #define __slock_held_func__(l)  usimple_lock_held(l)
 302 #endif / * !defined(simple_lock_init) */
 303
 304 #if     USLOCK_DEBUG
 305 /*
 306  *      Debug-time only:
 307  *              + verify that usimple_lock is already held by caller
 308  *              + verify that usimple_lock is NOT held by caller
 309  *              + verify that current processor owns no usimple_locks
 310  *
 311  *      We do not provide a simple_lock_NOT_held function because
 312  *      it's impossible to verify when only MACH_RT is turned on.
 313  *      In that situation, only preemption is enabled/disabled
 314  *      around lock use, and it's impossible to tell which lock
 315  *      acquisition caused preemption to be disabled.  However,
 316  *      note that it's still valid to use check_simple_locks
 317  *      when only MACH_RT is turned on -- no locks should be
 318  *      held, hence preemption should be enabled.
 319  *      Actually, the above isn't strictly true, as explicit calls
 320  *      to disable_preemption() need to be accounted for.
 321  */
 322 #define simple_lock_held(l)     __slock_held_func__(l)
 323 #define check_simple_locks()    usimple_lock_none_held()
 324 #else   /* USLOCK_DEBUG */
 325 #define simple_lock_held(l)
 326 #define check_simple_locks()
 327 #endif  /* USLOCK_DEBUG */
 328
 329 #endif /*!_SIMPLE_LOCK_H_*/