mirror of
https://git.FreeBSD.org/src.git
synced 2025-01-30 16:51:41 +00:00
ithread(9): update functions to current day
The public KPI is now intr_event_**, - Convert existing documented functions to their equivalents. - Fix up the function arguments - Fix up the possible error return values for each - Remove ithread_schedule() completely - Rename man page to intr_event(9) - Update cross-references Future changes will update the descriptive text for these functions. PR: 100803 Based on work by: trhodes Reviewed by: jhb MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D33475
This commit is contained in:
Mitchell Horne
parent
7d9dc91a99
commit
3cdbaee354
@ -52,6 +52,15 @@
|
||||
# xargs -n1 | sort | uniq -d;
|
||||
# done
|
||||
|
||||
# 20221015: update the ithread(9) man page
|
||||
OLD_FILES+=usr/share/man/man9/ithread.9.gz
|
||||
OLD_FILES+=usr/share/man/man9/ithread_add_handler.9.gz
|
||||
OLD_FILES+=usr/share/man/man9/ithread_create.9.gz
|
||||
OLD_FILES+=usr/share/man/man9/ithread_destroy.9.gz
|
||||
OLD_FILES+=usr/share/man/man9/ithread_priority.9.gz
|
||||
OLD_FILES+=usr/share/man/man9/ithread_remove_handler.9.gz
|
||||
OLD_FILES+=usr/share/man/man9/ithread_schedule.9.gz
|
||||
|
||||
# 20221012: remove nls support from sort
|
||||
OLD_FILES+=usr/share/nls/hu_HU.ISO8859-2/sort.cat
|
||||
|
||||
|
||||
@ -190,8 +190,8 @@ MAN= accept_filter.9 \
|
||||
ifnet.9 \
|
||||
inittodr.9 \
|
||||
insmntque.9 \
|
||||
intr_event.9 \
|
||||
intro.9 \
|
||||
ithread.9 \
|
||||
kasan.9 \
|
||||
KASSERT.9 \
|
||||
kern_reboot.9 \
|
||||
@ -1319,12 +1319,11 @@ MLINKS+=ifnet.9 if_addmulti.9 \
|
||||
ifnet.9 ifunit.9 \
|
||||
ifnet.9 ifunit_ref.9
|
||||
MLINKS+=insmntque.9 insmntque1.9
|
||||
MLINKS+=ithread.9 ithread_add_handler.9 \
|
||||
ithread.9 ithread_create.9 \
|
||||
ithread.9 ithread_destroy.9 \
|
||||
ithread.9 ithread_priority.9 \
|
||||
ithread.9 ithread_remove_handler.9 \
|
||||
ithread.9 ithread_schedule.9
|
||||
MLINKS+=intr_event.9 intr_event_add_handler.9 \
|
||||
intr_event.9 intr_event_create.9 \
|
||||
intr_event.9 intr_event_destroy.9 \
|
||||
intr_event.9 intr_event_remove_handler.9 \
|
||||
intr_event.9 intr_priority.9
|
||||
MLINKS+=kernacc.9 useracc.9
|
||||
MLINKS+=kernel_mount.9 free_mntarg.9 \
|
||||
kernel_mount.9 mount_arg.9 \
|
||||
|
||||
@ -23,25 +23,25 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd August 25, 2006
|
||||
.Dt ITHREAD 9
|
||||
.Dd October 15, 2022
|
||||
.Dt INTR_EVENT 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm ithread_add_handler ,
|
||||
.Nm ithread_create ,
|
||||
.Nm ithread_destroy ,
|
||||
.Nm ithread_priority ,
|
||||
.Nm ithread_remove_handler ,
|
||||
.Nm ithread_schedule
|
||||
.Nd kernel interrupt threads
|
||||
.Nm intr_event_add_handler ,
|
||||
.Nm intr_event_create ,
|
||||
.Nm intr_event_destroy ,
|
||||
.Nm intr_event_remove_handler ,
|
||||
.Nm intr_priority
|
||||
.Nd "kernel interrupt handler and thread API"
|
||||
.Sh SYNOPSIS
|
||||
.In sys/param.h
|
||||
.In sys/bus.h
|
||||
.In sys/interrupt.h
|
||||
.Ft int
|
||||
.Fo ithread_add_handler
|
||||
.Fa "struct ithd *ithread"
|
||||
.Fo intr_event_add_handler
|
||||
.Fa "struct intr_event *ie"
|
||||
.Fa "const char *name"
|
||||
.Fa "driver_filter_t filter"
|
||||
.Fa "driver_intr_t handler"
|
||||
.Fa "void *arg"
|
||||
.Fa "u_char pri"
|
||||
@ -49,23 +49,24 @@
|
||||
.Fa "void **cookiep"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fo ithread_create
|
||||
.Fa "struct ithd **ithread"
|
||||
.Fa "int vector"
|
||||
.Fo intr_event_create
|
||||
.Fa "struct intr_event **event"
|
||||
.Fa "void *source"
|
||||
.Fa "int flags"
|
||||
.Fa "void (*disable)(int)"
|
||||
.Fa "void (*enable)(int)"
|
||||
.Fa "int irq"
|
||||
.Fa "void (*pre_ithread)(void *)"
|
||||
.Fa "void (*post_ithread)(void *)"
|
||||
.Fa "void (*post_filter)(void *)"
|
||||
.Fa "int (*assign_cpu)(void *, int)"
|
||||
.Fa "const char *fmt"
|
||||
.Fa "..."
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fn ithread_destroy "struct ithd *ithread"
|
||||
.Fn intr_event_destroy "struct intr_event *ie"
|
||||
.Ft int
|
||||
.Fn intr_event_remove_handler "void *cookie"
|
||||
.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"
|
||||
.Fn intr_priority "enum intr_type flags"
|
||||
.Sh DESCRIPTION
|
||||
Interrupt threads are kernel threads that run a list of handlers when
|
||||
triggered by either a hardware or software interrupt.
|
||||
@ -82,23 +83,20 @@ Interrupt threads are also associated with a single interrupt source,
|
||||
represented as a vector number.
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_create
|
||||
.Fn intr_event_create
|
||||
function creates a new interrupt thread.
|
||||
The
|
||||
.Fa ithread
|
||||
argument points to an
|
||||
.Vt struct ithd
|
||||
.Fa source
|
||||
argument points to a
|
||||
.Vt struct intr_event event
|
||||
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
|
||||
.Fn intr_event_create
|
||||
is
|
||||
.Dv IT_SOFT
|
||||
.Dv IE_SOFT
|
||||
to specify that this interrupt thread is a software interrupt.
|
||||
The
|
||||
.Fa enable
|
||||
@ -110,18 +108,18 @@ The functions receive the vector corresponding to the thread's interrupt
|
||||
source as their only argument.
|
||||
The remaining arguments form a
|
||||
.Xr printf 9
|
||||
argument list that is used to build the base name of the new ithread.
|
||||
argument list that is used to build the base name of the new interrupt thread.
|
||||
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.
|
||||
name of the interrupt thread with the names of all of its interrupt handlers.
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_destroy
|
||||
.Fn intr_event_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.
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_add_handler
|
||||
.Fn intr_event_add_handler
|
||||
function adds a new handler to an existing interrupt thread specified by
|
||||
.Fa ithread .
|
||||
The
|
||||
@ -150,25 +148,17 @@ then it will be assigned a cookie that can be used later to remove this
|
||||
handler.
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_remove_handler
|
||||
.Fn intr_event_remove_handler
|
||||
removes a handler from an interrupt thread.
|
||||
The
|
||||
.Fa cookie
|
||||
argument specifies the handler to remove from its thread.
|
||||
.Pp
|
||||
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.
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_priority
|
||||
.Fn intr_priority
|
||||
function translates the
|
||||
.Dv INTR_TYPE_*
|
||||
interrupt flags into interrupt handler priorities.
|
||||
interrupt flags into interrupt thread scheduling priorities.
|
||||
.Pp
|
||||
The interrupt flags not related to the type of a particular interrupt
|
||||
.Pq Dv INTR_TYPE_*
|
||||
@ -198,24 +188,23 @@ flag set.
|
||||
Any allocation errors must be handled thereafter.
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn ithread_add_handler ,
|
||||
.Fn ithread_create ,
|
||||
.Fn ithread_destroy ,
|
||||
.Fn ithread_remove_handler ,
|
||||
.Fn intr_event_add_handler ,
|
||||
.Fn intr_event_create ,
|
||||
.Fn intr_event_destroy ,
|
||||
and
|
||||
.Fn ithread_schedule
|
||||
.Fn intr_event_remove_handler
|
||||
functions return zero on success and non-zero on failure.
|
||||
The
|
||||
.Fn ithread_priority
|
||||
.Fn intr_priority
|
||||
function returns a process priority corresponding to the passed in interrupt
|
||||
flags.
|
||||
.Sh EXAMPLES
|
||||
The
|
||||
.Fn swi_add
|
||||
function demonstrates the use of
|
||||
.Fn ithread_create
|
||||
.Fn intr_event_create
|
||||
and
|
||||
.Fn ithread_add_handler .
|
||||
.Fn intr_event_add_handler .
|
||||
.Bd -literal -offset indent
|
||||
int
|
||||
swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
|
||||
@ -248,67 +237,63 @@ swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
|
||||
.Ed
|
||||
.Sh ERRORS
|
||||
The
|
||||
.Fn ithread_add_handler
|
||||
.Fn intr_event_add_handler
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
Any of the
|
||||
.Fa ithread ,
|
||||
.Fa handler ,
|
||||
The
|
||||
.Fa ie
|
||||
or
|
||||
.Fa name
|
||||
arguments are
|
||||
.Dv NULL .
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Dv INTR_EXCL
|
||||
.Fa handler
|
||||
and
|
||||
.Fa filter
|
||||
arguments are both
|
||||
.Dv NULL .
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Dv IH_EXCLUSIVE
|
||||
flag is specified and the interrupt thread
|
||||
.Fa ithread
|
||||
.Fa ie
|
||||
already has at least one handler, or the interrupt thread
|
||||
.Fa ithread
|
||||
.Fa ie
|
||||
already has an exclusive handler.
|
||||
.It Bq Er ENOMEM
|
||||
Could not allocate needed memory for this handler.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_create
|
||||
.Fn intr_event_create
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EAGAIN
|
||||
The system-imposed limit on the total
|
||||
number of processes under execution would be exceeded.
|
||||
The limit is given by the
|
||||
.Xr sysctl 3
|
||||
MIB variable
|
||||
.Dv KERN_MAXPROC .
|
||||
.It Bq Er EINVAL
|
||||
A flag other than
|
||||
.Dv IT_SOFT
|
||||
.Dv IE_SOFT
|
||||
was specified in the
|
||||
.Fa flags
|
||||
parameter.
|
||||
.It Bq Er ENOMEM
|
||||
Could not allocate needed memory for this interrupt thread.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_destroy
|
||||
.Fn intr_event_destroy
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Fa ithread
|
||||
.Fa ie
|
||||
argument is
|
||||
.Dv NULL .
|
||||
.It Bq Er EINVAL
|
||||
The interrupt thread pointed to by
|
||||
.Fa ithread
|
||||
has at least one handler.
|
||||
.It Bq Er EBUSY
|
||||
The interrupt event pointed to by
|
||||
.Fa ie
|
||||
has at least one handler which has not been removed with
|
||||
.Fn intr_event_remove_handler .
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_remove_handler
|
||||
.Fn intr_event_remove_handler
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
@ -317,21 +302,6 @@ The
|
||||
argument is
|
||||
.Dv NULL .
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn ithread_schedule
|
||||
function will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Fa ithread
|
||||
argument is
|
||||
.Dv NULL .
|
||||
.It Bq Er EINVAL
|
||||
The interrupt thread pointed to by
|
||||
.Fa ithread
|
||||
has no interrupt handlers.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr kthread 9 ,
|
||||
.Xr malloc 9 ,
|
||||
@ -340,11 +310,3 @@ has no interrupt handlers.
|
||||
.Sh HISTORY
|
||||
Interrupt threads and their corresponding API first appeared in
|
||||
.Fx 5.0 .
|
||||
.Sh 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.
|
||||
@ -26,7 +26,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd October 18, 2018
|
||||
.Dd September 6, 2022
|
||||
.Dt SOCKET 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -171,8 +171,7 @@ are only useful for protocol implementors.
|
||||
.Pp
|
||||
Except where otherwise indicated,
|
||||
.Nm
|
||||
functions may sleep, and are not appropriate for use in an
|
||||
.Xr ithread 9
|
||||
functions may sleep, and are not appropriate for use in an interrupt thread
|
||||
context or while holding non-sleepable kernel locks.
|
||||
.Ss Creating and Destroying Sockets
|
||||
A new socket may be created using
|
||||
@ -461,10 +460,8 @@ argument, and use the same flag name space as the
|
||||
.Xr sendmsg 2
|
||||
system call.
|
||||
.Pp
|
||||
Kernel callers running in
|
||||
.Xr ithread 9
|
||||
context, or with a mutex held, will wish to use non-blocking sockets and pass
|
||||
the
|
||||
Kernel callers running in an interrupt thread context, or with a mutex held,
|
||||
will wish to use non-blocking sockets and pass the
|
||||
.Dv MSG_DONTWAIT
|
||||
flag in order to prevent these functions from sleeping.
|
||||
.Pp
|
||||
@ -593,7 +590,7 @@ data between user and kernel code.
|
||||
.Xr shutdown 2 ,
|
||||
.Xr socket 2 ,
|
||||
.Xr ng_ksocket 4 ,
|
||||
.Xr ithread 9 ,
|
||||
.Xr intr_event 9 ,
|
||||
.Xr msleep 9 ,
|
||||
.Xr ucred 9
|
||||
.Sh HISTORY
|
||||
|
||||
@ -208,7 +208,7 @@ is
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr hardclock 9 ,
|
||||
.Xr ithread 9 ,
|
||||
.Xr intr_event 9 ,
|
||||
.Xr taskqueue 9
|
||||
.Sh HISTORY
|
||||
The
|
||||
|
||||
Loading…
Reference in New Issue
Block a user