ithread_add_handler (9)

Leading comments

Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   docum...

(The comments found at the beginning of the groff file "man9/ithread_add_handler.9freebsd".)

NAME

ithread_add_handler ithread_create ithread_destroy ithread_priority ithread_remove_handler ithread_schedule - kernel interrupt threads

SYNOPSIS

In sys/param.h In sys/bus.h In sys/interrupt.h Ft int Fo ithread_add_handler Fa struct ithd *ithread Fa const char *name Fa driver_intr_t handler Fa void *arg Fa u_char pri Fa enum intr_type flags Fa void **cookiep Fc Ft int Fo ithread_create Fa struct ithd **ithread Fa int vector Fa int flags Fa void (*disable)(int) Fa void (*enable)(int) Fa const char *fmt Fa ... Fc Ft int Fn ithread_destroy struct ithd *ithread Ft u_char Fn ithread_priority enum intr_type flags Ft int Fn ithread_remove_handler void *cookie Ft int Fn ithread_schedule struct ithd *ithread int do_switch

DESCRIPTION

Interrupt threads are kernel threads that run a list of handlers when triggered by either a hardware or software interrupt. Each interrupt handler has a name, handler function, handler argument, priority, and various flags. Each interrupt thread maintains a list of handlers sorted by priority. This results in higher priority handlers being executed prior to lower priority handlers. Each thread assumes the priority of its highest priority handler for its process priority, or PRIO_MAX if it has no handlers. Interrupt threads are also associated with a single interrupt source, represented as a vector number.

The Fn ithread_create function creates a new interrupt thread. The Fa ithread argument points to an Vt struct ithd pointer that will point to the newly created thread upon success. The Fa vector argument specifies the interrupt source to associate this thread with. The Fa flags argument is a mask of properties of this thread. The only valid flag currently for Fn ithread_create is IT_SOFT to specify that this interrupt thread is a software interrupt. The Fa enable and Fa disable arguments specify optional functions used to enable and disable this interrupt thread's interrupt source. The functions receive the vector corresponding to the thread's interrupt source as their only argument. The remaining arguments form a printf(9) argument list that is used to build the base name of the new ithread. The full name of an interrupt thread is formed by concatenating the base name of an interrupt thread with the names of all of its interrupt handlers.

The Fn ithread_destroy function destroys a previously created interrupt thread by releasing its resources and arranging for the backing kernel thread to terminate. An interrupt thread can only be destroyed if it has no handlers remaining.

The Fn ithread_add_handler function adds a new handler to an existing interrupt thread specified by Fa ithread . The Fa name argument specifies a name for this handler. The Fa handler and Fa arg arguments provide the function to execute for this handler and an argument to pass to it. The Fa pri argument specifies the priority of this handler and is used both in sorting it in relation to the other handlers for this thread and to specify the priority of the backing kernel thread. The Fa flags argument can be used to specify properties of this handler as defined in In sys/bus.h . If Fa cookiep is not NULL then it will be assigned a cookie that can be used later to remove this handler.

The Fn ithread_remove_handler removes a handler from an interrupt thread. The Fa cookie argument specifies the handler to remove from its thread.

The Fn ithread_schedule function schedules an interrupt thread to run. If the Fa do_switch argument is non-zero and the interrupt thread is idle, then a context switch will be forced after putting the interrupt thread on the run queue.

The Fn ithread_priority function translates the INTR_TYPE_* interrupt flags into interrupt handler priorities.

The interrupt flags not related to the type of a particular interrupt (INTR_TYPE_* ) can be used to specify additional properties of both hardware and software interrupt handlers. The INTR_EXCL flag specifies that this handler cannot share an interrupt thread with another handler. The INTR_MPSAFE flag specifies that this handler is MP safe in that it does not need the Giant mutex to be held while it is executed. The INTR_ENTROPY flag specifies that the interrupt source this handler is tied to is a good source of entropy, and thus that entropy should be gathered when an interrupt from the handler's source triggers. Presently, the INTR_ENTROPY flag is not valid for software interrupt handlers.

It is not permitted to sleep in an interrupt thread; hence, any memory or zone allocations in an interrupt thread should be specified with the M_NOWAIT flag set. Any allocation errors must be handled thereafter.

RETURN VALUES

The Fn ithread_add_handler , Fn ithread_create , Fn ithread_destroy , Fn ithread_remove_handler , and Fn ithread_schedule functions return zero on success and non-zero on failure. The Fn ithread_priority function returns a process priority corresponding to the passed in interrupt flags.

EXAMPLES

The Fn swi_add function demonstrates the use of Fn ithread_create and Fn ithread_add_handler .

int
swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
            void *arg, int pri, enum intr_type flags, void **cookiep)
{
        struct proc *p;
        struct ithd *ithd;
        int error;

        if (flags & INTR_ENTROPY)
                return (EINVAL);

        ithd = (ithdp != NULL) ? *ithdp : NULL;

        if (ithd != NULL) {
                if ((ithd->it_flags & IT_SOFT) == 0)
                        return(EINVAL);
        } else {
                error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
                    "swi%d:", pri);
                if (error)
                        return (error);

                if (ithdp != NULL)
                        *ithdp = ithd;
        }
        return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
                    flags, cookiep));
}

ERRORS

The Fn ithread_add_handler function will fail if:

Bq Er EINVAL

Any of the Fa ithread , Fa handler , or Fa name arguments are NULL

Bq Er EINVAL

The INTR_EXCL flag is specified and the interrupt thread Fa ithread already has at least one handler, or the interrupt thread Fa ithread already has an exclusive handler.

Bq Er ENOMEM

Could not allocate needed memory for this handler.

The Fn ithread_create function will fail if:

Bq Er EAGAIN

The system-imposed limit on the total number of processes under execution would be exceeded. The limit is given by the sysctl(3) MIB variable KERN_MAXPROC

Bq Er EINVAL

A flag other than IT_SOFT was specified in the Fa flags parameter.

Bq Er ENOMEM

Could not allocate needed memory for this interrupt thread.

The Fn ithread_destroy function will fail if:

Bq Er EINVAL

The Fa ithread argument is NULL

Bq Er EINVAL

The interrupt thread pointed to by Fa ithread has at least one handler.

The Fn ithread_remove_handler function will fail if:

Bq Er EINVAL

The Fa cookie argument is NULL

The Fn ithread_schedule function will fail if:

Bq Er EINVAL

The Fa ithread argument is NULL

Bq Er EINVAL

The interrupt thread pointed to by Fa ithread has no interrupt handlers.

SEE ALSO

kthread(9), malloc(9), swi(9), uma(9)

HISTORY

Interrupt threads and their corresponding API first appeared in Fx 5.0 .

BUGS

Currently Vt struct ithd represents both an interrupt source and an interrupt thread. There should be a separate Vt struct isrc that contains a vector number, enable and disable functions, etc. that an ithread holds a reference to.