From nobody Sat Oct 15 18:52:07 2022 X-Original-To: dev-commits-src-main@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 4MqXRq5x8Sz4fTYd; Sat, 15 Oct 2022 18:52:07 +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 4MqXRq5Bpyz49fl; Sat, 15 Oct 2022 18:52:07 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1665859927; 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=3hxwmPen3gO6w12ToDPFnGJax5P7k+88nepsigZGJXA=; b=msZb0mtDldEfYQrjbYfoXyyoIo9UFduK8wOHRT0y2meZKr1KbamuZAHiLQ/hinvs6Syrei q2XBJB50B0/qGYoJ8UfROlh2T/FZo/UOy05perhJdNLpa6IR/PvXNXkD2Sc0ggv9Hxt5D3 UwTunC+M6ytyF4SJ6kd516Pmr7sqaL2sPqFTd7JzEYO3PB6uOzAQG8lgbEhlOZdC3xE8e8 TIad/IVo3VxmnGoUCND/AwVzi1Cz+DlnegcrRfssMGCa4tmCNx4y1d9/I64auSw3anCnaA qibGTW/8sYs/H6sKLTuugwj535kmZkIus5UqSXTgT9mU+bHF8oNpfILH3JaSAg== 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 4MqXRq4JM4z1CZg; Sat, 15 Oct 2022 18:52:07 +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 29FIq70t060158; Sat, 15 Oct 2022 18:52:07 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 29FIq7f7060157; Sat, 15 Oct 2022 18:52:07 GMT (envelope-from git) Date: Sat, 15 Oct 2022 18:52:07 GMT Message-Id: <202210151852.29FIq7f7060157@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mitchell Horne Subject: git: dfc91493abc6 - main - intr_event(9): update top-level description List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@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/main X-Git-Reftype: branch X-Git-Commit: dfc91493abc6046fc6cb237e48fd952deee358e0 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1665859927; 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=3hxwmPen3gO6w12ToDPFnGJax5P7k+88nepsigZGJXA=; b=EtrxeOra7PfZ1YkHlU7bz2LLbZouedDXZoe/eCZKIZORNCCQmdSY1VV0HWI+ymk2ZrBnSL qIN7+R3cb2+ZU/wa5tN5TJJhfL8EqEaqpkjHbcOZLtVkas5Lfm/d7e3ou8L2DeZnzFrZKd vnIKMe3mSjAS/Cy5yhOnllhhikLzV8xYlC0rv0VmA4hPCne7yrKFL6pDy+tn4vf+Ikp1za luqaSXiOAFzqYIE8+mTMC+PirmRXs6niPWDSi7NbrcwmidaduDcDFRNZEEC/9LjiQeQb7C EyI4jY6XQymDvkU54XUskkjGr9e5j1PzyQgVaH7LXWFUoePtiurLYFE08wixiQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1665859927; a=rsa-sha256; cv=none; b=t2Bg1NCxI3bhGeAy5b+a0lHkAW9DIKCTL3zeIszukYbAHjFJgR1gXCCkvu98SMhByyI7zu ExxyCBkEzUPrxxfarhPd7wh07eaxPF1Ty80nMKZogzUM+P4A7zFMKozNbsnHsY408d63uU zE2cPkw/3By/pOOFrtd9Rz0ziztw/xdkDDpr8f8aauAdFCqelHldmlnOa0hTabHwBLeQiU ptmkzeCTL+NJrtmI1NY5w0TsGJkBmgSpCq4RyBqvxxRrxK9v1Gyb7j2j3n4lJKN1vmyfVB +/3NxzcHRyFFtloe7nNCs3PQn20jwFWSo0KVkH2pZhP42mCdz5SRQCi/v4wvQw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=dfc91493abc6046fc6cb237e48fd952deee358e0 commit dfc91493abc6046fc6cb237e48fd952deee358e0 Author: Mitchell Horne AuthorDate: 2022-10-15 18:38:02 +0000 Commit: Mitchell Horne CommitDate: 2022-10-15 18:50:25 +0000 intr_event(9): update top-level description The ithread has been subsumed by the 'interrupt event' object, so update the description to reflect this by describing an interrupt event and its contents. We've also moved on from having a single handler function to the split filter-and-handler model. Explain the purpose and constraints of these two types of handlers. Reviewed by: jhb, pauamma MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D33477 --- share/man/man9/intr_event.9 | 79 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 60 insertions(+), 19 deletions(-) diff --git a/share/man/man9/intr_event.9 b/share/man/man9/intr_event.9 index 621a02e3967b..18423f283ad9 100644 --- a/share/man/man9/intr_event.9 +++ b/share/man/man9/intr_event.9 @@ -68,21 +68,67 @@ .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. -Each interrupt handler has a name, handler function, handler argument, -priority, and various flags. -Each interrupt thread maintains a list of handlers sorted by priority. -This results in higher priority handlers being executed prior to lower -priority handlers. -Each thread assumes the priority of its highest priority handler for its -process priority, or -.Dv PRIO_MAX -if it has no handlers. -Interrupt threads are also associated with a single interrupt source, -represented as a vector number. +The interrupt event API provides methods to manage the registration and +execution of interrupt handlers and their associated thread contexts. +.Pp +Each interrupt event in the system corresponds to a single hardware or software +interrupt source. +Each interrupt event maintains a list of interrupt handlers, sorted by +priority, which will be invoked when handling the event. +An interrupt event will typically, but not always, have an associated +.Xr kthread 9 , +known as the interrupt thread. +Finally, each event contains optional callback functions which will be +invoked before and after the handler functions themselves. +.Pp +An interrupt handler contains two distinct handler functions: +the +.Em filter +and the thread +.Em handler . +The +.Em filter +function is run from interrupt context and is intended to perform quick +handling such as acknowledging or masking a hardware interrupt, +and queueing work for the ensuing thread +.Em handler . +Both functions are optional; each interrupt handler may choose to register a +filter, a thread handler, or both. +Each interrupt handler also consists of a name, +a set of flags, +and an opaque argument which will be passed to both the +.Em filter +and +.Em handler +functions. +.Ss Handler Constraints +The +.Em filter +function is executed inside a +.Xr critical 9 +section. +Therefore, filters may not yield the CPU for any reason, and may only use spin +locks to access shared data. +Allocating memory within a filter is not permitted. .Pp The +.Em handler +function executes from the context of the associated interrupt kernel thread. +Sleeping is not permitted, but the interrupt thread may be preempted by higher +priority threads. +Thus, threaded handler functions may obtain non-sleepable locks, as described +in +.Xr locking 9 . +Any memory or zone allocations in an interrupt thread must specify the +.Dv M_NOWAIT +flag, and any allocation errors must be handled. +.Pp +The exception to these constraints is software interrupt threads, which are +allowed to sleep but should be allocated and scheduled using the +.Xr swi 9 +interface. +.Ss Function Descriptions +The .Fn intr_event_create function creates a new interrupt thread. The @@ -180,12 +226,6 @@ from the handler's source triggers. Presently, the .Dv INTR_ENTROPY flag is not valid for software interrupt handlers. -.Pp -It is not permitted to sleep in an interrupt thread; hence, any memory -or zone allocations in an interrupt thread should be specified with the -.Dv M_NOWAIT -flag set. -Any allocation errors must be handled thereafter. .Sh RETURN VALUES The .Fn intr_event_add_handler , @@ -305,6 +345,7 @@ argument is .El .Sh SEE ALSO .Xr kthread 9 , +.Xr locking 9 , .Xr malloc 9 , .Xr swi 9 , .Xr uma 9