LOCK_ALLOC(D3) LOCK_ALLOC(D3)
NAME
LOCK_ALLOC - allocate and initialize a basic lock
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);
Arguments
hierarchy Hierarchy value which asserts the order in which
this lock will be acquired relative to other basic
and read/write locks.
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 Pointer to a lkinfo structure. The lk_name member
of the lkinfo structure points to a character string
defining a name that will be associated with the
lock for the purpose of statistics gathering.
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. 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.
Copyright 1994 Novell, Inc. Page 1
LOCK_ALLOC(D3) LOCK_ALLOC(D3)
USAGE
hierarchy Argument
Implementations of lock testing may differ in whether they
assume a separate range of hierarchy values for each interrupt
priority level or a single range that spans all interrupt
priority levels. In order to be portable across different
implementations, drivers which may acquire locks at more than
one interrupt priority level should define the hierarchy among
those locks such that the hierarchy is strictly increasing
with increasing priority level (e.g. if M is the maximum
hierarchy value defined for any lock that may be acquired at
priority level N, then M + 1 should be the minimum hierarchy
value defined for any lock that may be acquired at any
priority level greater than N).
This assertion is enforced by the system when the driver is
compiled with the DEBUG and _LOCKTEST compilation options
defined. hierarchy must be within the range 1 through 32
inclusive and must be chosen such that locks are normally
acquired in order of increasing hierarchy number. In other
words, when acquiring a basic lock using any function other
than TRYLOCK(D3), the lock being acquired must have a
hierarchy value that is strictly greater than the hierarchy
values associated with all locks currently held by the calling
context.
min_pl Argument
This assertion may be enforced by the system when the driver
is compiled with the DEBUG and _LOCKTEST compilation options
defined. Implementations which do not require that the
interrupt priority level be raised during lock acquisition may
choose not to enforce the min_pl assertion, even when the
appropriate compilation options have been defined. 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
Copyright 1994 Novell, Inc. Page 2
LOCK_ALLOC(D3) LOCK_ALLOC(D3)
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.
lkinfop Argument
The name should begin with the driver prefix and should be
unique to the lock or group of locks for which the driver
wishes to collect a uniquely identifiable set of statistics
(for example, if a given name is shared by a group of locks,
the statistics of individual locks within the group will not
be uniquely identifiable). There are no flags defined within
the lk_flags member of the lkinfo structure [see
LKINFO_DECL(D5)] for use with LOCK_ALLOC.
The lkinfop pointer is recorded in a statistics buffer along
with the lock statistics when the driver is compiled with the
DEBUG and _MPSTATS compilation options defined. A given
Copyright 1994 Novell, Inc. Page 3
LOCK_ALLOC(D3) LOCK_ALLOC(D3)
lkinfo structure may be shared among multiple basic locks and
read/write locks but a lkinfo structure may not be shared
between a basic lock and a sleep lock. The caller must ensure
that the lk_flags and lk_pad members of the lkinfo structure
are zeroed out before passing it to LOCK_ALLOC.
flag Argument
Under the _MPSTATS compilation option, if KM_NOSLEEP is
specified and sufficient memory can be immediately allocated
for the lock itself but not for an accompanying statistics
buffer, LOCK_ALLOC will return a pointer to the allocated lock
but individual statistics will not be collected for the lock.
Level
Base only if flag is set to KM_SLEEP.
Initialization, Base or Interrupt if flag is set to
KM_NOSLEEP.
Synchronization Constraints
May sleep if flag is set to KM_SLEEP.
Driver-defined basic locks and read/write locks may be held
across calls to this function if flag is KM_NOSLEEP but may
not be held if flag is KM_SLEEP.
Driver-defined sleep locks may be held across calls to this
function regardless of the value of flag.
REFERENCES
LOCK(D3), LOCK_DEALLOC(D3), LKINFO_DECL(D5), TRYLOCK(D3),
UNLOCK(D3)
NOTICES
Portability
All processors
Applicability
ddi: 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 4