From nobody Sun Oct 30 14:15:50 2022 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4N0dc630cVz4h0gV; Sun, 30 Oct 2022 14:15:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4N0dc62RTpz3sjV; Sun, 30 Oct 2022 14:15:50 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1667139350; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=7kvWVBOTBbURFFfqcgXO91qneKtCQVshcCurObHAxWI=; b=lQ1lyFotdcMcRjMu2xsauvCx9G69dxYzubzTSPho8mU0EQIzO2kFJCeynSl3y/cP6pyYcF gNW0KuEtPMlIbCeL2AuY6FTGSFNfKrmVIJ+S8lM25c9HXMosQMspwUIzH8fQnxGpanEQwD HGJQSsOeM56dkJOmRhrLmlCjV3Pypwg+gZayUIpSkkBcMTsa87CfiwGiE2xupbprXsI4yn PlEUzKVMcVXh0hwkecoYuZChmWV2WFoN2uisEWIb/awfB+GQO0JCEbh7+WyVyQwd/KDtbl fvEfLxQFCl1JuK0Np+4M2D7JOzpwY7jadCCsKgtmIc3NRqBCw3czkpwj4fZvbQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4N0dc61Rwhz108F; Sun, 30 Oct 2022 14:15:50 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 29UEFofG014723; Sun, 30 Oct 2022 14:15:50 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 29UEFoFq014722; Sun, 30 Oct 2022 14:15:50 GMT (envelope-from git) Date: Sun, 30 Oct 2022 14:15:50 GMT Message-Id: <202210301415.29UEFoFq014722@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Mitchell Horne Subject: git: 8f85514a2c41 - stable/13 - ithread(9): update functions to current day List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: mhorne X-Git-Repository: src X-Git-Refname: refs/heads/stable/13 X-Git-Reftype: branch X-Git-Commit: 8f85514a2c41c62a32271afa00158310e5cc30d0 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1667139350; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=7kvWVBOTBbURFFfqcgXO91qneKtCQVshcCurObHAxWI=; b=cf7Bm2zm/Z3Pjn+os1BALr+iuppMhp8QWhrECVyLadAYD6OMXD2aIcmnyt0L/aad483A/G MccZ0VKK0ZB4Dh66st70PEXSBswb2abhnscmRG2GQhBzHwmfbtm5r0r9qfBbxUHqSSMTuS ZvEeLzQoby7gUksxpungA0mNVm9a5yrro0BWJo16KpKIueUEJ3LZroctubzcwar2f90qCc ArZXyQltuQaJdKawrsCLB1L7R43KBxn1+v4HJ0dRBnRXQE+5PYA8HmQ/Nznf3mcYPhcHcI Qd06xCLDzq0c4clrKYot9k2KJcycQL9h7zw/j1ikkzNWaanhxoFPWf3K6cV75w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1667139350; a=rsa-sha256; cv=none; b=mcVaXJ7JDEXl1lFWdPiiO+TEa2NbAxu9TLZYaxI82FmSAP3rWg3s5t7z/JmzkpGlwRKPGI CoYfnmcwinHQnCSr38Zl5WEPGQeYSEsRREj239RhC6ywrXRQZuUNjUByZcfghDN44UTxec eQ2YEtrbeckQtUNjCSWxUmN160xtET0O1u0yrCOTzzpeOwK7mcJMw1geQdNGkiFsgguCdu icdq4mT8yEO2Sn0bXkISao/BjLp7jh2nGUfkdxzQOArhUlPaohsZ7FyGGy/uOFbag819wQ kzuejCzM8CEsvYClSweUJAa5z/6fe8p5GICZ4adHkr0LhHM7w0W5+jDbchqlhw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=8f85514a2c41c62a32271afa00158310e5cc30d0 commit 8f85514a2c41c62a32271afa00158310e5cc30d0 Author: Mitchell Horne AuthorDate: 2022-10-15 18:32:09 +0000 Commit: Mitchell Horne CommitDate: 2022-10-30 14:13:58 +0000 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 (cherry picked from commit 3cdbaee3548a6caa3ab7aca5788775057b1bd1fd) --- ObsoleteFiles.inc | 9 ++ share/man/man9/Makefile | 13 +-- share/man/man9/{ithread.9 => intr_event.9} | 170 +++++++++++------------------ share/man/man9/socket.9 | 13 +-- share/man/man9/swi.9 | 2 +- 5 files changed, 87 insertions(+), 120 deletions(-) diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc index 7677de19828f..1dac72154539 100644 --- a/ObsoleteFiles.inc +++ b/ObsoleteFiles.inc @@ -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 + # 20220615: new clang import which bumps version from 14.0.4 to 14.0.5 OLD_FILES+=usr/lib/clang/14.0.4/include/cuda_wrappers/algorithm OLD_FILES+=usr/lib/clang/14.0.4/include/cuda_wrappers/complex diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 9b4e3e388710..1aa72acc97b9 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -187,8 +187,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 \ @@ -1323,12 +1323,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 kernel_vmount.9 \ diff --git a/share/man/man9/ithread.9 b/share/man/man9/intr_event.9 similarity index 72% rename from share/man/man9/ithread.9 rename to share/man/man9/intr_event.9 index 2a2e44f3d6af..b735da931f64 100644 --- a/share/man/man9/ithread.9 +++ b/share/man/man9/intr_event.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" -.Ft u_char -.Fn ithread_priority "enum intr_type flags" -.Ft int -.Fn ithread_remove_handler "void *cookie" +.Fn intr_event_destroy "struct intr_event *ie" .Ft int -.Fn ithread_schedule "struct ithd *ithread" "int do_switch" +.Fn intr_event_remove_handler "void *cookie" +.Ft u_char +.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. diff --git a/share/man/man9/socket.9 b/share/man/man9/socket.9 index 1c3f75785013..3c24efb75dc9 100644 --- a/share/man/man9/socket.9 +++ b/share/man/man9/socket.9 @@ -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 diff --git a/share/man/man9/swi.9 b/share/man/man9/swi.9 index d76793ec0bf3..6875fc890696 100644 --- a/share/man/man9/swi.9 +++ b/share/man/man9/swi.9 @@ -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