i_disable Kernel Service

Purpose

Disables interrupt priorities.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/intr.h>

int i_disable ( new) int new;

Parameter

Item	Description
new	Specifies the new interrupt priority.

Description

Attention: The i_disable service has two side effects that result from the replaceable and pageable nature of the kernel. First, it prevents process dispatching. Second, it ensures, within limits, that the caller's stack is in memory. Page faults that occur while the interrupt priority is not equal to INTBASE crash the system.

Note: The i_disable service is very similar to the standard UNIX spl service.

The i_disable service sets the interrupt priority to a more favored interrupt priority. The interrupt priority is used to control which interrupts are allowed.

A value of INTMAX is the most favored priority and disables all interrupts. A value of INTBASE is the least favored and disables only interrupts not in use. The /usr/include/sys/intr.h file defines valid interrupt priorities.

The interrupt priority is changed only to serialize code executing in more than one environment (that is, process and interrupt environments).

For example, a device driver typically links requests in a list while executing under the calling process. The device driver's interrupt handler typically uses this list to initiate the next request. Therefore, the device driver must serialize updating this list with device interrupts. The i_disable and i_enable services provide this ability. The I_init kernel service contains a brief description of interrupt handlers.

Note: When serializing such code in a multiprocessor-safe kernel extension, locking must be used as well as interrupt control. For this reason, new code should call the disable_lock kernel service instead of i_disable. The disable_lock service performs locking only on multiprocessor systems, and helps ensure that code is portable between uniprocessor and multiprocessor systems.

The i_disable service must always be used with the i_enable service. A routine must always return with the interrupt priority restored to the value that it had upon entry.

The i_mask service can be used when a routine must disable its device across a return.

Because of these side effects, the caller of the i_disable service should ensure that:

The reference parameters are pinned.
The code executed during the disable operation is pinned.
The amount of stack used during the disable operation is less than 1KB.
The called programs use less than 1KB of stack.

In general, the caller of the i_disable service should also call only services that can be called by interrupt handlers. However, processes that call the i_disable service can call the e_sleep, e_wait, e_sleepl, lockl, and unlockl services as long as the event word or lockword is pinned.

The kernel's first-level interrupt handler sets the interrupt priority for an interrupt handler before calling the interrupt handler. The interrupt priority for a process is set to INTBASE when the process is created and is part of each process's state. The dispatcher sets the interrupt priority to the value associated with the process to be executed.

Execution Environment

The i_disable kernel service can be called from either the process or interrupt environment.

Return Value

The i_disable service returns the current interrupt priority that is subsequently used with the i_enable service.