From nobody Sun Oct 30 14:15:52 2022 X-Original-To: dev-commits-src-branches@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 4N0dc85pwtz4h0nx; Sun, 30 Oct 2022 14:15:52 +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 4N0dc84t4tz3t3F; Sun, 30 Oct 2022 14:15:52 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1667139352; 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=hxW7mCd2ebraWn/KyTRaoSqwaze4W50byh3XknyE1XI=; b=b4FgJfL+EDys4vXVQQXV5h1h9dXmGDoVHNI4Byyia/w9vD5Iu4E/71RtA87D7AQ0jBm3Be iggxUK0V9JS9WM6xWosfE9FeHguCdzVwjlODr79kZTRHGuFh2n2Pbl53WlFTdlHcoTh1qU lRjh1Jo5fdLwujnqOapSsT8iDBC/ZJZb7ntaXpUt7jEnKTFpwsF2a4wBB46aMqZLaq3gMl sdDDgVogolI1rWBfFfq5+DaHd1LOadnG1kvmglxV0HZ5kak8ZMBP+S/566jIWFF0ca4mO+ fJgyCPrBNFgtNhlTrUOZgU9Y5K8Fe2Wl2BgfUd95vpM8vwjpzLPlM9cq81goYg== 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 4N0dc83fX0z10X0; Sun, 30 Oct 2022 14:15:52 +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 29UEFqZv014779; Sun, 30 Oct 2022 14:15:52 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 29UEFqVi014778; Sun, 30 Oct 2022 14:15:52 GMT (envelope-from git) Date: Sun, 30 Oct 2022 14:15:52 GMT Message-Id: <202210301415.29UEFqVi014778@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: da82ab9801fb - stable/13 - intr_event(9): update top-level description List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-branches@freebsd.org X-BeenThere: dev-commits-src-branches@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: da82ab9801fb394e085752af4a0e88c4d42a902c Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1667139352; 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=hxW7mCd2ebraWn/KyTRaoSqwaze4W50byh3XknyE1XI=; b=aI+7cCt/uTzsPMzeZ6CfdiAAHHNEHV0LFjNTyyG6BYfXPYvGHJNwsvjOHO8JxhrooU18CZ ZxnN9Cf+j1TwJwx45QrhFxpukH6bwVVSckdq73mIqxGCOoxnElOSs9T1qFUyiN8SlsCOXL P/SHy22lRG3lyK0YyGOJ+oLjYBSO4yMl68mAslFUHcxHcq+6Tcb4NNFgR8dZ0Ws3VBoZUQ 3O3wnIhhKxULM472XE3ENkGiPW0XQqDe00Nn5820kKL60QRUjK2m/UkiNz/UVHZMfoTkNB h/MfJqAtVrgvtTpbZWTZMwT0n04nJu0OPDktAnifVpfor6At1VgzxiRra7/hWA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1667139352; a=rsa-sha256; cv=none; b=jlF4zZEEzPE+LOvEnT6GT/S4futPxyH+3jybr5MydATb7ST1MTHag3DWNb4/4maWsGBejP 4l7n0Y6rTjS1JnRK58b43pwF6QMYjBGDN2QyGCF+57sVYw+bzrWfkqq5xGAzzGsgLWivbH l9+gLidFpdd/mNi0h54a+bY3H3NheVjiE74vstd/+HY0DmSq4nJqTwpquKqxom1hq5VwfM 9KGYgmkYOOWWPwNtCD20UUYZ1ZWGtuUrZDBsjgQ8bukQ8v3QXq1234Ne0sWdhRiVIvFU4L C3Ep/6uHR3t1tp8zNQVm6Rq9SP61SfSrZSZY1BPUe5hkVjjVS6XkuCtQqgkS0A== 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=da82ab9801fb394e085752af4a0e88c4d42a902c commit da82ab9801fb394e085752af4a0e88c4d42a902c Author: Mitchell Horne AuthorDate: 2022-10-15 18:38:02 +0000 Commit: Mitchell Horne CommitDate: 2022-10-30 14:14:37 +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 (cherry picked from commit dfc91493abc6046fc6cb237e48fd952deee358e0) --- 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