NAME

RW_ALLOC − allocate and initialize a read/write lock .IX \f4RW_ALLOC\fP(D3DK)

SYNOPSIS

#include <sys/types.h>
#include <sys/kmem.h>
#include <sys/ksynch.h>
rwlock_t ∗RW_ALLOC(uchar_t hierarchy, pl_t min_pl, lkinfo_t ∗lkinfop, int flag);

ARGUMENTS

hierarchyHierarchy value which asserts the order in which this lock will be acquired relative to other basic and read/write locks.  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 read/write lock using any function other than RW_TRYRDLOCK(D3DK) or RW_TRYWRLOCK(D3DK), 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 (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). 

min_plMinimum priority level argument which asserts the minimum priority level that will be passed in with any attempt to acquire this lock [see RW_RDLOCK(D3DK) and RW_WRLOCK(D3DK)].  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:

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 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. 

lkinfopPointer to a lkinfo(D4DK) 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.  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 (i.e. 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. 

flagSpecifies whether the caller is willing to sleep waiting for memory.  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.  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. 

DESCRIPTION

RW_ALLOC dynamically allocates and initializes an instance of a read/write lock.  The lock is initialized to the unlocked state. 

RETURN VALUE

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. 

LEVEL

Base only if flag is set to KM_SLEEP.  Base or interrupt if flag is set to KM_NOSLEEP. 

NOTES

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. 

SEE ALSO

RW_DEALLOC(D3DK), RW_RDLOCK(D3DK), RW_TRYRDLOCK(D3DK), RW_TRYWRLOCK(D3DK), RW_UNLOCK(D3DK), RW_WRLOCK(D3DK), lkinfo(D4DK)

DDI/DKI