osfmk/kern/locks.h

   1 /*
   2  * Copyright (c) 2003-2012 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28
  29 #ifndef _KERN_LOCKS_H_
  30 #define _KERN_LOCKS_H_
  31
  32 #include        <sys/cdefs.h>
  33 #include        <sys/appleapiopts.h>
  34 #include        <mach/boolean.h>
  35 #include        <mach/mach_types.h>
  36 #include        <kern/kern_types.h>
  37 #include        <kern/lock_group.h>
  38 #include        <machine/locks.h>
  39
  40 #ifdef  MACH_KERNEL_PRIVATE
  41 #include        <kern/queue.h>
  42
  43 extern void                             lck_mod_init(
  44         void);
  45
  46 #endif
  47
  48 typedef unsigned int            lck_sleep_action_t;
  49
  50 #define LCK_SLEEP_DEFAULT       0x00    /* Release the lock while waiting for the event, then reclaim */
  51 /* RW locks are returned in the same mode */
  52 #define LCK_SLEEP_UNLOCK        0x01    /* Release the lock and return unheld */
  53 #define LCK_SLEEP_SHARED        0x02    /* Reclaim the lock in shared mode (RW only) */
  54 #define LCK_SLEEP_EXCLUSIVE     0x04    /* Reclaim the lock in exclusive mode (RW only) */
  55 #define LCK_SLEEP_SPIN          0x08    /* Reclaim the lock in spin mode (mutex only) */
  56 #define LCK_SLEEP_PROMOTED_PRI  0x10    /* Sleep at a promoted priority */
  57 #define LCK_SLEEP_SPIN_ALWAYS   0x20    /* Reclaim the lock in spin-always mode (mutex only) */
  58
  59 #define LCK_SLEEP_MASK          0x3f    /* Valid actions */
  60
  61
  62 #ifdef  MACH_KERNEL_PRIVATE
  63 typedef struct _lck_attr_ {
  64         unsigned int    lck_attr_val;
  65 } lck_attr_t;
  66
  67 extern lck_attr_t      LockDefaultLckAttr;
  68
  69 #define LCK_ATTR_NONE           0
  70
  71 #define LCK_ATTR_DEBUG                          0x00000001
  72 #define LCK_ATTR_RW_SHARED_PRIORITY     0x00010000
  73
  74 #else
  75 typedef struct __lck_attr__ lck_attr_t;
  76 #endif
  77
  78 #define LCK_ATTR_NULL (lck_attr_t *)0
  79
  80 __BEGIN_DECLS
  81
  82 extern  lck_attr_t              *lck_attr_alloc_init(
  83         void);
  84
  85 extern  void                    lck_attr_setdefault(
  86         lck_attr_t              *attr);
  87
  88 extern  void                    lck_attr_setdebug(
  89         lck_attr_t              *attr);
  90
  91 extern  void                    lck_attr_cleardebug(
  92         lck_attr_t              *attr);
  93
  94 #ifdef  XNU_KERNEL_PRIVATE
  95
  96 typedef union {
  97         uint16_t tcurnext;
  98         struct {
  99                 uint8_t cticket;
 100                 uint8_t nticket;
 101         };
 102 } lck_ticket_internal;
 103
 104 typedef struct {
 105         lck_ticket_internal tu;
 106         uintptr_t lck_owner;
 107 } lck_ticket_t;
 108
 109 void lck_ticket_init(lck_ticket_t *tlock);
 110 void lck_ticket_lock(lck_ticket_t *tlock);
 111 void lck_ticket_unlock(lck_ticket_t *tlock);
 112 void lck_ticket_assert_owned(lck_ticket_t *tlock);
 113
 114 extern  void                    lck_attr_rw_shared_priority(
 115         lck_attr_t              *attr);
 116 #endif
 117
 118 extern  void                    lck_attr_free(
 119         lck_attr_t              *attr);
 120
 121 #define decl_lck_spin_data(class, name)     class lck_spin_t name;
 122
 123 extern lck_spin_t               *lck_spin_alloc_init(
 124         lck_grp_t               *grp,
 125         lck_attr_t              *attr);
 126
 127 extern void                             lck_spin_init(
 128         lck_spin_t              *lck,
 129         lck_grp_t               *grp,
 130         lck_attr_t              *attr);
 131
 132 extern void                             lck_spin_lock(
 133         lck_spin_t              *lck);
 134
 135 extern void                             lck_spin_lock_grp(
 136         lck_spin_t              *lck,
 137         lck_grp_t               *grp);
 138
 139 extern void                             lck_spin_unlock(
 140         lck_spin_t              *lck);
 141
 142 extern void                             lck_spin_destroy(
 143         lck_spin_t              *lck,
 144         lck_grp_t               *grp);
 145
 146 extern void                             lck_spin_free(
 147         lck_spin_t              *lck,
 148         lck_grp_t               *grp);
 149
 150 extern wait_result_t    lck_spin_sleep(
 151         lck_spin_t                      *lck,
 152         lck_sleep_action_t      lck_sleep_action,
 153         event_t                         event,
 154         wait_interrupt_t        interruptible);
 155
 156 extern wait_result_t    lck_spin_sleep_grp(
 157         lck_spin_t                      *lck,
 158         lck_sleep_action_t      lck_sleep_action,
 159         event_t                         event,
 160         wait_interrupt_t        interruptible,
 161         lck_grp_t               *grp);
 162
 163 extern wait_result_t    lck_spin_sleep_deadline(
 164         lck_spin_t                      *lck,
 165         lck_sleep_action_t      lck_sleep_action,
 166         event_t                         event,
 167         wait_interrupt_t        interruptible,
 168         uint64_t                        deadline);
 169
 170 #ifdef  KERNEL_PRIVATE
 171
 172 extern void                     lck_spin_lock_nopreempt(                lck_spin_t              *lck);
 173 extern void                     lck_spin_lock_nopreempt_grp(                lck_spin_t              *lck, lck_grp_t *grp);
 174
 175 extern void                     lck_spin_unlock_nopreempt(              lck_spin_t              *lck);
 176
 177 extern boolean_t                lck_spin_try_lock_grp(                      lck_spin_t              *lck, lck_grp_t *grp);
 178
 179 extern boolean_t                lck_spin_try_lock(                      lck_spin_t              *lck);
 180
 181 extern boolean_t                lck_spin_try_lock_nopreempt(            lck_spin_t              *lck);
 182 extern boolean_t                lck_spin_try_lock_nopreempt_grp(            lck_spin_t              *lck, lck_grp_t *grp);
 183
 184 /* NOT SAFE: To be used only by kernel debugger to avoid deadlock. */
 185 extern boolean_t                kdp_lck_spin_is_acquired(               lck_spin_t              *lck);
 186
 187 struct _lck_mtx_ext_;
 188 extern void lck_mtx_init_ext(lck_mtx_t *lck, struct _lck_mtx_ext_ *lck_ext,
 189     lck_grp_t *grp, lck_attr_t *attr);
 190
 191 #endif
 192
 193
 194 #define decl_lck_mtx_data(class, name)     class lck_mtx_t name;
 195
 196 extern lck_mtx_t                *lck_mtx_alloc_init(
 197         lck_grp_t               *grp,
 198         lck_attr_t              *attr);
 199
 200 extern void                             lck_mtx_init(
 201         lck_mtx_t               *lck,
 202         lck_grp_t               *grp,
 203         lck_attr_t              *attr);
 204 extern void                             lck_mtx_lock(
 205         lck_mtx_t               *lck);
 206
 207 extern void                             lck_mtx_unlock(
 208         lck_mtx_t               *lck);
 209
 210 extern void                             lck_mtx_destroy(
 211         lck_mtx_t               *lck,
 212         lck_grp_t               *grp);
 213
 214 extern void                             lck_mtx_free(
 215         lck_mtx_t               *lck,
 216         lck_grp_t               *grp);
 217
 218 extern wait_result_t    lck_mtx_sleep(
 219         lck_mtx_t                       *lck,
 220         lck_sleep_action_t      lck_sleep_action,
 221         event_t                         event,
 222         wait_interrupt_t        interruptible);
 223
 224 extern wait_result_t    lck_mtx_sleep_deadline(
 225         lck_mtx_t                       *lck,
 226         lck_sleep_action_t      lck_sleep_action,
 227         event_t                         event,
 228         wait_interrupt_t        interruptible,
 229         uint64_t                        deadline);
 230 #if DEVELOPMENT || DEBUG
 231 extern void             erase_all_test_mtx_stats(void);
 232 extern int              get_test_mtx_stats_string(char* buffer, int buffer_size);
 233 extern void             lck_mtx_test_init(void);
 234 extern void             lck_mtx_test_lock(void);
 235 extern void             lck_mtx_test_unlock(void);
 236 extern int              lck_mtx_test_mtx_uncontended(int iter, char* buffer, int buffer_size);
 237 extern int              lck_mtx_test_mtx_contended(int iter, char* buffer, int buffer_size);
 238 extern int              lck_mtx_test_mtx_uncontended_loop_time(int iter, char* buffer, int buffer_size);
 239 extern int              lck_mtx_test_mtx_contended_loop_time(int iter, char* buffer, int buffer_size);
 240 #endif
 241 #ifdef  KERNEL_PRIVATE
 242
 243 extern boolean_t                lck_mtx_try_lock(
 244         lck_mtx_t               *lck);
 245
 246 extern void                             mutex_pause(uint32_t);
 247
 248 extern void                     lck_mtx_yield(
 249         lck_mtx_t               *lck);
 250
 251 extern boolean_t                lck_mtx_try_lock_spin(
 252         lck_mtx_t               *lck);
 253
 254 extern void                     lck_mtx_lock_spin(
 255         lck_mtx_t               *lck);
 256
 257 extern boolean_t                kdp_lck_mtx_lock_spin_is_acquired(
 258         lck_mtx_t               *lck);
 259
 260 extern void                     lck_mtx_convert_spin(
 261         lck_mtx_t               *lck);
 262
 263 extern void                     lck_mtx_lock_spin_always(
 264         lck_mtx_t               *lck);
 265
 266 extern boolean_t                lck_mtx_try_lock_spin_always(
 267         lck_mtx_t               *lck);
 268
 269 #define lck_mtx_unlock_always(l)        lck_mtx_unlock(l)
 270
 271 extern void                             lck_spin_assert(
 272         lck_spin_t              *lck,
 273         unsigned int    type);
 274
 275 extern boolean_t                kdp_lck_rw_lock_is_acquired_exclusive(
 276         lck_rw_t                *lck);
 277
 278 #endif  /* KERNEL_PRIVATE */
 279
 280 extern void                             lck_mtx_assert(
 281         lck_mtx_t               *lck,
 282         unsigned int    type);
 283
 284 #if MACH_ASSERT
 285 #define LCK_MTX_ASSERT(lck, type) lck_mtx_assert((lck),(type))
 286 #define LCK_SPIN_ASSERT(lck, type) lck_spin_assert((lck),(type))
 287 #define LCK_RW_ASSERT(lck, type) lck_rw_assert((lck),(type))
 288 #else /* MACH_ASSERT */
 289 #define LCK_MTX_ASSERT(lck, type)
 290 #define LCK_SPIN_ASSERT(lck, type)
 291 #define LCK_RW_ASSERT(lck, type)
 292 #endif /* MACH_ASSERT */
 293
 294 #if DEBUG
 295 #define LCK_MTX_ASSERT_DEBUG(lck, type) lck_mtx_assert((lck),(type))
 296 #define LCK_SPIN_ASSERT_DEBUG(lck, type) lck_spin_assert((lck),(type))
 297 #define LCK_RW_ASSERT_DEBUG(lck, type) lck_rw_assert((lck),(type))
 298 #else /* DEBUG */
 299 #define LCK_MTX_ASSERT_DEBUG(lck, type)
 300 #define LCK_SPIN_ASSERT_DEBUG(lck, type)
 301 #define LCK_RW_ASSERT_DEBUG(lck, type)
 302 #endif /* DEBUG */
 303
 304 __END_DECLS
 305
 306 #define LCK_ASSERT_OWNED                1
 307 #define LCK_ASSERT_NOTOWNED             2
 308
 309 #define LCK_MTX_ASSERT_OWNED    LCK_ASSERT_OWNED
 310 #define LCK_MTX_ASSERT_NOTOWNED LCK_ASSERT_NOTOWNED
 311
 312 #ifdef  MACH_KERNEL_PRIVATE
 313 extern void                             lck_mtx_lock_wait(
 314         lck_mtx_t               *lck,
 315         thread_t                holder);
 316
 317 extern int                              lck_mtx_lock_acquire(
 318         lck_mtx_t               *lck);
 319
 320 extern void                             lck_mtx_unlock_wakeup(
 321         lck_mtx_t               *lck,
 322         thread_t                holder);
 323
 324 extern boolean_t                lck_mtx_ilk_unlock(
 325         lck_mtx_t               *lck);
 326
 327 extern boolean_t                lck_mtx_ilk_try_lock(
 328         lck_mtx_t               *lck);
 329
 330 extern void lck_mtx_wakeup_adjust_pri(thread_t thread, integer_t priority);
 331
 332 #endif
 333
 334 #define decl_lck_rw_data(class, name)     class lck_rw_t name;
 335
 336 typedef unsigned int     lck_rw_type_t;
 337
 338 #define LCK_RW_TYPE_SHARED                      0x01
 339 #define LCK_RW_TYPE_EXCLUSIVE           0x02
 340
 341 #ifdef XNU_KERNEL_PRIVATE
 342 #define LCK_RW_ASSERT_SHARED    0x01
 343 #define LCK_RW_ASSERT_EXCLUSIVE 0x02
 344 #define LCK_RW_ASSERT_HELD              0x03
 345 #define LCK_RW_ASSERT_NOTHELD   0x04
 346 #endif
 347
 348 __BEGIN_DECLS
 349
 350 extern lck_rw_t                 *lck_rw_alloc_init(
 351         lck_grp_t               *grp,
 352         lck_attr_t              *attr);
 353
 354 extern void                             lck_rw_init(
 355         lck_rw_t                *lck,
 356         lck_grp_t               *grp,
 357         lck_attr_t              *attr);
 358
 359 extern void                             lck_rw_lock(
 360         lck_rw_t                *lck,
 361         lck_rw_type_t   lck_rw_type);
 362
 363 extern void                             lck_rw_unlock(
 364         lck_rw_t                *lck,
 365         lck_rw_type_t   lck_rw_type);
 366
 367 extern void                             lck_rw_lock_shared(
 368         lck_rw_t                *lck);
 369
 370 extern void                             lck_rw_unlock_shared(
 371         lck_rw_t                *lck);
 372
 373 extern boolean_t                        lck_rw_lock_yield_shared(
 374         lck_rw_t                *lck,
 375         boolean_t       force_yield);
 376
 377 extern void                             lck_rw_lock_exclusive(
 378         lck_rw_t                *lck);
 379
 380 extern void                             lck_rw_unlock_exclusive(
 381         lck_rw_t                *lck);
 382
 383 #ifdef  XNU_KERNEL_PRIVATE
 384 /*
 385  * CAUTION
 386  * read-write locks do not have a concept of ownership, so lck_rw_assert()
 387  * merely asserts that someone is holding the lock, not necessarily the caller.
 388  */
 389 extern void                             lck_rw_assert(
 390         lck_rw_t                *lck,
 391         unsigned int            type);
 392
 393 extern void lck_rw_clear_promotion(thread_t thread, uintptr_t trace_obj);
 394 extern void lck_rw_set_promotion_locked(thread_t thread);
 395
 396 uintptr_t unslide_for_kdebug(void* object);
 397 #endif /* XNU_KERNEL_PRIVATE */
 398
 399 #ifdef  KERNEL_PRIVATE
 400
 401 extern lck_rw_type_t    lck_rw_done(
 402         lck_rw_t                *lck);
 403 #endif
 404
 405 extern void                             lck_rw_destroy(
 406         lck_rw_t                *lck,
 407         lck_grp_t               *grp);
 408
 409 extern void                             lck_rw_free(
 410         lck_rw_t                *lck,
 411         lck_grp_t               *grp);
 412
 413 extern wait_result_t    lck_rw_sleep(
 414         lck_rw_t                        *lck,
 415         lck_sleep_action_t      lck_sleep_action,
 416         event_t                         event,
 417         wait_interrupt_t        interruptible);
 418
 419 extern wait_result_t    lck_rw_sleep_deadline(
 420         lck_rw_t                        *lck,
 421         lck_sleep_action_t      lck_sleep_action,
 422         event_t                         event,
 423         wait_interrupt_t        interruptible,
 424         uint64_t                        deadline);
 425
 426 extern boolean_t                lck_rw_lock_shared_to_exclusive(
 427         lck_rw_t                *lck);
 428
 429 extern void                             lck_rw_lock_exclusive_to_shared(
 430         lck_rw_t                *lck);
 431
 432 extern boolean_t                lck_rw_try_lock(
 433         lck_rw_t                *lck,
 434         lck_rw_type_t   lck_rw_type);
 435
 436 #ifdef  KERNEL_PRIVATE
 437
 438 extern boolean_t                lck_rw_try_lock_shared(
 439         lck_rw_t                *lck);
 440
 441 extern boolean_t                lck_rw_try_lock_exclusive(
 442         lck_rw_t                *lck);
 443 #endif
 444
 445 __END_DECLS
 446
 447 #endif /* _KERN_LOCKS_H_ */