LOCK_ALLOC(D3)

NAME
     LOCK_ALLOC, LOCK_INIT - basic lock initialization

SYNOPSIS
     #include <sys/types.h>
     #include <sys/kmem.h>
     #include <sys/ksynch.h>
     #include <sys/ddi.h>

     lock_t *LOCK_ALLOC(uchar_t hierarchy, pl_t min_pl,
          lkinfo_t *lkinfop, int flag);

     void LOCK_INIT(lock_t *lockp, uchar_t hierarchy, pl_t min_pl,
          lkinfo_t *lkinfop);

   Arguments
     hierarchy Set to -1.  Reserved for future use.

     min_pl    Minimum priority level argument which asserts the minimum
               priority level that will be passed in with any attempt to
               acquire this lock [see LOCK(D3)].

     lkinfop   Set to -1.  Reserved for future use.

     flag      Specifies whether the caller is willing to sleep waiting for
               memory.

DESCRIPTION
     LOCK_ALLOC dynamically allocates and initializes an instance of a basic
     lock.  LOCK_INIT initializes an already-allocated instance of a basic
     lock.  The lock is initialized to the unlocked state.

     If flag is set to KM_SLEEP, the caller will sleep if necessary until
     sufficient memory is available.  If flag is set to KM_NOSLEEP, the caller
     will not sleep, but LOCK_ALLOC will return NULL if sufficient memory is
     not immediately available.

   Return Values
     Upon successful completion, LOCK_ALLOC returns a pointer to the newly
     allocated lock.  If KM_NOSLEEP is specified and sufficient memory is not
     immediately available, LOCK_ALLOC returns a NULL pointer.

   min_pl Argument
     The valid values for this argument are as follows:

          plbase         Block no interrupts

          pltimeout      Block functions scheduled by itimeout and dtimeout

          pldisk         Block disk device interrupts
          plstr          Block STREAMS interrupts

          plhi           Block all interrupts

     The notion of a min_pl assumes a defined order of priority levels.  The
     following partial order is defined:

     plbase < pltimeout <= pldisk,plstr <= plhi

     The ordering of pldisk and plstr relative to each other is not defined.

     Setting a given priority level will block interrupts associated with that
     level as well as any levels that are defined to be less than or equal to
     the specified level.  In order to be portable a driver should not acquire
     locks at different priority levels where the relative order of those
     priority levels is not defined above.

     The min_pl argument should specify a priority level that would be
     sufficient to block out any interrupt handler that might attempt to
     acquire this lock.  In addition, potential deadlock problems involving
     multiple locks should be considered when defining the min_pl value.  For
     example, if the normal order of acquisition of locks A and B (as defined
     by the lock hierarchy) is to acquire A first and then B, lock B should
     never be acquired at a priority level less than the min_pl for lock A.
     Therefore, the min_pl for lock B should be greater than or equal to the
     min_pl for lock A.

     Note that the specification of min_pl with a LOCK_ALLOC call does not
     actually cause any interrupts to be blocked upon lock acquisition, it
     simply asserts that subsequent LOCK calls to acquire this lock will pass
     in a priority level at least as great as min_pl.

   Level
     Base.

   Synchronization Constraints
     May sleep if flag is set to KM_SLEEP (LOCK_ALLOC only) or if debugging
     locks are installed.

     Driver-defined basic locks and read/write locks may not be held across
     calls to this functions.

     Driver-defined sleep locks may be held across calls to this function
     regardless of the value of flag.

REFERENCES
     LOCK(D3), LOCK_DEALLOC(D3), LOCK_DESTROY(D3), TRYLOCK(D3), UNLOCK(D3).