SVR5

hierarchy(D5)

hierarchy -- hierarachy value for spin locks

Synopsis

   #include <sys/types.h>
   #include <sys/ddi.h>

Description

hierarchy is specified as an argument to functions that allocate a spin lock such as LOCK_ALLOC(D3) and RW_ALLOC(D3). hierarchy is a value between 1 and 32 inclusive and must be chosen so that locks are normally acquired in order of increasing hierarchy number. In other words, when acquiring a spin 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 that are associated with all locks currently held by the calling context.

Usage

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

For more information about the roll of the hierarchy order in preventing deadlocks, see ``Spin locks (DDI)'' in HDK Technical Reference.

To test the sanity of locking hierarchies:

Compile the driver as follows:
```
   cc -D_KERNEL -D_LOCKTEST -DDEBUG -c driv.c
```
The resulting object file has lock testing enabled.
Install the driver in either a native or debug kernel. Any lock hierarchy violations will cause the system to panic, and you can use kdb, scodb, or crash to examine the system.

References

LOCK_ALLOC(D3), RW_ALLOC(D3)

``Spin locks (DDI)'' in HDK Technical Reference
``Using SCODB on SVR5'' in Developing device drivers