swi(9freebsd)
NAME
swi_add, swi_remove, swi_sched --- register and schedule software interrupt
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
handlers. 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 processing 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 interrupt 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
associate 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
specifies 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
execution 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
specifies 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.
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
handlers off of the same thread. clk_intr_event is used to hang delayed
handlers off of the clock software interrupt thread so that the
functionality 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
processes 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
exclusive 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>.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
