InterruptAttach(), InterruptAttach_r()

Присоединить функцию-обработчик прерывания к устройству-источнику прерываний

Прототип:

#include <sys/neutrino.h>
int InterruptAttach( int intr,
const struct sigevent * (*handler)( void *, int ),
const void *area,
int size,
unsigned flags );
int InterruptAttach_r( int intr,
const struct sigevent * (*handler)( void *, int ),
const void *area,
int size,
unsigned flags );

Аргументы:

intr
The interrupt that you want to attach a handler to; see “Interrupt vector numbers” below.
handler
A pointer to the handler function; see “Interrupt handler function” below.
area
A pointer to a communications area in your process, or NULL if you don't want a communications area.
size
The size of the communications area; this should be 0 if area is NULL. InterruptAttach() currently ignores this argument.
flags
Flags that specify how you want to attach the interrupt handler. For more information, see “Flags” below.

Библиотека:

libc

Описание:

The InterruptAttach() and InterruptAttach_r() kernel calls attach the interrupt function handler to the hardware interrupt specified by intr. They automatically enable (i.e unmask) the interrupt level.

Данные функции идентичны за исключением способа возврата ошибок.

Before calling either of these functions, the thread must request I/O privileges by calling:

ThreadCtl( _NTO_TCTL_IO, 0 );

If the thread doesn't do this, the attachment fails with an error code of EPERM.

On a multicore system, the interrupt handler runs on the CPU that takes the interrupt.

Interrupt vector numbers

The interrupt values for intr are logical interrupt vector numbers grouped into related “interrupt classes” that generally correspond to a particular interrupt line on the CPU. The following interrupt classes are present on all ЗОСРВ «Нейтрино» systems:

_NTO_INTR_CLASS_EXTERNAL
Normal external interrupts (such as the ones generated by the INTR pin on x86 CPUs).
_NTO_INTR_CLASS_SYNTHETIC
Synthetic, kernel-generated interrupts.

_NTO_INTR_SPARE is usually the only _NTO_INTR_CLASS_SYNTHETIC interrupt you'll use; _NTO_INTR_SPARE is guaranteed not to match any valid logical interrupt vector number.

There can be additional interrupt classes defined for specific CPUs or embedded systems. For the interrupt assignments for specific boards, see the sample build files in ${KPDA_TARGET}/${PROCESSOR}/boot/build.

Interrupts and startup code

The mapping of logical interrupt vector numbers is completely dependent on the implementer of the startup code.

Device drivers must:

Typical x86 Interrupt vector numbers

The following list contains typical interrupt assignments for the 16 hardware interrupts on an x86-based PC using startup-bios:

Interrupt intr Description
0 A clock that runs at the resolution set by ClockPeriod()
1 Keyboard
2 Slave 8259 — you can't attach to this interrupt.
3 Com2
4 Com1
5 Net card / sound card / other
6 Floppy
7 Parallel printer / sound card / other
8
9 Remapped interrupt 2
10
11
12
13 Co-processor
14 Primary disk controller
15 Secondary disk controller


Note: The interrupt assignments are different for other boards.

Interrupt handler function

The function to call is specified by the handler argument. This function runs in the environment of your process, and the area and size arguments define a communications area in your process. This typically is a structure containing buffers and information needed by the handler and the process when it runs.


Note: The area argument can be NULL to indicate no communications area. If area is NULL, size should be 0.

The handler function's prototype is:

const struct sigevent * handler( void *area, int id );

Where area is a pointer to the area specified by the call to InterruptAttach(), and id is the ID returned by InterruptAttach().

Follow the following guidelines when writing your handler:

The return value of the handler function should be NULL or a pointer to a valid struct sigevent that the kernel delivers. These events are defined in <signal.h>.

Consider the following when choosing the event type:

Flags

The flags argument is a bitwise OR of the following values, or 0:

_NTO_INTR_FLAGS_END
_NTO_INTR_FLAGS_PROCESS
_NTO_INTR_FLAGS_TRK_MSK

_NTO_INTR_FLAGS_END

Put the new handler at the end of the list of existing handlers (for shared interrupts) instead of the start.

The interrupt structure allows hardware interrupts to be shared. For example, if two processes take over the same physical interrupt, both handlers are invoked consecutively. When a handler attaches, it's placed in front of any existing handlers for that interrupt and is called first. You can change this behavior by setting the _NTO_INTR_FLAGS_END flag in the flags argument. This adds the handler at the end of any existing handlers. Although the Neutrino microkernel allows full interrupt sharing, your hardware might not. For example, the ISA bus doesn't allow interrupt sharing, while the PCI bus does.

Processor interrupts are enabled during the execution of the handler. Don't attempt to talk to the interrupt controller chip. The operating system issues the end-of-interrupt command to the chip after processing all handlers at a given level.

The first process to attach to an interrupt unmasks the interrupt. When the last process detaches from an interrupt, the system masks it.

If the thread that attached the interrupt handler terminates without detaching the handler, the kernel does it automatically.

_NTO_INTR_FLAGS_PROCESS

Associate the handler with the process instead of the attaching thread.

Adding _NTO_INTR_FLAGS_PROCESS to flags associates the interrupt handler with the process instead of the attaching thread. The interrupt handler is removed when the process exits, instead of when the attaching thread exits.

_NTO_INTR_FLAGS_TRK_MSK

Track calls to InterruptMask() and InterruptUnmask() to make detaching the interrupt handler safer.

The _NTO_INTR_FLAGS_TRK_MSK flag and the id argument to InterruptMask() and InterruptUnmask() let the kernel track the number of times a particular interrupt handler or event has been masked. Then, when an application detaches from the interrupt, the kernel can perform the proper number of unmasks to ensure that the interrupt functions normally. This is important for shared interrupt levels.


Note: You should always set _NTO_INTR_FLAGS_TRK_MSK.

Состояния блокировки:

This call doesn't block.

Возвращаемое значение:

InterruptAttach()
Идентификатор обработчика прерываний. Если возникла ошибка функция возвращает -1, код ошибки записывается в errno.
InterruptAttach_r()
Идентификатор обработчика прерываний. Функция НЕ устанавливает errno. При возникновении ошибки функция возвращает один из представленных ниже кодов.

Use the function ID with the InterruptDetach() function to detach this interrupt handler.

Коды ошибок:

EAGAIN
All kernel interrupt entries are in use.
EFAULT
A fault occurred when the kernel tried to access the buffers provided.
EINVAL
The value of intr isn't a valid interrupt number.
EPERM
The process doesn't have I/O privileges.

Классификация:

ЗОСРВ «Нейтрино»

Точка остановки потока
Нет
Обработчик прерываний
Нет
Обработчик сигналов
Да
В потоке
Да

Предостережения:

If you're writing a resource manager and using the resmgr_*() functions with multiple threads, a thread that attaches to an interrupt must use _NTO_INTR_FLAGS_PROCESS in the flags argument when calling InterruptAttach().

If your interrupt handler isn't SMP-safe, you must lock it to one processor using:

ThreadCtl( _NTO_TCTL_RUNMASK, ... );

Тематические ссылки:

atomic_add(), atomic_clr(), atomic_set(), atomic_sub(), atomic_toggle(), InterruptAttachEvent(), InterruptDetach(), InterruptDisable(), InterruptEnable(), InterruptLock(), InterruptMask(), InterruptUnlock(), InterruptUnmask(), InterruptWait(), mlock(), struct sigevent, ThreadCtl(), TraceEvent()




Предыдущий раздел: Описание API системной библиотеки