From patchwork Fri Oct 4 16:39:54 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 175242 Delivered-To: patch@linaro.org Received: by 2002:a92:7e96:0:0:0:0:0 with SMTP id q22csp944783ill; Fri, 4 Oct 2019 09:40:21 -0700 (PDT) X-Google-Smtp-Source: APXvYqyw9K//cZqnMxWc/WLiicoi3O8GmrO5kBj8KAByTb6RH7QqL8962uaGSj+4sTSVI1CkZve2 X-Received: by 2002:aa7:d688:: with SMTP id d8mr16359491edr.156.1570207220783; Fri, 04 Oct 2019 09:40:20 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1570207220; cv=none; d=google.com; s=arc-20160816; b=zvE38OB3bvP579jMNiidavGu+OQQ86y1HSXO1wfNcN+ntH4a+l1cOVwws9L89l6FZU CQk2bdijplGehJ6J6Loe/pNyoNi5vIwrHCGsR/86iN6NPQYgGQKiT8AjW3FXoFSSSBel PLNIgxznivmA8j8vDUwl3VBVspxevhQyLGS39NAURByhrt1a4uNWkfYL/OWHEtYOsTJT kv9e2oRaSc1+iEda5RKeUGCHhxJtwkr2ooKX9pJ+e8PikHIq5alhGs75ovNk9RpYM1Ue fn60lGnIasvAiqJCg/m+18AfRXdoDPYTAwVUlwmHn95drmmjRJeKrRWLjOuitLwi0E+D C8xw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=E/NU2YoOJEfLJdExZ5DsO3EJENUZ/h604iJsqxYsNN8=; b=RM19kYxaJXmgGIpGXXmoZySH+HzHPh3zQUlyntvgNdJBto4PrLSvOzEoun35Wh2z8P 9dxVAnJqHAgDC+X6jCKG7vjUDZXf8FtaZbceSbCglKz3PD5Btj/xyjDFUK9ElYlsO9To OpsYmwmWV5mvdP/MDX9NfbJKkh5wiy0tk4cjCjyCIU6x2TwQ8uv09IKn9nuzjUx6NkO7 U5Y+IAGYUgbpr9CCj5VdcZ0rzqVbN1jVqpHHeoPnooer/p9vgphC7EcXfl9xiHDpgEhD 3KZjK1bcB5fRKyqh8bftCjSZdFgWVcQa7ZUcapxG5BJDVpP7rEd4nKvJmmmoSZbIlrx5 CO4g== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id d1si3552547edr.446.2019.10.04.09.40.20; Fri, 04 Oct 2019 09:40:20 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729927AbfJDQkJ (ORCPT + 27 others); Fri, 4 Oct 2019 12:40:09 -0400 Received: from ms.lwn.net ([45.79.88.28]:40206 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727758AbfJDQkH (ORCPT ); Fri, 4 Oct 2019 12:40:07 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id AFC9E6E5; Fri, 4 Oct 2019 16:40:06 +0000 (UTC) From: Jonathan Corbet To: Thomas Gleixner Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 1/2] docs: remove :c:func: from genericirq.rst Date: Fri, 4 Oct 2019 10:39:54 -0600 Message-Id: <20191004163955.14419-2-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191004163955.14419-1-corbet@lwn.net> References: <20191004163955.14419-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org As of 5.3, the automarkup extension will do the right thing with function() notation, so we don't need to clutter the text with :c:func: invocations. So remove them. Signed-off-by: Jonathan Corbet --- Documentation/core-api/genericirq.rst | 50 +++++++++++++-------------- 1 file changed, 25 insertions(+), 25 deletions(-) -- 2.21.0 diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 4da67b65cecf..2e6c99e3ce3b 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -26,7 +26,7 @@ Rationale ========= The original implementation of interrupt handling in Linux uses the -:c:func:`__do_IRQ` super-handler, which is able to deal with every type of +__do_IRQ() super-handler, which is able to deal with every type of interrupt logic. Originally, Russell King identified different types of handlers to build @@ -43,7 +43,7 @@ During the implementation we identified another type: - Fast EOI type -In the SMP world of the :c:func:`__do_IRQ` super-handler another type was +In the SMP world of the __do_IRQ() super-handler another type was identified: - Per CPU type @@ -83,7 +83,7 @@ IRQ-flow implementation for 'level type' interrupts and add a (sub)architecture specific 'edge type' implementation. To make the transition to the new model easier and prevent the breakage -of existing implementations, the :c:func:`__do_IRQ` super-handler is still +of existing implementations, the __do_IRQ() super-handler is still available. This leads to a kind of duality for the time being. Over time the new model should be used in more and more architectures, as it enables smaller and cleaner IRQ subsystems. It's deprecated for three @@ -116,7 +116,7 @@ status information and pointers to the interrupt flow method and the interrupt chip structure which are assigned to this interrupt. Whenever an interrupt triggers, the low-level architecture code calls -into the generic interrupt code by calling :c:func:`desc->handle_irq`. This +into the generic interrupt code by calling desc->handle_irq(). This high-level IRQ handling function only uses desc->irq_data.chip primitives referenced by the assigned chip descriptor structure. @@ -125,27 +125,27 @@ High-level Driver API The high-level Driver API consists of following functions: -- :c:func:`request_irq` +- request_irq() -- :c:func:`free_irq` +- free_irq() -- :c:func:`disable_irq` +- disable_irq() -- :c:func:`enable_irq` +- enable_irq() -- :c:func:`disable_irq_nosync` (SMP only) +- disable_irq_nosync() (SMP only) -- :c:func:`synchronize_irq` (SMP only) +- synchronize_irq() (SMP only) -- :c:func:`irq_set_irq_type` +- irq_set_irq_type() -- :c:func:`irq_set_irq_wake` +- irq_set_irq_wake() -- :c:func:`irq_set_handler_data` +- irq_set_handler_data() -- :c:func:`irq_set_chip` +- irq_set_chip() -- :c:func:`irq_set_chip_data` +- irq_set_chip_data() See the autogenerated function documentation for details. @@ -154,19 +154,19 @@ High-level IRQ flow handlers The generic layer provides a set of pre-defined irq-flow methods: -- :c:func:`handle_level_irq` +- handle_level_irq() -- :c:func:`handle_edge_irq` +- handle_edge_irq() -- :c:func:`handle_fasteoi_irq` +- handle_fasteoi_irq() -- :c:func:`handle_simple_irq` +- handle_simple_irq() -- :c:func:`handle_percpu_irq` +- handle_percpu_irq() -- :c:func:`handle_edge_eoi_irq` +- handle_edge_eoi_irq() -- :c:func:`handle_bad_irq` +- handle_bad_irq() The interrupt flow handlers (either pre-defined or architecture specific) are assigned to specific interrupts by the architecture either @@ -325,14 +325,14 @@ Delayed interrupt disable This per interrupt selectable feature, which was introduced by Russell King in the ARM interrupt implementation, does not mask an interrupt at -the hardware level when :c:func:`disable_irq` is called. The interrupt is kept +the hardware level when disable_irq() is called. The interrupt is kept enabled and is masked in the flow handler when an interrupt event happens. This prevents losing edge interrupts on hardware which does not store an edge interrupt event while the interrupt is disabled at the hardware level. When an interrupt arrives while the IRQ_DISABLED flag is set, then the interrupt is masked at the hardware level and the IRQ_PENDING bit is set. When the interrupt is re-enabled by -:c:func:`enable_irq` the pending bit is checked and if it is set, the interrupt +enable_irq() the pending bit is checked and if it is set, the interrupt is resent either via hardware or by a software resend mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use the delayed interrupt disable feature and your hardware is not capable @@ -369,7 +369,7 @@ handler(s) to use these basic units of low-level functionality. __do_IRQ entry point ==================== -The original implementation :c:func:`__do_IRQ` was an alternative entry point +The original implementation __do_IRQ() was an alternative entry point for all types of interrupts. It no longer exists. This handler turned out to be not suitable for all interrupt hardware From patchwork Fri Oct 4 16:39:55 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 175241 Delivered-To: patch@linaro.org Received: by 2002:a92:7e96:0:0:0:0:0 with SMTP id q22csp944620ill; Fri, 4 Oct 2019 09:40:13 -0700 (PDT) X-Google-Smtp-Source: APXvYqzJihCtyWKxvGzY1Mr6VMhjmY/Dug1uK3SA1QqiKSXL/63a/H9vsUeMa7KgYOEpr9i1XMBK X-Received: by 2002:a17:906:1e44:: with SMTP id i4mr13145665ejj.141.1570207213421; Fri, 04 Oct 2019 09:40:13 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1570207213; cv=none; d=google.com; s=arc-20160816; b=Rb/G7JqW1R/wbQtu/oFOy9jHTjmrNUByZAOh2+6qZ8w6m3hxBW+zUYm+j1JrQXPnMt riPnBvsz1jOPcTxaFfeudJvMqRuE2HKY9LWnOuZelDsnlrqcVDWIv0tcIAgoCe6482+0 UiYi0nFBQ5NZirmlD7+1lPf+ipcPIgV3U8fjnBLVdnEF5f9M0bIgb//YPtMKvyg0TznX VsT2EFHF+0XM5YuB54gsqzjjjyBNSU7jEKEAj28LwsEA3OAwVn/SdI0ezaQuF4icIoPA 0p/A+4glIUb6YSl533HoLAlGsFYGCsHRhXsf+0mXDw6UgXDdI1w3CSkA7DN0Sofyoowl HDrA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from; bh=RgM3EdF45r7tC2gd+rqnrgdvO5DDZm6iKAUQrODCn7g=; b=Lhl/NSorTGFb6MX77D/gCf+h7/tVoMyJyGq2rf+0wPnwrfMHvgJrsCLXuHMX5yGuoS JaGMrffz3rzUONv//DOVzK2rApMSKtGKPrd8f457AGGYo3hWZWl1pWxNPa2647qiujW7 S69QRLXAnOPdboVolBNwAEM5gQIsw3F7iNAH7ftmNGFCni5RkIA99SywSdavbxXaOTTy lHMfwrHQnYpcOchlAU/yArsXeOMM4UA2sqIdjjraB9EfhdxUVbFQt7lcOkxIm+F8Su3X TmYHxQLD+CDs5pY6j5klx5/iZkAhfcF1fbUlj3UIir3dXeD16TxgW6u2A6uc6Dk0vTTb C1Cg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id q30si4335030eda.5.2019.10.04.09.40.13; Fri, 04 Oct 2019 09:40:13 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730080AbfJDQkM (ORCPT + 27 others); Fri, 4 Oct 2019 12:40:12 -0400 Received: from ms.lwn.net ([45.79.88.28]:40210 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726111AbfJDQkH (ORCPT ); Fri, 4 Oct 2019 12:40:07 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 0660C7C0; Fri, 4 Oct 2019 16:40:06 +0000 (UTC) From: Jonathan Corbet To: Thomas Gleixner Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 2/2] docs: Add request_irq() documentation Date: Fri, 4 Oct 2019 10:39:55 -0600 Message-Id: <20191004163955.14419-3-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191004163955.14419-1-corbet@lwn.net> References: <20191004163955.14419-1-corbet@lwn.net> MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org While checking the results of the :c:func: removal, I noticed that there was no documentation for request_irq(), and request_threaded_irq() was not mentioned at all. Add a kerneldoc comment for request_irq() and add request_threaded_irq() to the list of functions. Signed-off-by: Jonathan Corbet --- Documentation/core-api/genericirq.rst | 2 ++ include/linux/interrupt.h | 13 +++++++++++++ 2 files changed, 15 insertions(+) -- 2.21.0 Reviewed-by: Thomas Gleixner diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 2e6c99e3ce3b..8f06d885c310 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -127,6 +127,8 @@ The high-level Driver API consists of following functions: - request_irq() +- request_threaded_irq() + - free_irq() - disable_irq() diff --git a/include/linux/interrupt.h b/include/linux/interrupt.h index 89fc59dab57d..ba873ec7e09d 100644 --- a/include/linux/interrupt.h +++ b/include/linux/interrupt.h @@ -140,6 +140,19 @@ request_threaded_irq(unsigned int irq, irq_handler_t handler, irq_handler_t thread_fn, unsigned long flags, const char *name, void *dev); +/** + * request_irq - Add a handler for an interrupt line + * @irq: The interrupt line to allocate + * @handler: Function to be called when the IRQ occurs. + * Primary handler for threaded interrupts + * If NULL, the default primary handler is installed + * @flags: Handling flags + * @name: Name of the device generating this interrupt + * @dev: A cookie passed to the handler function + * + * This call allocates an interrupt and establishes a handler; see + * the documentation for request_threaded_irq() for details. + */ static inline int __must_check request_irq(unsigned int irq, irq_handler_t handler, unsigned long flags, const char *name, void *dev)