LOCK_ALLOC(D3)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.
DESCRIPTIONLOCK_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
Page 1
LOCK_ALLOC(D3)LOCK_ALLOC(D3)
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.
REFERENCESLOCK(D3), LOCK_DEALLOC(D3), LOCK_DESTROY(D3), TRYLOCK(D3), UNLOCK(D3).
Page 2
