system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-07-24 11:47:20 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

ithread(9): update functions to current day

Browse source 
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 2022-10-15 15:32:09 -03:00
parent 7d9dc91a99
commit 3cdbaee354
5 changed files with 87 additions and 120 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
ObsoleteFiles.inc
View file

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

13
share/man/man9/Makefile
View file

@ -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 \

170
share/man/man9/ithread.9 → share/man/man9/intr_event.9
View file

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

13
share/man/man9/socket.9
View file

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

2
share/man/man9/swi.9
View file

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