Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SWI(9)		       FreeBSD Kernel Developer's Manual		SWI(9)

NAME
     swi_add, swi_remove, swi_sched -- register	and schedule software inter-
     rupt handlers

SYNOPSIS
     #include <sys/param.h>
     #include <sys/bus.h>
     #include <sys/interrupt.h>

     extern struct intr_event *tty_intr_event;
     extern struct intr_event *clk_intr_event;
     extern void *vm_ih;

     int
     swi_add(struct intr_event **eventp, const char *name,
	 driver_intr_t handler,	void *arg, int pri, enum intr_type flags,
	 void **cookiep);

     int
     swi_remove(void *cookie);

     void
     swi_sched(void *cookie, int flags);

DESCRIPTION
     These functions are used to register and schedule software	interrupt han-
     dlers.  Software interrupt	handlers are attached to a software interrupt
     thread, just as hardware interrupt	handlers are attached to a hardware
     interrupt thread.	Multiple handlers can be attached to the same thread.
     Software interrupt	handlers can be	used to	queue up less critical pro-
     cessing inside of hardware	interrupt handlers so that the work can	be
     done at a later time.  Software interrupt threads are different from
     other kernel threads in that they are treated as an interrupt thread.
     This means	that time spent	executing these	threads	is counted as inter-
     rupt time,	and that they can be run via a lightweight context switch.

     The swi_add() function is used to add a new software interrupt handler to
     a specified interrupt event.  The eventp argument is an optional pointer
     to	a struct intr_event pointer.  If this argument points to an existing
     event that	holds a	list of	interrupt handlers, then this handler will be
     attached to that event.  Otherwise	a new event will be created, and if
     eventp is not NULL, then the pointer at that address to will be modified
     to	point to the newly created event.  The name argument is	used to	asso-
     ciate a name with a specific handler.  This name is appended to the name
     of	the software interrupt thread that this	handler	is attached to.	 The
     handler argument is the function that will	be executed when the handler
     is	scheduled to run.  The arg parameter will be passed in as the only
     parameter to handler when the function is executed.  The pri value	speci-
     fies the priority of this interrupt handler relative to other software
     interrupt handlers.  If an	interrupt event	is created, then this value is
     used as the vector, and the flags argument	is used	to specify the
     attributes	of a handler such as INTR_MPSAFE.  The cookiep argument	points
     to	a void * cookie.  This cookie will be set to a value that uniquely
     identifies	this handler, and is used to schedule the handler for execu-
     tion later	on.

     The swi_remove() function is used to teardown an interrupt	handler
     pointed to	by the cookie argument.	 It detaches the interrupt handler
     from the associated interrupt event and frees its memory.

     The swi_sched() function is used to schedule an interrupt handler and its
     associated	thread to run.	The cookie argument specifies which software
     interrupt handler should be scheduled to run.  The	flags argument speci-
     fies how and when the handler should be run and is	a mask of one or more
     of	the following flags:

     SWI_DELAY	Specifies that the kernel should mark the specified handler as
		needing	to run,	but the	kernel should not schedule the soft-
		ware interrupt thread to run.  Instead,	handler	will be	exe-
		cuted the next time that the software interrupt	thread runs
		after being scheduled by another event.	 Attaching a handler
		to the clock software interrupt	thread and using this flag
		when scheduling	a software interrupt handler can be used to
		implement the functionality performed by setdelayed() in ear-
		lier versions of FreeBSD.

     The tty_intr_event	and clk_intr_event variables contain pointers to the
     software interrupt	handlers for the tty and clock software	interrupts,
     respectively.  tty_intr_event is used to hang tty software	interrupt han-
     dlers off of the same thread.  clk_intr_event is used to hang delayed
     handlers off of the clock software	interrupt thread so that the function-
     ality of setdelayed() can be obtained in conjunction with SWI_DELAY.  The
     vm_ih handler cookie is used to schedule software interrupt threads to
     run for the VM subsystem.

RETURN VALUES
     The swi_add() and swi_remove() functions return zero on success and non-
     zero on failure.

ERRORS
     The swi_add() function will fail if:

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

     [EINVAL]		The flags argument specifies INTR_ENTROPY.

     [EINVAL]		The eventp argument points to a	hardware interrupt
			thread.

     [EINVAL]		Either of the name or handler arguments	are NULL.

     [EINVAL]		The INTR_EXCL flag is specified	and the	interrupt
			event pointed to by eventp already has at least	one
			handler, or the	interrupt event	already	has an exclu-
			sive handler.

     The swi_remove() function will fail if:

     [EINVAL]		A software interrupt handler pointed to	by cookie is
			NULL.

SEE ALSO
     ithread(9), taskqueue(9)

HISTORY
     The swi_add() and swi_sched() functions first appeared in FreeBSD 5.0.
     They replaced the register_swi() function which appeared in FreeBSD 3.0
     and the setsoft*(), and schedsoft*() functions which date back to at
     least 4.4BSD.  The	swi_remove() function first appeared in	FreeBSD	6.1.

BUGS
     Most of the global	variables described in this manual page	should not be
     global, or	at the very least should not be	declared in <sys/interrupt.h>.

FreeBSD	9.3			April 19, 2012			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=swi&sektion=9&manpath=FreeBSD+9.3-RELEASE>

home | help