LOCK(D3)

NAME
     LOCK - acquire a basic lock

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

     int LOCK(lock_t *lockp, pl_t pl);

   Arguments
     lockp     Pointer to the basic lock to be acquired.

     pl        The interrupt priority level to be set while the lock is held
               by the caller.

DESCRIPTION
     LOCK sets the interrupt priority level in accordance with the value
     specified by pl and acquires the lock specified by lockp.  If the lock is
     not immediately available, the caller will busy-wait until the lock is
     available.

   Return Values
     Upon acquiring the lock, LOCK returns the previous mask for use by
     UNLOCK.  Your driver should treat this return integer as an "opaque"
     value and should not try to compare it with any other value or perform
     any operation on it.

USAGE
     Because some implementations require that interrupts that might attempt
     to acquire the lock be blocked on the processor on which the lock is
     held, portable drivers must specify a pl value that is sufficient to
     block out any interrupt handler that might attempt to acquire this lock.
     See the description of the min_pl argument to LOCK_ALLOC(D3) for
     additional discussion and a list of the valid values for pl.

   Level
     Base or Interrupt.

   Synchronization Constraints
     Driver-defined sleep locks may be held across calls to this function.

     Driver-defined basic locks and read/write locks may be held across calls
     to this function subject to the hierarchy -- but basic locks must be
     unlocked in the reverse order in which they were acquired (first-in,
     last-out).

   Warnings
     Basic locks are not recursive.  A call to LOCK attempting to acquire a
     lock that is currently held by the calling context will result in
     deadlock.
     Calls to LOCK should honor the hierarchy ordering to avoid deadlock.

     When called from interrupt level, the pl argument must not specify a
     priority level below the level at which the interrupt handler is running.

REFERENCES
     LOCK_ALLOC(D3), LOCK_DEALLOC(D3), LOCK_DESTROY(D3), LOCK_INIT(D3),
     TRYLOCK(D3), UNLOCK(D3).