osfmk/kern/locks.h

   1 /*
   2  * Copyright (c) 2003-2007 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        <machine/locks.h>
  38
  39 #ifdef  MACH_KERNEL_PRIVATE
  40 #include        <kern/queue.h>
  41
  42 extern void                             lck_mod_init(
  43                                                                 void) __attribute__((section("__TEXT, initcode")));
  44
  45 typedef unsigned int    lck_type_t;
  46
  47 #define LCK_TYPE_SPIN   1
  48 #define LCK_TYPE_MTX    2
  49 #define LCK_TYPE_RW     3
  50
  51 #endif
  52
  53 typedef unsigned int            lck_sleep_action_t;
  54
  55 #define LCK_SLEEP_DEFAULT       0x00    /* Release the lock while waiting for the event, then reclaim */
  56                                                                         /* RW locks are returned in the same mode */
  57 #define LCK_SLEEP_UNLOCK        0x01    /* Release the lock and return unheld */
  58 #define LCK_SLEEP_SHARED        0x02    /* Reclaim the lock in shared mode (RW only) */
  59 #define LCK_SLEEP_EXCLUSIVE     0x04    /* Reclaim the lock in exclusive mode (RW only) */
  60
  61 #define LCK_SLEEP_MASK          0x07    /* Valid actions */
  62
  63 #ifdef  MACH_KERNEL_PRIVATE
  64
  65 typedef struct {
  66         uint64_t                        lck_grp_spin_util_cnt;
  67         uint64_t                        lck_grp_spin_held_cnt;
  68         uint64_t                        lck_grp_spin_miss_cnt;
  69         uint64_t                        lck_grp_spin_held_max;
  70         uint64_t                        lck_grp_spin_held_cum;
  71 } lck_grp_spin_stat_t;
  72
  73 typedef struct {
  74         uint64_t                        lck_grp_mtx_util_cnt;
  75         /* On x86, this is used as the "direct wait" count */
  76         uint64_t                        lck_grp_mtx_held_cnt;
  77         uint64_t                        lck_grp_mtx_miss_cnt;
  78         uint64_t                        lck_grp_mtx_wait_cnt;
  79         /* Rest currently unused */
  80         uint64_t                        lck_grp_mtx_held_max;
  81         uint64_t                        lck_grp_mtx_held_cum;
  82         uint64_t                        lck_grp_mtx_wait_max;
  83         uint64_t                        lck_grp_mtx_wait_cum;
  84 } lck_grp_mtx_stat_t;
  85
  86 typedef struct {
  87         uint64_t                        lck_grp_rw_util_cnt;
  88         uint64_t                        lck_grp_rw_held_cnt;
  89         uint64_t                        lck_grp_rw_miss_cnt;
  90         uint64_t                        lck_grp_rw_wait_cnt;
  91         uint64_t                        lck_grp_rw_held_max;
  92         uint64_t                        lck_grp_rw_held_cum;
  93         uint64_t                        lck_grp_rw_wait_max;
  94         uint64_t                        lck_grp_rw_wait_cum;
  95 } lck_grp_rw_stat_t;
  96
  97 typedef struct _lck_grp_stat_ {
  98         lck_grp_spin_stat_t     lck_grp_spin_stat;
  99         lck_grp_mtx_stat_t      lck_grp_mtx_stat;
 100         lck_grp_rw_stat_t       lck_grp_rw_stat;
 101 } lck_grp_stat_t;
 102
 103 #define LCK_GRP_MAX_NAME        64
 104
 105 typedef struct _lck_grp_ {
 106         queue_chain_t           lck_grp_link;
 107         unsigned int            lck_grp_refcnt;
 108         unsigned int            lck_grp_spincnt;
 109         unsigned int            lck_grp_mtxcnt;
 110         unsigned int            lck_grp_rwcnt;
 111         unsigned int            lck_grp_attr;
 112         char                    lck_grp_name[LCK_GRP_MAX_NAME];
 113         lck_grp_stat_t          lck_grp_stat;
 114 } lck_grp_t;
 115
 116 #define LCK_GRP_NULL    (lck_grp_t *)0
 117
 118 #else
 119 typedef struct __lck_grp__ lck_grp_t;
 120 #endif
 121
 122 #ifdef  MACH_KERNEL_PRIVATE
 123 typedef struct _lck_grp_attr_ {
 124         unsigned int    grp_attr_val;
 125 } lck_grp_attr_t;
 126
 127 extern lck_grp_attr_t  LockDefaultGroupAttr;
 128
 129 #define LCK_GRP_ATTR_STAT       0x1
 130
 131 #else
 132 typedef struct __lck_grp_attr__ lck_grp_attr_t;
 133 #endif
 134
 135 #define LCK_GRP_ATTR_NULL       (lck_grp_attr_t *)0
 136
 137 __BEGIN_DECLS
 138
 139 extern  lck_grp_attr_t  *lck_grp_attr_alloc_init(
 140                                                                         void);
 141
 142 extern  void                    lck_grp_attr_setdefault(
 143                                                                         lck_grp_attr_t  *attr);
 144
 145 extern  void                    lck_grp_attr_setstat(
 146                                                                         lck_grp_attr_t  *attr);
 147
 148 extern  void                    lck_grp_attr_free(
 149                                                                         lck_grp_attr_t  *attr);
 150
 151 extern  lck_grp_t               *lck_grp_alloc_init(
 152                                                                         const char*             grp_name,
 153                                                                         lck_grp_attr_t  *attr);
 154
 155 __END_DECLS
 156
 157 #ifdef  MACH_KERNEL_PRIVATE
 158 extern  void                    lck_grp_init(
 159                                                                         lck_grp_t               *grp,
 160                                                                         const char*             grp_name,
 161                                                                         lck_grp_attr_t  *attr);
 162
 163 extern  void                    lck_grp_reference(
 164                                                                         lck_grp_t               *grp);
 165
 166 extern  void                    lck_grp_deallocate(
 167                                                                         lck_grp_t                *grp);
 168
 169 extern  void                    lck_grp_lckcnt_incr(
 170                                                                         lck_grp_t               *grp,
 171                                                                         lck_type_t              lck_type);
 172
 173 extern  void                    lck_grp_lckcnt_decr(
 174                                                                         lck_grp_t               *grp,
 175                                                                         lck_type_t              lck_type);
 176 #endif
 177
 178 __BEGIN_DECLS
 179
 180 extern void                             lck_grp_free(
 181                                                                         lck_grp_t               *grp);
 182
 183 __END_DECLS
 184
 185 #ifdef  MACH_KERNEL_PRIVATE
 186 typedef struct _lck_attr_ {
 187         unsigned int    lck_attr_val;
 188 } lck_attr_t;
 189
 190 extern lck_attr_t      LockDefaultLckAttr;
 191
 192 #define LCK_ATTR_NONE           0
 193
 194 #define LCK_ATTR_DEBUG                          0x00000001
 195 #define LCK_ATTR_RW_SHARED_PRIORITY     0x00010000
 196
 197 #else
 198 typedef struct __lck_attr__ lck_attr_t;
 199 #endif
 200
 201 #define LCK_ATTR_NULL (lck_attr_t *)0
 202
 203 __BEGIN_DECLS
 204
 205 extern  lck_attr_t              *lck_attr_alloc_init(
 206                                                                         void);
 207
 208 extern  void                    lck_attr_setdefault(
 209                                                                         lck_attr_t              *attr);
 210
 211 extern  void                    lck_attr_setdebug(
 212                                                                         lck_attr_t              *attr);
 213
 214 extern  void                    lck_attr_cleardebug(
 215                                                                         lck_attr_t              *attr);
 216
 217 #ifdef  XNU_KERNEL_PRIVATE
 218 extern  void                    lck_attr_rw_shared_priority(
 219                                                                         lck_attr_t              *attr);
 220 #endif
 221
 222 extern  void                    lck_attr_free(
 223                                                                         lck_attr_t              *attr);
 224
 225 #define decl_lck_spin_data(class,name)     class lck_spin_t name;
 226
 227 extern lck_spin_t               *lck_spin_alloc_init(
 228                                                                         lck_grp_t               *grp,
 229                                                                         lck_attr_t              *attr);
 230
 231 extern void                             lck_spin_init(
 232                                                                         lck_spin_t              *lck,
 233                                                                         lck_grp_t               *grp,
 234                                                                         lck_attr_t              *attr);
 235
 236 extern void                             lck_spin_lock(
 237                                                                         lck_spin_t              *lck);
 238
 239 extern void                             lck_spin_unlock(
 240                                                                         lck_spin_t              *lck);
 241
 242 extern void                             lck_spin_destroy(
 243                                                                         lck_spin_t              *lck,
 244                                                                         lck_grp_t               *grp);
 245
 246 extern void                             lck_spin_free(
 247                                                                         lck_spin_t              *lck,
 248                                                                         lck_grp_t               *grp);
 249
 250 extern wait_result_t    lck_spin_sleep(
 251                                                                         lck_spin_t                      *lck,
 252                                                                         lck_sleep_action_t      lck_sleep_action,
 253                                                                         event_t                         event,
 254                                                                         wait_interrupt_t        interruptible);
 255
 256 extern wait_result_t    lck_spin_sleep_deadline(
 257                                                                         lck_spin_t                      *lck,
 258                                                                         lck_sleep_action_t      lck_sleep_action,
 259                                                                         event_t                         event,
 260                                                                         wait_interrupt_t        interruptible,
 261                                                                         uint64_t                        deadline);
 262
 263 #ifdef  KERNEL_PRIVATE
 264
 265 extern boolean_t                lck_spin_try_lock(
 266                                                                         lck_spin_t              *lck);
 267
 268 #endif
 269
 270
 271 #define decl_lck_mtx_data(class,name)     class lck_mtx_t name;
 272
 273 extern lck_mtx_t                *lck_mtx_alloc_init(
 274                                                                         lck_grp_t               *grp,
 275                                                                         lck_attr_t              *attr);
 276
 277 extern void                             lck_mtx_init(
 278                                                                         lck_mtx_t               *lck,
 279                                                                         lck_grp_t               *grp,
 280                                                                         lck_attr_t              *attr);
 281
 282 extern void                             lck_mtx_lock(
 283                                                                         lck_mtx_t               *lck);
 284
 285 extern void                             lck_mtx_unlock(
 286                                                                         lck_mtx_t               *lck);
 287
 288 extern void                             lck_mtx_destroy(
 289                                                                         lck_mtx_t               *lck,
 290                                                                         lck_grp_t               *grp);
 291
 292 extern void                             lck_mtx_free(
 293                                                                         lck_mtx_t               *lck,
 294                                                                         lck_grp_t               *grp);
 295
 296 extern wait_result_t    lck_mtx_sleep(
 297                                                                         lck_mtx_t                       *lck,
 298                                                                         lck_sleep_action_t      lck_sleep_action,
 299                                                                         event_t                         event,
 300                                                                         wait_interrupt_t        interruptible);
 301
 302 extern wait_result_t    lck_mtx_sleep_deadline(
 303                                                                         lck_mtx_t                       *lck,
 304                                                                         lck_sleep_action_t      lck_sleep_action,
 305                                                                         event_t                         event,
 306                                                                         wait_interrupt_t        interruptible,
 307                                                                         uint64_t                        deadline);
 308
 309 #ifdef  KERNEL_PRIVATE
 310
 311 extern boolean_t                lck_mtx_try_lock(
 312                                                                         lck_mtx_t               *lck);
 313
 314 #ifdef i386
 315 extern boolean_t                lck_mtx_try_lock_spin(
 316                                                                         lck_mtx_t               *lck);
 317
 318 extern void                     lck_mtx_lock_spin(
 319                                                                         lck_mtx_t               *lck);
 320
 321 extern void                     lck_mtx_convert_spin(
 322                                                                         lck_mtx_t               *lck);
 323 #else
 324 #define lck_mtx_try_lock_spin(l)        lck_mtx_try_lock(l)
 325 #define lck_mtx_lock_spin(l)            lck_mtx_lock(l)
 326 #define lck_mtx_convert_spin(l)         do {} while (0)
 327 #endif
 328
 329 #endif  /* KERNEL_PRIVATE */
 330
 331 extern void                             lck_mtx_assert(
 332                                                                         lck_mtx_t               *lck,
 333                                                                         unsigned int    type);
 334
 335 __END_DECLS
 336
 337 #define LCK_MTX_ASSERT_OWNED    0x01
 338 #define LCK_MTX_ASSERT_NOTOWNED 0x02
 339
 340 #ifdef  MACH_KERNEL_PRIVATE
 341 extern void                             lck_mtx_lock_wait(
 342                                                                         lck_mtx_t               *lck,
 343                                                                         thread_t                holder);
 344
 345 extern int                              lck_mtx_lock_acquire(
 346                                                                         lck_mtx_t               *lck);
 347
 348 extern void                             lck_mtx_unlock_wakeup(
 349                                                                         lck_mtx_t               *lck,
 350                                                                         thread_t                holder);
 351 extern void                             lck_mtx_unlockspin_wakeup(
 352                                                                         lck_mtx_t               *lck);
 353
 354 extern boolean_t                lck_mtx_ilk_unlock(
 355                                                                         lck_mtx_t               *lck);
 356
 357 struct _lck_mtx_ext_;
 358 extern void lck_mtx_init_ext(lck_mtx_t *lck, struct _lck_mtx_ext_ *lck_ext,
 359     lck_grp_t *grp, lck_attr_t *attr);
 360 #endif
 361
 362 #define decl_lck_rw_data(class,name)     class lck_rw_t name;
 363
 364 typedef unsigned int     lck_rw_type_t;
 365
 366 #define LCK_RW_TYPE_SHARED                      0x01
 367 #define LCK_RW_TYPE_EXCLUSIVE           0x02
 368
 369 #ifdef XNU_KERNEL_PRIVATE
 370 #define LCK_RW_ASSERT_SHARED    0x01
 371 #define LCK_RW_ASSERT_EXCLUSIVE 0x02
 372 #define LCK_RW_ASSERT_HELD      (LCK_RW_ASSERT_SHARED | LCK_RW_ASSERT_EXCLUSIVE)
 373 #endif
 374
 375 __BEGIN_DECLS
 376
 377 extern lck_rw_t                 *lck_rw_alloc_init(
 378                                                                         lck_grp_t               *grp,
 379                                                                         lck_attr_t              *attr);
 380
 381 extern void                             lck_rw_init(
 382                                                                         lck_rw_t                *lck,
 383                                                                         lck_grp_t               *grp,
 384                                                                         lck_attr_t              *attr);
 385
 386 extern void                             lck_rw_lock(
 387                                                                         lck_rw_t                *lck,
 388                                                                         lck_rw_type_t   lck_rw_type);
 389
 390 extern void                             lck_rw_unlock(
 391                                                                         lck_rw_t                *lck,
 392                                                                         lck_rw_type_t   lck_rw_type);
 393
 394 extern void                             lck_rw_lock_shared(
 395                                                                         lck_rw_t                *lck);
 396
 397 extern void                             lck_rw_unlock_shared(
 398                                                                         lck_rw_t                *lck);
 399
 400 extern void                             lck_rw_lock_exclusive(
 401                                                                         lck_rw_t                *lck);
 402
 403 extern void                             lck_rw_unlock_exclusive(
 404                                                                         lck_rw_t                *lck);
 405
 406 #ifdef  XNU_KERNEL_PRIVATE
 407 /*
 408  * CAUTION
 409  * read-write locks do not have a concept of ownership, so lck_rw_assert()
 410  * merely asserts that someone is holding the lock, not necessarily the caller.
 411  */
 412 extern void                             lck_rw_assert(
 413                                                                         lck_rw_t                *lck,
 414                                                                         unsigned int            type);
 415 #endif
 416
 417 #ifdef  KERNEL_PRIVATE
 418
 419 extern lck_rw_type_t    lck_rw_done(
 420                                                                         lck_rw_t                *lck);
 421 #endif
 422
 423 extern void                             lck_rw_destroy(
 424                                                                         lck_rw_t                *lck,
 425                                                                         lck_grp_t               *grp);
 426
 427 extern void                             lck_rw_free(
 428                                                                         lck_rw_t                *lck,
 429                                                                         lck_grp_t               *grp);
 430
 431 extern wait_result_t    lck_rw_sleep(
 432                                                                         lck_rw_t                        *lck,
 433                                                                         lck_sleep_action_t      lck_sleep_action,
 434                                                                         event_t                         event,
 435                                                                         wait_interrupt_t        interruptible);
 436
 437 extern wait_result_t    lck_rw_sleep_deadline(
 438                                                                         lck_rw_t                        *lck,
 439                                                                         lck_sleep_action_t      lck_sleep_action,
 440                                                                         event_t                         event,
 441                                                                         wait_interrupt_t        interruptible,
 442                                                                         uint64_t                        deadline);
 443
 444 extern boolean_t                lck_rw_lock_shared_to_exclusive(
 445                                                                         lck_rw_t                *lck);
 446
 447 extern void                             lck_rw_lock_exclusive_to_shared(
 448                                                                         lck_rw_t                *lck);
 449
 450 extern boolean_t                lck_rw_try_lock(
 451                                                                         lck_rw_t                *lck,
 452                                                                         lck_rw_type_t   lck_rw_type);
 453
 454 #ifdef  KERNEL_PRIVATE
 455
 456 extern boolean_t                lck_rw_try_lock_shared(
 457                                                                         lck_rw_t                *lck);
 458
 459 extern boolean_t                lck_rw_try_lock_exclusive(
 460                                                                         lck_rw_t                *lck);
 461 #endif
 462
 463 __END_DECLS
 464
 465 #endif /* _KERN_LOCKS_H_ */