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