From nobody Wed Feb 11 14:45:06 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id DB6C3C77B7C for ; Tue, 9 May 2023 17:57:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233613AbjEIR5q (ORCPT ); Tue, 9 May 2023 13:57:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57146 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233992AbjEIR5n (ORCPT ); Tue, 9 May 2023 13:57:43 -0400 Received: from m228-4.mailgun.net (m228-4.mailgun.net [159.135.228.4]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0B1724EDD for ; Tue, 9 May 2023 10:57:41 -0700 (PDT) DKIM-Signature: a=rsa-sha256; v=1; c=relaxed/relaxed; d=equiv.tech; q=dns/txt; s=mx; t=1683655060; x=1683662260; h=Content-Transfer-Encoding: MIME-Version: References: In-Reply-To: Message-Id: Date: Subject: Subject: Cc: To: To: From: From: Sender: Sender; bh=6jttwz+Cugq4ceWJPmbhCtB6fO9JHbLfWVDtldhs2RI=; b=X7u5t44Q2a7RtJmVkklR1X/ulwhIPJYP6Bx1SJLNVEjmZgpAehFIqbRoLin1UK59t9r3dzHDXptVlwAQKPdmRb1rtkYNuGVKt4DhlV9WqbL2R3QlK6dOZ+qrlobd9+CgQDDNldn0aXNGdQrAdcN5p+8Qn/GbPq26GmsvHqyqKcC5aQ3UklB+tTr+3LqRzWBZZIkdJu5ceatCl2ZUPrsbKjFjMFGnHoPfc2lB0SDX7phDbTMI6zTKruh7HXUsR+GLQyqDJo/ZV0TvE+ONYlGAM3hIgQcNRQqNPJi2qgIzS6rBoTOWnCvXr5XD6HDejOXcURV7tKLxuR/YH2U4fttpFA== X-Mailgun-Sending-Ip: 159.135.228.4 X-Mailgun-Sid: WyI4ZWI3MiIsImxpbnV4LWtlcm5lbEB2Z2VyLmtlcm5lbC5vcmciLCI5M2Q1YWIiXQ== Received: from mail.equiv.tech (equiv.tech [142.93.28.83]) by c8d9e52701dd with SMTP id 645a8994dd415858cb50579b (version=TLS1.2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256); Tue, 09 May 2023 17:57:40 GMT Sender: james@equiv.tech From: James Seo To: Jonathan Corbet , Greg Kroah-Hartman , Andrew Morton Cc: James Seo , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 1/3] Documentation: conf.py: Add __force to c_id_attributes Date: Tue, 9 May 2023 10:55:43 -0700 Message-Id: <20230509175543.2065835-2-james@equiv.tech> In-Reply-To: <20230509175543.2065835-1-james@equiv.tech> References: <20230509175543.2065835-1-james@equiv.tech> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" Fixes the following error in the docs build that occurs with recent versions of Sphinx when parsing kerneldocs for a function with the '__force' macro in its signature: ./include/linux/err.h:51: WARNING: Error in declarator or parameters Error in declarator or parameters Invalid C declaration: Expected identifier, got keyword: void [error at 3= 5] void * ERR_CAST (__force const void *ptr) -----------------------------------^ Currently, almost all of the few in-signature occurrences of '__force' are in the error pointer functions. Of those, ERR_CAST() is the only one with kerneldocs, but the kerneldocs aren't even being used to generate documentation. This change will allow all the error pointer functions to be properly documented. In addition to '__force', also defines '__nocast', '__safe', and '__private'. These are not currently used in any function signatures and do not need to be added to the docs config. Signed-off-by: James Seo --- Documentation/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/conf.py b/Documentation/conf.py index 37314afd1ac8..d4fdf6a3875a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -74,6 +74,7 @@ if major >=3D 3: "__percpu", "__rcu", "__user", + "__force", =20 # include/linux/compiler_attributes.h: "__alias", --=20 2.34.1 From nobody Wed Feb 11 14:45:06 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id BC6A9C7EE24 for ; Tue, 9 May 2023 17:59:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234487AbjEIR7Q (ORCPT ); Tue, 9 May 2023 13:59:16 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58172 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229738AbjEIR7M (ORCPT ); Tue, 9 May 2023 13:59:12 -0400 Received: from m228-13.mailgun.net (m228-13.mailgun.net [159.135.228.13]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EB0EF4480 for ; Tue, 9 May 2023 10:59:11 -0700 (PDT) DKIM-Signature: a=rsa-sha256; v=1; c=relaxed/relaxed; d=equiv.tech; q=dns/txt; s=mx; t=1683655151; x=1683662351; h=Content-Transfer-Encoding: MIME-Version: References: In-Reply-To: Message-Id: Date: Subject: Subject: Cc: To: To: From: From: Sender: Sender; bh=3UCNsG9zTtlSKFUi3pfdqS/d3QkDhijjCHrzZONc2RU=; b=gsBdKyJr/BVWmZSFKUzYAAN83qbvND6yPtUOmxkTfi3bdcR7ZFCPKDHgiucWaV0Ct3YU9WDq6y5tNyOVdQ/a4bx9zLdBKKjFSKAqxROpDUSXS3egH8rGURW46vMi1iJQcVt1W/wvlrbvFx5hYHGJoi6p0RMP4AjUMp7YTFMmOJfLCkQAPRoMDyHADVMtJwsIbJ9UdughrzJKS8MJOM+Uh77HEuXL6SuYAnzmfJGqrkzB4VPH99bHO2Q6pn0YbGtNfdjYHWgp/FG6g11/q8ZTHk4Spto/BzYJVzkqubNvLFC27UNHkKPgLgS5tMF8ey57W5rbHMjRRNJFo+N4RqlnAg== X-Mailgun-Sending-Ip: 159.135.228.13 X-Mailgun-Sid: WyI4ZWI3MiIsImxpbnV4LWtlcm5lbEB2Z2VyLmtlcm5lbC5vcmciLCI5M2Q1YWIiXQ== Received: from mail.equiv.tech (equiv.tech [142.93.28.83]) by cd847f61b1c3 with SMTP id 645a89eff77227a83016954f (version=TLS1.2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256); Tue, 09 May 2023 17:59:11 GMT Sender: james@equiv.tech From: James Seo To: Jonathan Corbet , Greg Kroah-Hartman , Andrew Morton Cc: James Seo , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 2/3] err.h: Add missing kerneldocs for error pointer functions Date: Tue, 9 May 2023 10:55:46 -0700 Message-Id: <20230509175543.2065835-3-james@equiv.tech> In-Reply-To: <20230509175543.2065835-1-james@equiv.tech> References: <20230509175543.2065835-1-james@equiv.tech> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" Add kerneldocs for ERR_PTR(), PTR_ERR(), PTR_ERR_OR_ZERO(), IS_ERR(), and IS_ERR_OR_NULL(). Doing so will help convert hundreds of mentions of them in existing documentation into automatic cross-references. Also add kerneldocs for IS_ERR_VALUE(). Doing so adds no automatic cross-references, but this macro has a slightly different use case than the functionally similar IS_ERR(), and documenting it may be helpful to readers who encounter it in existing code. ERR_CAST() already has kerneldocs and has not been touched. Signed-off-by: James Seo --- include/linux/err.h | 48 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/include/linux/err.h b/include/linux/err.h index a139c64aef2a..c804118ae73d 100644 --- a/include/linux/err.h +++ b/include/linux/err.h @@ -19,23 +19,54 @@ =20 #ifndef __ASSEMBLY__ =20 +/** + * IS_ERR_VALUE - Detect an error pointer. + * @x: The pointer to check. + * + * Like IS_ERR(), but does not generate a compiler warning if result is un= used. + */ #define IS_ERR_VALUE(x) unlikely((unsigned long)(void *)(x) >=3D (unsigned= long)-MAX_ERRNO) =20 +/** + * ERR_PTR - Create an error pointer. + * @error: A negative error code. + * + * Encodes @error into a pointer value. Users should consider the result + * opaque and not assume anything about how the error is encoded. + * + * Return: A pointer with @error encoded within its value. + */ static inline void * __must_check ERR_PTR(long error) { return (void *) error; } =20 +/** + * PTR_ERR - Extract the error code from an error pointer. + * @ptr: An error pointer. + * Return: The error code within @ptr. + */ static inline long __must_check PTR_ERR(__force const void *ptr) { return (long) ptr; } =20 +/** + * IS_ERR - Detect an error pointer. + * @ptr: The pointer to check. + * Return: true if @ptr is an error pointer, false otherwise. + */ static inline bool __must_check IS_ERR(__force const void *ptr) { return IS_ERR_VALUE((unsigned long)ptr); } =20 +/** + * IS_ERR_OR_NULL - Detect an error pointer or a null pointer. + * @ptr: The pointer to check. + * + * Like IS_ERR(), but also returns true for a null pointer. + */ static inline bool __must_check IS_ERR_OR_NULL(__force const void *ptr) { return unlikely(!ptr) || IS_ERR_VALUE((unsigned long)ptr); @@ -54,6 +85,23 @@ static inline void * __must_check ERR_CAST(__force const= void *ptr) return (void *) ptr; } =20 +/** + * PTR_ERR_OR_ZERO - Extract the error code from a pointer if it has one. + * @ptr: A potential error pointer. + * + * Convenience function that can be used inside a function that returns + * an error code to propagate errors received as error pointers. + * For example, ``return PTR_ERR_OR_ZERO(ptr);`` replaces: + * + * .. code-block:: c + * + * if (IS_ERR(ptr)) + * return PTR_ERR(ptr); + * else + * return 0; + * + * Return: The error code within @ptr if it is an error pointer; 0 otherwi= se. + */ static inline int __must_check PTR_ERR_OR_ZERO(__force const void *ptr) { if (IS_ERR(ptr)) --=20 2.34.1 From nobody Wed Feb 11 14:45:06 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9B589C77B75 for ; Tue, 9 May 2023 17:59:32 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234778AbjEIR7b (ORCPT ); Tue, 9 May 2023 13:59:31 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58344 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234636AbjEIR7V (ORCPT ); Tue, 9 May 2023 13:59:21 -0400 Received: from m228-4.mailgun.net (m228-4.mailgun.net [159.135.228.4]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D53D94EF4 for ; Tue, 9 May 2023 10:59:18 -0700 (PDT) DKIM-Signature: a=rsa-sha256; v=1; c=relaxed/relaxed; d=equiv.tech; q=dns/txt; s=mx; t=1683655158; x=1683662358; h=Content-Transfer-Encoding: MIME-Version: References: In-Reply-To: Message-Id: Date: Subject: Subject: Cc: To: To: From: From: Sender: Sender; bh=AhzIKWTMsV4zA7MKuXnmnFl9fzQYGsYJmx449VzTw/k=; b=rt7nZG4eY1jmCmkyT+f4vD1T6Gb3gdCSV+Tne5Y+RvAU+u8DLKnqNaMUjMI2BQTafFLQMClsyB7q4p8DOae9wpUVOl4G4tg1cNWRZC/TizMOY/iqCiRGCNQeFJVaefxFYaE/JmJj/9BrCxXOkkaafyEZeKcmIJCFoPwh+Z25SM76Ev79ubuJn0iWBwSdoR17QORl0yR9hQecprKAyVnvWzHhm3A6zQEbZf+jFPBvmoJyExQQ+0bi4U5CGfZNNUUPALSLd6WQLMEC+x02fpOJ8qeOuu3sPUGMXhE/8do5A4Vf097PIDQT8WSl9uXQ4d93hELxx8yCizt5C+9c7vIOMw== X-Mailgun-Sending-Ip: 159.135.228.4 X-Mailgun-Sid: WyI4ZWI3MiIsImxpbnV4LWtlcm5lbEB2Z2VyLmtlcm5lbC5vcmciLCI5M2Q1YWIiXQ== Received: from mail.equiv.tech (equiv.tech [142.93.28.83]) by 450ed783a028 with SMTP id 645a89f67ce302952fa785cb (version=TLS1.2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256); Tue, 09 May 2023 17:59:18 GMT Sender: james@equiv.tech From: James Seo To: Jonathan Corbet , Greg Kroah-Hartman , Andrew Morton Cc: James Seo , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 3/3] Documentation: core-api: Add error pointer functions to kernel-api Date: Tue, 9 May 2023 10:55:48 -0700 Message-Id: <20230509175543.2065835-4-james@equiv.tech> In-Reply-To: <20230509175543.2065835-1-james@equiv.tech> References: <20230509175543.2065835-1-james@equiv.tech> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" Bring the error pointer functions (e.g. ERR_PTR(), PTR_ERR()) into the docs build so that they can be cross-referenced elsewhere. List them as kernel library functions in the kernel-api document. Nowhere else seems to fit, and they need to go *somewhere*. Signed-off-by: James Seo --- Documentation/core-api/kernel-api.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api= /kernel-api.rst index 9b3f3e5f5a95..44b96e18f8f2 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -96,6 +96,12 @@ Command-line Parsing .. kernel-doc:: lib/cmdline.c :export: =20 +Error Pointers +-------------- + +.. kernel-doc:: include/linux/err.h + :internal: + Sorting ------- =20 --=20 2.34.1