RW_ALLOC(D3) RW_ALLOC(D3)
NAME
RW_ALLOC - allocate and initialize a read/write lock
SYNOPSIS
#include <sys/types.h>
#include <sys/kmem.h>
#include <sys/ksynch.h>
#include <sys/ddi.h>
rwlock_t *RW_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 RW_RDLOCK(D3)
and RW_WRLOCK(D3)].
lkinfop Pointer to a lkinfo structure.
flag Specifies whether the caller is willing to sleep
waiting for memory.
DESCRIPTION
RW_ALLOC dynamically allocates and initializes an instance of
a read/write 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 RW_ALLOC will
return NULL if sufficient memory is not immediately available.
Return Values
Upon successful completion, RW_ALLOC returns a pointer to the
newly allocated lock. If KM_NOSLEEP is specified and
sufficient memory is not immediately available, RW_ALLOC
returns a NULL pointer.
USAGE
hierarchy Argument
This assertion is enforced by the system when the driver is
compiled with the DEBUG and _LOCKTEST compilation options
Copyright 1994 Novell, Inc. Page 1
RW_ALLOC(D3) RW_ALLOC(D3)
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 read/write lock using any function
other than RW_TRYRDLOCK(D3) or RW_TRYWRLOCK(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.
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. For example, 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.
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
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.
Copyright 1994 Novell, Inc. Page 2
RW_ALLOC(D3) RW_ALLOC(D3)
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 RW_ALLOC call
does not actually cause any interrupts to be blocked upon lock
acquisition, it simply asserts that subsequent
RW_RDLOCK/RW_WRLOCK calls to acquire this lock will pass in a
priority level at least as great as min_pl.
lkinfop Argument
The lk_name member of the lkinfo structure [see
LKINFO_DECL(D5)] points to a character string defining a name
that will be associated with the lock for the purpose of
statistics gathering. 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 (that is, 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 for
use with RW_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
lkinfo structure may be shared among multiple read/write locks
and basic locks but a lkinfo structure may not be shared
between a read/write 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 RW_ALLOC.
Copyright 1994 Novell, Inc. Page 3
RW_ALLOC(D3) RW_ALLOC(D3)
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, RW_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
LKINFO_DECL(D5), RW_DEALLOC(D3), RW_RDLOCK(D3),
RW_TRYRDLOCK(D3), RW_TRYWRLOCK(D3), RW_UNLOCK(D3),
RW_WRLOCK(D3)
NOTICES
Portability
All processors
Applicability
ddi: 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 4