SCO OpenServer

lockb(D3oddi)

lockb, unlockb -- lock and unlock critical code section for single processor access

Syntax

#include <sys/ci/cilock.h>

int lockb(struct lockb *lock_xxtab);

int lockb5(struct lockb *lock_xxtab);

void unlockb(struct lockb *lock_xxtab, int oldspl);

Description

lockb( ) and unlockb( ) implement a spin lock that is used to ensure atomic access of a critical code section (see ``Critical code section'' in HDK Technical Reference) in multithreaded drivers.

Arguments

lock_xxtab: Pointer to a lockb(D4oddi) structure that indicates the address of the lock.
oldspl: The spl level, returned by the lockb( ) function, to be restored by unlockb. If the value of oldspl is set to -1, then unlockb does not restore the spl value; the driver must restore the spl value after the call to unlockb completes.

Return values

lockb and lockb5 return the previous spl value. unlockb does not return a value.

Usage

The lockb( ) acquires the requested lock, spins at spl7, and returns the previous spl level. While this lock is held, a process on another processor that attempts to obtain the lock will spin (busy wait). This ensures that only one processor executes the critical code section at a time.

lockb5( ) is identical to lockb( ) except it spins at spl5. This is the recommended lock interface for network drivers since it allows clock interrupts.

Locks must be released in the same order as they are acquired. See ``Spin locks (ODDI)'' in HDK Technical Reference for a full list of guidelines that must be followed when using spin locks.

The unlockb( ) function releases the lock and returns the processor to the previous spl level, restoring multiprocessor access. The address of lock_xxtab parameter to the unlockb function must be the same address used in the lockb or lockb5 call.

clockb(D3oddi) can be used to conditionally acquire a lock that was acquired by lockb( ). clockb( ) will acquire the lock if it is not already held, but does not block waiting for the lock to be available.

Context and synchronization

Non-blockable, interrupt, user, or blockable context.

Hardware applicability

All

Version applicability

oddi: 2mp, 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp

SVR5 DDI compatibility

DDI does not support these locking functions; see ``Spin locks (DDI)'' in HDK Technical Reference for information about the functions used to implement spin locks in DDI drivers. Note that DDI provides specialized spin locks (read locks, write locks, and trylocks) that can be used to reduce contention of the locks in the driver. DDI provides additional types of locks and other synchronization primitives; when porting a driver to DDI, you may want to replace some spin locks with sleep locks or synchronization variables; see ``Synchronization primitives'' in HDK Technical Reference for a list.

References

clockb(D3oddi), ilockb(D3oddi), spl(D3oddi)

``Critical code section'' in HDK Technical Reference
``Spin locks (ODDI)'' in HDK Technical Reference

Examples

Refer to the can_doio(D3oddi) manual page for an example of the use of lockb and unlockb. The sample MDI drivers provided in the HDK illustrate the use of unlockb5.