From nobody Sat Oct 15 18:52:08 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 4MqXRs0Mdyz4fTkM; Sat, 15 Oct 2022 18:52:09 +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 4MqXRr6Gp5z49rt; Sat, 15 Oct 2022 18:52:08 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1665859928; 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=vSdioRcJPmH4jMseezy/idbrOaJFvulA9V+ldqe6L1o=; b=LbTHXA4WGlHkIot6/4dm6zNzKNXUkTfGoCEM4epqpDE4HgjvBQh/NNNQeqgvWdVILUIXBD uGzZyB7DpXxCK5ar+4CABJPDc5EfnzjRF4yEU12v1sin8Z3tKoXYLeuTomVZufyqkSNC/m dDHLuB5Cr6RhhJ1iRxUIHaKkt63Mlnz7smVcvenZ6lwaC7itOaOhYNmGx5H/v7u4/gI53X a3oglhVf7VrN8pF5W0O7M2XMZnDmxWNq0+4aZfw5lNHSVVm2n8nAUsw2coroVpV9Dk0Mwk rLu+CkaLhIUSYbZE6fYN6UbRErrRkxWmSHUP0lz6de8vg4UVSaO6HNvoGFHbIg== 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 4MqXRr5LYCz1CVQ; Sat, 15 Oct 2022 18:52:08 +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 29FIq84P060182; Sat, 15 Oct 2022 18:52:08 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 29FIq8FU060181; Sat, 15 Oct 2022 18:52:08 GMT (envelope-from git) Date: Sat, 15 Oct 2022 18:52:08 GMT Message-Id: <202210151852.29FIq8FU060181@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: cb9425e21c91 - main - intr_event(9): update existing function descriptions 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: cb9425e21c917732fb16bd14947cba01f26687f3 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1665859928; 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=vSdioRcJPmH4jMseezy/idbrOaJFvulA9V+ldqe6L1o=; b=OYty0ltMrx38BxDf1Ac3IOUm43ADSDU2/X1Nge11JWJH5Rj9pCSS9s/Sv9mjKnN2bHfLKO esDLBlECmBNuZolC4gb8bO0HlMr3nWiiNepJUP/5bb5r33J4NduFQMP0+H01u8oGpWZ/DR HKYgmoxtVBX4oenGIdnLjUITtQmU6tPZ2CBvCSc0lRXPa8X+LCLcds+MjgS0BW+Fl5OIAF XHdzriyT6jMpf1edjcFaiXez0ioTT3ADKu9OqXgXSUkLzGLX4EE/JGr3pCNAJuXYE/xj5p XgR8u6OUMbQF+v0PUiYMXu6don4xmQixEhMt8Kd9a7cp3boOf26T2HMNN68UHA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1665859928; a=rsa-sha256; cv=none; b=EvyzVD56HcWsVe+8xQTB0m7LTTV77ilRo+EpncCtYofDysUFqzQlItvzNM0vXzeWYckYD7 CGdGEjBNDFAq/0k/OaFbx3s0bjNRh6KWLjwm9usMkd/8gN/JABWobhFb7eacXkRsG/t2XR itO0YBY7stMsEA220ojN4IH9mM8ozfOgdWHQ3EZmsqttGfWSfFWUn13Er9grz9PUkXk7Tt bcu3L0YvJZiNvLnVkISD+N+5h9wtG4EEaFcddD8yiEzn2WRTBJermzNrhx3B2eaHjSeS29 OkL9FXz+3NJa952BIXvmQVpPa4QMpZLx2TAZMhB/dqNUx4lsm++4HF8SOBjdCQ== 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=cb9425e21c917732fb16bd14947cba01f26687f3 commit cb9425e21c917732fb16bd14947cba01f26687f3 Author: Mitchell Horne AuthorDate: 2022-10-15 18:39:27 +0000 Commit: Mitchell Horne CommitDate: 2022-10-15 18:50:25 +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 --- 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 ,