From nobody Sun Oct 30 14:15:53 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 4N0dcB0wbsz4h0p3; Sun, 30 Oct 2022 14:15:54 +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 4N0dc95YRrz3t3Z; Sun, 30 Oct 2022 14:15:53 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1667139353; 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=gGsJRIugxdR4hNwKybpSaC2PhJeAc9FbYRGfrIXJ9hs=; b=QB6+CVsUuCNodLOiHwPsRI3O7x81S9Fv6hO0bgmfGMQnRYmAZmwIcZcxL2SMNSwCRfIOZC hgHD9qP0QaP4sNVob75wg+hvGeGW0yhODX7TZPXiHrkY6j6BWvpfvFXK/jr8pv0gFrMM32 oOEj50qsq4Ksrww8rS7CXoT/20EaPD2pEkMWxNc9jkU1yx/k8ZtyB23xxFSTx26SxpyEX0 73mLCKtt9PB6NdPy8daQu5zUHI04mEa6fwFXscyB99drRdiEwnKDcrjTrWT+uh7uUzqtoB Ur7AE4cyV2096B24SDc9xpiEc8BMq65tZ87WdX3V3xeKMNA77ESO3VSBBDsPkg== 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 4N0dc94RZxz10CS; Sun, 30 Oct 2022 14:15:53 +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 29UEFr0M014808; Sun, 30 Oct 2022 14:15:53 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 29UEFrKg014807; Sun, 30 Oct 2022 14:15:53 GMT (envelope-from git) Date: Sun, 30 Oct 2022 14:15:53 GMT Message-Id: <202210301415.29UEFrKg014807@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: fa2462f03c3c - stable/13 - intr_event(9): update existing function descriptions 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: fa2462f03c3c5434b3ee04472deca2d3308ca2fa Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1667139353; 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=gGsJRIugxdR4hNwKybpSaC2PhJeAc9FbYRGfrIXJ9hs=; b=TJQJUzm+0HIaix7gSNb8iuAcgBWz2JLHNV3Fx05nRqiJPABBloR9lyM8p5wOOLUv9ev08v 3d0KzdzyVJrfKJaPc/FNQJKkrsaZR6sOYyzFYKpbOhXQTnF548mCn714LvjjUOKWEpL2xr QBFuGBRrQzuSaFZR7d6BGLKpSqJYz5PeNeZcnU5ro1w9SZAqsdlYdeKwNEGE3jlFWkhQkX 1GHQeCpv8etTXoLKupYxHSqtel+osK/TISoxakt3gOHU+Ey0poAgnSVjzsQdFsZDGi+9sS k4S80TCXjdBPOIqxaqFs+xVJHfESiTUpnXSd8oq4PLiD22M4432z8H6intzw3w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1667139353; a=rsa-sha256; cv=none; b=OBMF9WOJ9yl0cCDt6RzHKu8xXQruNvfRlhdP1aNXmUXiadgQjaSGuESMl7z7mGA9ReJJOI 925zCnwIGubkQqsm7JQrCXWhh3GnJ6ME2JJfwuMxjP2RbWsd6TJJ8RmL3p/TaG9bRoloT8 Wr2QTMCtCpGl0x+EPk+eGkImQClpAOfCtW3RENfI1g3R7MVRgiKMWOqrUdOfrvssAGc3Wy d8ugJr0pGyOJdQd+iZ3upX+YuamneAlUKcMafj00x21lOoKwAuFe1O3xM/W9RSza9XcrFV Dt5SheUiWQF8SENsjevrimn57wRfJ3k3SYPNrDqfNheS5/zZ5a2BSxaxG1wN3Q== 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=fa2462f03c3c5434b3ee04472deca2d3308ca2fa commit fa2462f03c3c5434b3ee04472deca2d3308ca2fa Author: Mitchell Horne AuthorDate: 2022-10-15 18:39:27 +0000 Commit: Mitchell Horne CommitDate: 2022-10-30 14:15:12 +0000 intr_event(9): update existing function descriptions Document new arguments and behaviours for these functions as compared to the old ithread_* versions. Reviewed by: pauamma Input from: jhb MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D33478 (cherry picked from commit cb9425e21c917732fb16bd14947cba01f26687f3) --- share/man/man9/intr_event.9 | 118 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 97 insertions(+), 21 deletions(-) diff --git a/share/man/man9/intr_event.9 b/share/man/man9/intr_event.9 index 18423f283ad9..8ca42892dd8f 100644 --- a/share/man/man9/intr_event.9 +++ b/share/man/man9/intr_event.9 @@ -130,12 +130,20 @@ interface. .Ss Function Descriptions The .Fn intr_event_create -function creates a new interrupt thread. +function creates a new interrupt event. The -.Fa source +.Fa event argument points to a -.Vt struct intr_event event -pointer that will point to the newly created thread upon success. +.Vt struct intr_event +pointer that will reference the newly created event upon success. +The +.Fa source +argument is an opaque pointer which will be passed to the +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter +callbacks. The .Fa flags argument is a mask of properties of this thread. @@ -150,9 +158,31 @@ and .Fa disable arguments specify optional functions used to enable and disable this interrupt thread's interrupt source. -The functions receive the vector corresponding to the thread's interrupt -source as their only argument. -The remaining arguments form a +The +.Fa irq +argument is the unique interrupt vector number corresponding to the event. +The +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter +arguments are callback functions that are invoked at different +points while handling an interrupt. +This is described in more detail in the +.Sx Handler Callbacks +section, below. +They may be +.Va NULL +to specify no callback. +The +.Fa assign_cpu +argument points to a callback function that will be invoked when binding +an interrupt to a particular CPU. +It may be +.Va NULL +if binding is unsupported. +The +remaining arguments form a .Xr printf 9 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 @@ -160,29 +190,41 @@ name of the interrupt thread with the names of all of its interrupt handlers. .Pp The .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. +function destroys a previously created interrupt event by releasing its +resources. +.\" The following is not true (yet): +.\"and arranging for the backing kernel thread to terminate. +An interrupt event can only be destroyed if it has no handlers remaining. .Pp The .Fn intr_event_add_handler -function adds a new handler to an existing interrupt thread specified by -.Fa ithread . +function adds a new handler to an existing interrupt event specified by +.Fa ie . The .Fa name argument specifies a name for this handler. The +.Fa filter +argument provide the filter function to execute. +The .Fa handler -and +argument provides the handler function to be executed from the +event's interrupt thread. +The .Fa arg -arguments provide the function to execute for this handler and an argument -to pass to it. +argument will be passed to the +.Fa filter +and +.Fa handler +functions when they are invoked. The .Fa pri -argument specifies the priority of this handler and is used both in sorting -it in relation to the other handlers for this thread and to specify the -priority of the backing kernel thread. -The +argument specifies the priority of this handler, +corresponding to the values defined in +.In sys/priority.h . +It determines the order this handler is called relative to the other handlers +for this event, as well as the scheduling priority of of the backing kernel +thread. .Fa flags argument can be used to specify properties of this handler as defined in .In sys/bus.h . @@ -195,10 +237,13 @@ handler. .Pp The .Fn intr_event_remove_handler -removes a handler from an interrupt thread. +function removes an interrupt handler from the interrupt event specified by +.Fa ie . The .Fa cookie -argument specifies the handler to remove from its thread. +argument, obtained from +.Fn intr_event_add_handler , +identifies the handler to remove. .Pp The .Fn intr_priority @@ -226,6 +271,37 @@ from the handler's source triggers. Presently, the .Dv INTR_ENTROPY flag is not valid for software interrupt handlers. +.Ss Handler Callbacks +Each +.Vt struct intr_event +is assigned three optional callback functions when it is created: +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter . +These callbacks are intended to be defined by the interrupt controller driver, +to allow for actions such as masking and unmasking hardware interrupt signals. +.Pp +When an interrupt is triggered, all filters are run to determine if any +threaded interrupt handlers should be scheduled for execution by the associated +interrupt thread. If no threaded handlers are scheduled, the +.Fa post_filter +callback is invoked which should acknowledge the interrupt and permit it to +trigger in the future. +If any threaded handlers are scheduled, the +.Fa pre_ithread +callback is invoked instead. +This handler should acknowledge the interrupt, but it should also ensure that +the interrupt will not fire continuously until after the threaded handlers have +executed. +Typically this callback masks level-triggered interrupts in an interrupt +controller while leaving edge-triggered interrupts alone. +Once all threaded handlers have executed, +the +.Fa post_ithread +callback is invoked from the interrupt thread to enable future interrupts. +Typically this callback unmasks level-triggered interrupts in an interrupt +controller. .Sh RETURN VALUES The .Fn intr_event_add_handler ,