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 /*
  94  *      All of the remaining locking constructs may have two versions.
  95  *      One version is machine-independent, built in C on top of the
  96  *      hw_lock construct.  This version supports production, debugging
  97  *      and statistics configurations and is portable across architectures.
  98  *
  99  *      Any particular port may override some or all of the portable
 100  *      lock package for whatever reason -- usually efficiency.
 101  *
 102  *      The direct use of hw_locks by machine-independent Mach code
 103  *      should be rare; the preferred spinning lock is the simple_lock
 104  *      (see below).
 105  */
 106
 107 /*
 108  *      A "simple" spin lock, providing non-blocking mutual
 109  *      exclusion and conditional acquisition.
 110  *
 111  *      The usimple_lock exists even in uniprocessor configurations.
 112  *      A data structure is always allocated for it.
 113  *
 114  *      The usimple_lock may be used for synchronization between
 115  *      thread context and interrupt context, or between a uniprocessor
 116  *      and an intelligent device.  Obviously, it may also be used for
 117  *      multiprocessor synchronization.  Its use should be rare; the
 118  *      simple_lock is the preferred spinning lock (see below).
 119  *
 120  *      The usimple_lock supports optional lock debugging and statistics.
 121  *
 122  *      The usimple_lock may be inlined or optimized in ways that
 123  *      depend on the particular machine architecture and kernel
 124  *      build configuration; e.g., processor type, number of CPUs,
 125  *      production v. debugging.
 126  *
 127  *      Normally, we expect the usimple_lock data structure to be
 128  *      defined here, with its operations implemented in an efficient,
 129  *      machine-dependent way.  However, any implementation may choose
 130  *      to rely on a C-based, portable  version of the usimple_lock for
 131  *      debugging, statistics, and/or tracing.  Three hooks are used in
 132  *      the portable lock package to allow the machine-dependent package
 133  *      to override some or all of the portable package's features.
 134  *
 135  *
 136  *      The usimple_lock data structure
 137  *      can be overriden in a machine-dependent way by defining
 138  *      LOCK_USIMPLE_DATA, although we expect this to be unnecessary.
 139  *      (Note that if you choose to override LOCK_USIMPLE_DATA, you'd
 140  *      better also be prepared to override LOCK_USIMPLE_CALLS.)
 141  *
 142  *      The usimple_lock also handles pre-emption.  Lock acquisition
 143  *      implies disabling pre-emption, while lock release implies
 144  *      re-enabling pre-emption.  Conditional lock acquisition does
 145  *      not assume success:  on success, pre-emption is disabled
 146  *      but on failure the pre-emption state remains the same as
 147  *      the pre-emption state before the acquisition attempt.
 148  */
 149
 150 #ifndef USIMPLE_LOCK_DATA
 151 #define USLOCK_DEBUG_DATA 1 /* Always allocate lock debug data for now */
 152 #if     USLOCK_DEBUG_DATA
 153 /*
 154  *
 155  *
 156  *      This structure records additional information about lock state
 157  *      and recent operations.  The data are carefully organized so that
 158  *      some portions of it can be examined BEFORE actually acquiring
 159  *      the lock -- for instance, the lock_thread field, to detect an
 160  *      attempt to acquire a lock already owned by the calling thread.
 161  *      All *updates* to this structure are governed by the lock to which
 162  *      this structure belongs.
 163  *
 164  *      Note cache consistency dependency:  being able to examine some
 165  *      of the fields in this structure without first acquiring a lock
 166  *      implies strongly-ordered cache coherency OR release consistency.
 167  *      Perhaps needless to say, acquisition consistency may not suffice.
 168  *      However, it's hard to imagine a scenario using acquisition
 169  *      consistency that results in using stale data from this structure.
 170  *      It would be necessary for the thread manipulating the lock to
 171  *      switch to another processor without first executing any instructions
 172  *      that would cause the needed consistency updates; basically, without
 173  *      taking a lock.  Not possible in this kernel!
 174  */
 175 typedef struct uslock_debug {
 176         void            *lock_pc;       /* pc where lock operation began    */
 177         void            *lock_thread;   /* thread that acquired lock */
 178         unsigned long   duration[2];
 179         unsigned short  state;
 180         unsigned char   lock_cpu;
 181         void            *unlock_thread; /* last thread to release lock */
 182         unsigned char   unlock_cpu;
 183         void            *unlock_pc;     /* pc where lock operation ended    */
 184 } uslock_debug;
 185 #endif  /* USLOCK_DEBUG_DATA */
 186
 187 typedef struct slock {
 188         hw_lock_data_t  interlock;      /* must be first... see lock.c */
 189 #if     USLOCK_DEBUG_DATA
 190         unsigned short  lock_type;      /* must be second... see lock.c */
 191 #define USLOCK_TAG      0x5353
 192         uslock_debug    debug;
 193 #endif  /* USLOCK_DEBUG_DATA */
 194 } usimple_lock_data_t, *usimple_lock_t;
 195
 196 #define USIMPLE_LOCK_NULL       ((usimple_lock_t) 0)
 197
 198 #endif  /* USIMPLE_LOCK_DATA */
 199
 200 /*
 201  *      Upon the usimple_lock we define the simple_lock, which
 202  *      exists for SMP configurations.  These locks aren't needed
 203  *      in a uniprocessor configuration, so compile-time tricks
 204  *      make them disappear when NCPUS==1.  (For debugging purposes,
 205  *      however, they can be enabled even on a uniprocessor.)  This
 206  *      should be the "most popular" spinning lock; the usimple_lock
 207  *      and hw_lock should only be used in rare cases.
 208  *
 209  *      IMPORTANT:  simple_locks that may be shared between interrupt
 210  *      and thread context must have their use coordinated with spl.
 211  *      The spl level must alway be the same when acquiring the lock.
 212  *      Otherwise, deadlock may result.
 213  *
 214  *      Given that, in some configurations, Mach does not need to
 215  *      allocate simple_lock data structures, users of simple_locks
 216  *      should employ the "decl_simple_lock_data" macro when allocating
 217  *      simple_locks.  Note that it use should be something like
 218  *              decl_simple_lock_data(static,foo_lock)
 219  *      WITHOUT any terminating semi-colon.  Because the macro expands
 220  *      to include its own semi-colon, if one is needed, it may safely
 221  *      be used multiple times at arbitrary positions within a structure.
 222  *      Adding a semi-colon will cause structure definitions to fail
 223  *      when locks are turned off and a naked semi-colon is left behind.
 224  */
 225
 226 /*
 227  *      Decide whether to allocate simple_lock data structures.
 228  *      If the machine-dependent code has turned on LOCK_SIMPLE_DATA,
 229  *      then it assumes all responsibility.  Otherwise, we need
 230  *      these data structures if the configuration includes SMP or
 231  *      lock debugging or statistics.
 232  *
 233  *      N.B.  Simple locks should be declared using
 234  *              decl_simple_lock_data(class,name)
 235  *      with no trailing semi-colon.  This syntax works best because
 236  *              - it correctly disappears in production uniprocessor
 237  *                configurations, leaving behind no allocated data
 238  *                structure
 239  *              - it can handle static and extern declarations:
 240  *                      decl_simple_lock_data(extern,foo)       extern
 241  *                      decl_simple_lock_data(static,foo)       static
 242  *                      decl_simple_lock_data(,foo)             ordinary
 243  */
 244 typedef usimple_lock_data_t     *simple_lock_t;
 245
 246 #ifdef MACH_KERNEL_PRIVATE
 247 #include <mach_ldebug.h>
 248 #include <cpus.h>
 249
 250 /*
 251  * Turn on the uslock debug (internally to oskmk) when we are using the
 252  * package and mach_ldebug build option is set.
 253  */
 254 #if (MACH_LDEBUG) && !(defined(LOCK_SIMPLE_DATA))
 255 #define USLOCK_DEBUG 1
 256 #else
 257 #define USLOCK_DEBUG 0
 258 #endif
 259
 260 #if     (defined(LOCK_SIMPLE_DATA) || ((NCPUS == 1) && !USLOCK_DEBUG ))
 261 #define decl_simple_lock_data(class,name)
 262 #endif
 263 #endif /* MACH_KERNEL_PRIVATE */
 264
 265 /*
 266  *  Outside the mach kernel component, and even within it on SMP or
 267  *  debug systems, simple locks are the same as usimple locks.
 268  */
 269 #if !defined(decl_simple_lock_data)
 270 typedef usimple_lock_data_t     simple_lock_data_t;
 271 #define decl_simple_lock_data(class,name) \
 272 class   simple_lock_data_t      name;
 273 #endif  /* !defined(decl_simple_lock_data) */
 274
 275 #endif /* !_SIMPLE_LOCK_TYPES_H_ */