osfmk/kern/simple_lock_types.h

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*
  26  * @OSF_COPYRIGHT@
  27  */
  28 /*
  29  * Mach Operating System
  30  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
  31  * All Rights Reserved.
  32  *
  33  * Permission to use, copy, modify and distribute this software and its
  34  * documentation is hereby granted, provided that both the copyright
  35  * notice and this permission notice appear in all copies of the
  36  * software, derivative works or modified versions, and any portions
  37  * thereof, and that both notices appear in supporting documentation.
  38  *
  39  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  40  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  41  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  42  *
  43  * Carnegie Mellon requests users of this software to return to
  44  *
  45  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  46  *  School of Computer Science
  47  *  Carnegie Mellon University
  48  *  Pittsburgh PA 15213-3890
  49  *
  50  * any improvements or extensions that they make and grant Carnegie Mellon
  51  * the rights to redistribute these changes.
  52  */
  53 /*
  54  *      File:   kern/simple_lock_types.h
  55  *      Author: Avadis Tevanian, Jr., Michael Wayne Young
  56  *      Date:   1985
  57  *
  58  *      Simple lock data type definitions
  59  */
  60
  61 #ifndef _SIMPLE_LOCK_TYPES_H_
  62 #define _SIMPLE_LOCK_TYPES_H_
  63
  64 #include <mach/boolean.h>
  65 #include <kern/kern_types.h>
  66 #include <machine/hw_lock_types.h>
  67
  68 /*
  69  *      The Mach lock package exports the following simple lock abstractions:
  70  *
  71  *      Lock Type  Properties
  72  *      hw_lock    lowest level hardware abstraction; atomic,
  73  *                 non-blocking, mutual exclusion; supports pre-emption
  74  *      usimple    non-blocking spinning lock, available in all
  75  *                 kernel configurations; may be used from thread
  76  *                 and interrupt contexts; supports debugging,
  77  *                 statistics and pre-emption
  78  *      simple     non-blocking spinning lock, intended for SMP
  79  *                 synchronization (vanishes on a uniprocessor);
  80  *                 supports debugging, statistics and pre-emption
  81  *
  82  *      NOTES TO IMPLEMENTORS:  there are essentially two versions
  83  *      of the lock package.  One is portable, written in C, and
  84  *      supports all of the various flavors of debugging, statistics,
  85  *      uni- versus multi-processor, pre-emption, etc.  The "other"
  86  *      is whatever set of lock routines is provided by machine-dependent
  87  *      code.  Presumably, the machine-dependent package is heavily
  88  *      optimized and meant for production kernels.
  89  *
  90  *      We encourage implementors to focus on highly-efficient,
  91  *      production implementations of machine-dependent lock code,
  92  *      and use the portable lock package for everything else.
  93  */
  94
  95 /*
  96  *      All of the remaining locking constructs may have two versions.
  97  *      One version is machine-independent, built in C on top of the
  98  *      hw_lock construct.  This version supports production, debugging
  99  *      and statistics configurations and is portable across architectures.
 100  *
 101  *      Any particular port may override some or all of the portable
 102  *      lock package for whatever reason -- usually efficiency.
 103  *
 104  *      The direct use of hw_locks by machine-independent Mach code
 105  *      should be rare; the preferred spinning lock is the simple_lock
 106  *      (see below).
 107  */
 108
 109 /*
 110  *      A "simple" spin lock, providing non-blocking mutual
 111  *      exclusion and conditional acquisition.
 112  *
 113  *      The usimple_lock exists even in uniprocessor configurations.
 114  *      A data structure is always allocated for it.
 115  *
 116  *      The usimple_lock may be used for synchronization between
 117  *      thread context and interrupt context, or between a uniprocessor
 118  *      and an intelligent device.  Obviously, it may also be used for
 119  *      multiprocessor synchronization.  Its use should be rare; the
 120  *      simple_lock is the preferred spinning lock (see below).
 121  *
 122  *      The usimple_lock supports optional lock debugging and statistics.
 123  *
 124  *      The usimple_lock may be inlined or optimized in ways that
 125  *      depend on the particular machine architecture and kernel
 126  *      build configuration; e.g., processor type, number of CPUs,
 127  *      production v. debugging.
 128  *
 129  *      Normally, we expect the usimple_lock data structure to be
 130  *      defined here, with its operations implemented in an efficient,
 131  *      machine-dependent way.  However, any implementation may choose
 132  *      to rely on a C-based, portable  version of the usimple_lock for
 133  *      debugging, statistics, and/or tracing.  Three hooks are used in
 134  *      the portable lock package to allow the machine-dependent package
 135  *      to override some or all of the portable package's features.
 136  *
 137  *
 138  *      The usimple_lock data structure
 139  *      can be overriden in a machine-dependent way by defining
 140  *      LOCK_USIMPLE_DATA, although we expect this to be unnecessary.
 141  *      (Note that if you choose to override LOCK_USIMPLE_DATA, you'd
 142  *      better also be prepared to override LOCK_USIMPLE_CALLS.)
 143  *
 144  *      The usimple_lock also handles pre-emption.  Lock acquisition
 145  *      implies disabling pre-emption, while lock release implies
 146  *      re-enabling pre-emption.  Conditional lock acquisition does
 147  *      not assume success:  on success, pre-emption is disabled
 148  *      but on failure the pre-emption state remains the same as
 149  *      the pre-emption state before the acquisition attempt.
 150  */
 151
 152 #ifndef USIMPLE_LOCK_DATA
 153 #define USLOCK_DEBUG_DATA 1 /* Always allocate lock debug data for now */
 154 #if     USLOCK_DEBUG_DATA
 155 /*
 156  *
 157  *
 158  *      This structure records additional information about lock state
 159  *      and recent operations.  The data are carefully organized so that
 160  *      some portions of it can be examined BEFORE actually acquiring
 161  *      the lock -- for instance, the lock_thread field, to detect an
 162  *      attempt to acquire a lock already owned by the calling thread.
 163  *      All *updates* to this structure are governed by the lock to which
 164  *      this structure belongs.
 165  *
 166  *      Note cache consistency dependency:  being able to examine some
 167  *      of the fields in this structure without first acquiring a lock
 168  *      implies strongly-ordered cache coherency OR release consistency.
 169  *      Perhaps needless to say, acquisition consistency may not suffice.
 170  *      However, it's hard to imagine a scenario using acquisition
 171  *      consistency that results in using stale data from this structure.
 172  *      It would be necessary for the thread manipulating the lock to
 173  *      switch to another processor without first executing any instructions
 174  *      that would cause the needed consistency updates; basically, without
 175  *      taking a lock.  Not possible in this kernel!
 176  */
 177 typedef struct uslock_debug {
 178         void            *lock_pc;       /* pc where lock operation began    */
 179         void            *lock_thread;   /* thread that acquired lock */
 180         unsigned long   duration[2];
 181         unsigned short  state;
 182         unsigned char   lock_cpu;
 183         void            *unlock_thread; /* last thread to release lock */
 184         unsigned char   unlock_cpu;
 185         void            *unlock_pc;     /* pc where lock operation ended    */
 186 } uslock_debug;
 187 #endif  /* USLOCK_DEBUG_DATA */
 188
 189 typedef struct slock {
 190         hw_lock_data_t  interlock;      /* must be first... see lock.c */
 191 #if     USLOCK_DEBUG_DATA
 192         unsigned short  lock_type;      /* must be second... see lock.c */
 193 #define USLOCK_TAG      0x5353
 194         uslock_debug    debug;
 195 #endif  /* USLOCK_DEBUG_DATA */
 196 } usimple_lock_data_t, *usimple_lock_t;
 197
 198 #define USIMPLE_LOCK_NULL       ((usimple_lock_t) 0)
 199
 200 #endif  /* USIMPLE_LOCK_DATA */
 201
 202 /*
 203  *      Upon the usimple_lock we define the simple_lock, which
 204  *      exists for SMP configurations.  These locks aren't needed
 205  *      in a uniprocessor configuration, so compile-time tricks
 206  *      make them disappear when NCPUS==1.  (For debugging purposes,
 207  *      however, they can be enabled even on a uniprocessor.)  This
 208  *      should be the "most popular" spinning lock; the usimple_lock
 209  *      and hw_lock should only be used in rare cases.
 210  *
 211  *      IMPORTANT:  simple_locks that may be shared between interrupt
 212  *      and thread context must have their use coordinated with spl.
 213  *      The spl level must alway be the same when acquiring the lock.
 214  *      Otherwise, deadlock may result.
 215  *
 216  *      Given that, in some configurations, Mach does not need to
 217  *      allocate simple_lock data structures, users of simple_locks
 218  *      should employ the "decl_simple_lock_data" macro when allocating
 219  *      simple_locks.  Note that it use should be something like
 220  *              decl_simple_lock_data(static,foo_lock)
 221  *      WITHOUT any terminating semi-colon.  Because the macro expands
 222  *      to include its own semi-colon, if one is needed, it may safely
 223  *      be used multiple times at arbitrary positions within a structure.
 224  *      Adding a semi-colon will cause structure definitions to fail
 225  *      when locks are turned off and a naked semi-colon is left behind.
 226  */
 227
 228 /*
 229  *      Decide whether to allocate simple_lock data structures.
 230  *      If the machine-dependent code has turned on LOCK_SIMPLE_DATA,
 231  *      then it assumes all responsibility.  Otherwise, we need
 232  *      these data structures if the configuration includes SMP or
 233  *      lock debugging or statistics.
 234  *
 235  *      N.B.  Simple locks should be declared using
 236  *              decl_simple_lock_data(class,name)
 237  *      with no trailing semi-colon.  This syntax works best because
 238  *              - it correctly disappears in production uniprocessor
 239  *                configurations, leaving behind no allocated data
 240  *                structure
 241  *              - it can handle static and extern declarations:
 242  *                      decl_simple_lock_data(extern,foo)       extern
 243  *                      decl_simple_lock_data(static,foo)       static
 244  *                      decl_simple_lock_data(,foo)             ordinary
 245  */
 246
 247 #include <sys/appleapiopts.h>
 248
 249 #ifdef  __APPLE_API_PRIVATE
 250
 251 #ifdef  MACH_KERNEL_PRIVATE
 252
 253 #include <mach_ldebug.h>
 254 #include <cpus.h>
 255
 256 /*
 257  * Turn on the uslock debug (internally to oskmk) when we are using the
 258  * package and mach_ldebug build option is set.
 259  */
 260 #if (MACH_LDEBUG) && !(defined(LOCK_SIMPLE_DATA))
 261 #define USLOCK_DEBUG 1
 262 #else
 263 #define USLOCK_DEBUG 0
 264 #endif
 265
 266 #if     (defined(LOCK_SIMPLE_DATA) || ((NCPUS == 1) && !USLOCK_DEBUG ))
 267 typedef usimple_lock_data_t     *simple_lock_t;
 268 #define decl_simple_lock_data(class,name)
 269 #endif
 270
 271 #endif  /* MACH_KERNEL_PRIVATE */
 272
 273 #endif  /* __APPLE_API_PRIVATE */
 274
 275 /*
 276  *  Outside the mach kernel component, and even within it on SMP or
 277  *  debug systems, simple locks are the same as usimple locks.
 278  */
 279 #if !defined(decl_simple_lock_data)
 280 typedef usimple_lock_data_t     *simple_lock_t;
 281 typedef usimple_lock_data_t     simple_lock_data_t;
 282
 283 #define decl_simple_lock_data(class,name) \
 284         class   simple_lock_data_t      name;
 285
 286 #endif  /* !defined(decl_simple_lock_data) */
 287
 288 #endif /* !_SIMPLE_LOCK_TYPES_H_ */