SVR5

LOCK_ALLOC(D3)

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);

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 returns NULL if sufficient memory is not immediately available.

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.

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.

Usage

hierarchy argument

See hierarchy(D5).

min_pl argument

See pl(D5) for a list of values.

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

Context and synchronization

If flag is set to KM_NOSLEEP, non-blockable, initialization, or interrupt context.

If flag is set to KM_SLEEP, user context.

Hardware applicability

All

Version applicability

ddi: 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

References

hierarchy(D5), LOCK(D3), LOCK_DEALLOC(D3), LKINFO_DECL(D5), pl(D5) TRYLOCK(D3), UNLOCK(D3)

``Spin locks (DDI)'' in HDK Technical Reference