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

FreeBSD Manual Pages


home | help
SWI(9)			 BSD Kernel Developer's	Manual			SWI(9)

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

     #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;

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

     swi_remove(void *cookie);

     swi_sched(void *cookie, int flags);

     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 pa-
     rameter 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 at-
     tributes 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
		  software interrupt thread to run.  Instead, handler will be
		  executed 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 earlier versions of FreeBSD.

     SWI_FROMNMI  Specifies that swi_sched() is	called from NMI	context	and
		  should be careful about used KPIs.  On platforms allowing
		  IPI sending from NMI context it immediately wakes
		  clk_intr_event via the IPI, otherwise	it works just like

     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.

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

     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

     [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

     ithread(9), taskqueue(9)

     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.

     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>.

BSD				 July 25, 2020				   BSD


Want to link to this manual page? Use this URL:

home | help