From nobody Wed Apr 1 10:02:08 2026 Received: from mx0b-0031df01.pphosted.com (mx0b-0031df01.pphosted.com [205.220.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 50FF33876B3 for ; Tue, 31 Mar 2026 12:28:42 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=205.220.180.131 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774960124; cv=none; b=nWwJ+56+IFpWd0tYeiZhxKG+9jDnJK1JFxG26chMSaEBzoxm0ZrhOzY77C0dCXJAZFr01mKJr5CGxMlEqFBiSWnVD1M//MmM4zYjjplBjKT+Gdi0dzLjy7Eb7QYzLaj/h6NFp/pMBFh7uZSMOpVz7cRjMnnWvmRdZVHDnkl32uA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774960124; c=relaxed/simple; bh=mi7memNQJCzeEutC0WFVeI6fKKTMYzxTIJkiFRVVWSA=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:To:Cc; b=gcR2pyTnnw6NNSBN7CQ2OS9AKeBwx1/++yjp4LUn8JPNUa5A8P7NYVydICMpsfs6bMH8tfTEj6/zah8+5zT/NPUXgOpQChiNgJUFD08HTnkEgwD9/++dIeHw+1gL70Fh77giRV+H/TpLAGn5Ab0wgCud15Q5ldHknJ34n04q2Oo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=oss.qualcomm.com; spf=pass smtp.mailfrom=oss.qualcomm.com; dkim=pass (2048-bit key) header.d=qualcomm.com header.i=@qualcomm.com header.b=JCLuRbpI; dkim=pass (2048-bit key) header.d=oss.qualcomm.com header.i=@oss.qualcomm.com header.b=AodhZJVb; arc=none smtp.client-ip=205.220.180.131 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=oss.qualcomm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=oss.qualcomm.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=qualcomm.com header.i=@qualcomm.com header.b="JCLuRbpI"; dkim=pass (2048-bit key) header.d=oss.qualcomm.com header.i=@oss.qualcomm.com header.b="AodhZJVb" Received: from pps.filterd (m0279872.ppops.net [127.0.0.1]) by mx0a-0031df01.pphosted.com (8.18.1.11/8.18.1.11) with ESMTP id 62V7OVf92465275 for ; Tue, 31 Mar 2026 12:28:41 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=qualcomm.com; h= cc:content-transfer-encoding:content-type:date:from:message-id :mime-version:subject:to; s=qcppdkim1; bh=k8hUEnYut0k71ljUpIpx01 nVp9CKF2EbzDfYFhXRuzY=; b=JCLuRbpIqzs57buzkCa/31s/O4DrRqOy3aKwmy rbQIfmSefPdkBpHaWzCQtDTc/ZYrNCBss46H8Eim8aPGWql5JYreeVKMZj4Za+nb po3uGRfhYiqp0tKR0GB68/wSQrhh8qrYVASWopT0cxf6ffpBSJQpGueh7fSPydzs aQA+fA5tTV80Rff7qQMlEcd6fcEsGzKTqfWdmIxjf9NMJ1BTuscEjVBbrj5saPPq UM5UDyth52AstheFvgIgWQEsFpjGJ3rE3uQRG/r9b2wR4QMKA7D4MFosSRNKeSxL UckoNXPtxO2faG0Ue+TtuNWbhIAdIaLEIDe5ulJ5vkpmGLAw== Received: from mail-qt1-f200.google.com (mail-qt1-f200.google.com [209.85.160.200]) by mx0a-0031df01.pphosted.com (PPS) with ESMTPS id 4d89ut96qg-1 (version=TLSv1.3 cipher=TLS_AES_128_GCM_SHA256 bits=128 verify=NOT) for ; Tue, 31 Mar 2026 12:28:41 +0000 (GMT) Received: by mail-qt1-f200.google.com with SMTP id d75a77b69052e-5093a985e21so130809571cf.3 for ; Tue, 31 Mar 2026 05:28:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oss.qualcomm.com; s=google; t=1774960120; x=1775564920; darn=vger.kernel.org; h=cc:to:message-id:content-transfer-encoding:mime-version:subject :date:from:from:to:cc:subject:date:message-id:reply-to; bh=k8hUEnYut0k71ljUpIpx01nVp9CKF2EbzDfYFhXRuzY=; b=AodhZJVbRWGNasnENFR4SANnNZWqkLxQ9fDU/8ougZEE9ACxYLicPUXQzWFNJlKmaU tGHH+0ps0Iec3CJqEn89fsWLWHHk4S9nkTh9FX2FbGBgDZw6dy6bxRtuOOFLoQUfbxNn TU48DGBmRdsk+ipLwt0MebolpL73lIDDf/Xmjq3Bm+NPo+bBIpy1SW/9pdcdZKjIsxf6 kG8x/KDN3I/xs0Zm5acwn1QuVEogh/xKVTDmajxekNIWZjZQNYhGrlHOLioR/145Z3pf gygllTE/je9zSbKnisF46ZsNwT+4ii6VBqt+FysDlVnLHK/JHfUf8rOdjnQHJ4Gdy8aQ jdxw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1774960120; x=1775564920; h=cc:to:message-id:content-transfer-encoding:mime-version:subject :date:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=k8hUEnYut0k71ljUpIpx01nVp9CKF2EbzDfYFhXRuzY=; b=RXrNc3XiRz5pOg7asIBqTkL0lyAKntFRZT59ppGjOV/VAJ9ecbwyiLnUK7lv0Xj7LU a/bpCTHm55hLfnyf/mAJ3kHXwKCH6i8p58aIR36PnKAt9RnCmOXbU5XHp1S8VZGtTEJU jYbyVhPJDpn2gFRrsyxyLBOsvt2ViOZTOjdWbNRzsUpCbTVpMwVpWSSq57iB2GsYCzif C8+jeqx6LG4s5VEgWuRNLXMFscQUgJp+tWEug0Qi6ZwY1UNxujt6rn3JsxnKyBbLVhvS HaxMw64Sn7puxqxkvLyhJ3WdMS+w62u8QZaUObaw+CQV5I+XVHAwb/ih34tNvlamlMnE eHcQ== X-Forwarded-Encrypted: i=1; AJvYcCX6OHhkikicuAB2B0mS9lKiI2JLMvF78lpVm9Tuzl8CTNvgSmZy3BvKLJerildftF1DfBxDPWYP5ELcZ54=@vger.kernel.org X-Gm-Message-State: AOJu0YzbDyq+6ph3WhD8K7z9CnrBxDe7YD42B1uD7WeP+Wo2N+OYecSL wSyU8CEbe5VlYUWMSlPaMx/wsffQsfq+9HR4CVmCXojTVdFye7iyVmssNh2wYokT2HAC3J20jLq 5VhaPxKZuV3yPlP+aesFkr7MaOKQf4bZtk197l/rgnrKAkPJk1brZhiFNfksuZW/RW+w= X-Gm-Gg: ATEYQzyJvEZDxhKwcf8LxGgN2JnDdCAcJFN/eFDuu7WvWFSbLDduzKfuOGILiYxaqqo +7LJeVbz1G43pwxptOJhIFE9BSXHke4lRokRB47PuMS/V9FR5JXGMRy/1tsgkOfFASDHIL1jLcQ i8LHmiUuhwYUY1nl8z0jyOT7Ecu4HquXqtbdPHLd7E1i/EF4InAxJ61tmbh0DSfNX1u/yOMvwQE e8YRDLz5mRvd9mBG9KbbIA9FbFcFRvW7sG2Ns1uQpSo+ahaypgErrUBwQhRNR2HxfW+9gxQH4KA dhBALCSftRVmP7KUs5nBB/vyCE8GNILwIjy5+AStPzMHCwTuhcmOBpJ0YU2Rm1qRHsb+GVf6qzB NnHWE5ez3Cf+tBhC22XE7IMOcswECzUvRDC/Jt41n+jG29UxQTmps X-Received: by 2002:ac8:7d0f:0:b0:509:2fa5:741 with SMTP id d75a77b69052e-50ba3818bfamr208064691cf.4.1774960120413; Tue, 31 Mar 2026 05:28:40 -0700 (PDT) X-Received: by 2002:ac8:7d0f:0:b0:509:2fa5:741 with SMTP id d75a77b69052e-50ba3818bfamr208064301cf.4.1774960119921; Tue, 31 Mar 2026 05:28:39 -0700 (PDT) Received: from brgl-qcom.local ([2a01:cb1d:dc:7e00:977e:e16b:6244:a86f]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4887c77df84sm23343405e9.4.2026.03.31.05.28.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 31 Mar 2026 05:28:38 -0700 (PDT) From: Bartosz Golaszewski Date: Tue, 31 Mar 2026 14:28:29 +0200 Subject: [PATCH] Documentation: gpio: update the preferred method for using software node lookup Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260331-doc-gpio-swnodes-v1-1-3f84c268999b@oss.qualcomm.com> X-B4-Tracking: v=1; b=H4sIAOy9y2kC/x3MMQqAMAxA0atIZgPVoqhXEQdt0pqllQZUEO9uc XzD/w8oZ2GFqXog8ykqKRY0dQVuX2NgFCqG1rS9sbZBSg7DIQn1iolY0TtL5LtxG8hByY7MXu5 /OS/v+wEVGQ6BYgAAAA== X-Change-ID: 20260331-doc-gpio-swnodes-fc3ddf59b8dc To: Linus Walleij , Bartosz Golaszewski , Jonathan Corbet , Shuah Khan , Dmitry Torokhov Cc: linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Bartosz Golaszewski X-Mailer: b4 0.14.2 X-Developer-Signature: v=1; a=openpgp-sha256; l=7215; i=bartosz.golaszewski@oss.qualcomm.com; h=from:subject:message-id; bh=mi7memNQJCzeEutC0WFVeI6fKKTMYzxTIJkiFRVVWSA=; b=owEBbQKS/ZANAwAKAQWdLsv/NoTDAcsmYgBpy73xKHeRRU1aQQdygxLpzMfekpEucmYmPOgkS VL7hWz7EzmJAjMEAAEKAB0WIQSR5RMt5bVGHXuiZfwFnS7L/zaEwwUCacu98QAKCRAFnS7L/zaE wwF+D/46dCxYO+SuyTketuhK+O+1wRtn5kdjnz/jPuKg2DdWYAdfvcAvjlec9tnVc+FMP4Bc5db LXJ9qYXVcAiJzCJOicc14u55mS3sTUulgSnVrY+0omciBww8Hj1t7CqFd4qkEQsK3qQNm1FaLqt JWftGhUjOnYmg7c3ARUtElVjJ80jBNvncFMZCyR59OpPeC30GrjGrRV+vfXZkZe2bb4Wmnn5qIT HbmfyA+fR/TZwjEvRipfEex0HsmAyWH2GxMgU9UsiKf6BwBEC4aFh8WYE4si+s62VAnoaXXU/6j X9fuFtBa24T0PfTCWn+6PC75AGwy77EJqJiE2jl/U91X5bPzZ2JHPk2m9n2EE1aU4YBjFQ6yq8Q fw3iYfMWB7ahvmRLDIS/6zLIoYEWve+wUnEkBry5D7O6udDWn1VeGgSCvaTjOsWbOR2pbcUXySC goBRamUVuQD7BaRlMKRPZ8aLAXQ3kF7Gwe3WzCVEHJ1JE6wpBG3HZObXM+AiNYSwvW7N/V/eZ3n 6k5zuZLdu+qmoR5RQAZckbVI2BU67Nf0FnT/OORSgPTR5GV0sB67t6BkQuy0sVWx5/XXRJ+12rj FonNTl2SFGBf/Eu3itJDPpq/pZY7GSwOrqpi0s/VmZitGLYpSB2BopxL5DbZaLnHYZqu+nFLUHm 2OBkzahr32qKiww== X-Developer-Key: i=bartosz.golaszewski@oss.qualcomm.com; a=openpgp; fpr=169DEB6C0BC3C46013D2C79F11A72EA01471D772 X-Proofpoint-ORIG-GUID: twM6F6o7_mqi-lQCUh_16-wM73oezu_9 X-Authority-Analysis: v=2.4 cv=C5LkCAP+ c=1 sm=1 tr=0 ts=69cbbdf9 cx=c_pps a=JbAStetqSzwMeJznSMzCyw==:117 a=VHV1bxSRZQlKidfD:21 a=xqWC_Br6kY4A:10 a=IkcTkHD0fZMA:10 a=Yq5XynenixoA:10 a=s4-Qcg_JpJYA:10 a=VkNPw1HP01LnGYTKEx00:22 a=u7WPNUs3qKkmUXheDGA7:22 a=yx91gb_oNiZeI1HMLzn7:22 a=EUspDBNiAAAA:8 a=KH8R8Eao7PwcOq8sAqYA:9 a=QEXdDO2ut3YA:10 a=uxP6HrT_eTzRwkO_Te1X:22 X-Proofpoint-GUID: twM6F6o7_mqi-lQCUh_16-wM73oezu_9 X-Proofpoint-Spam-Details-Enc: AW1haW4tMjYwMzMxMDEyMCBTYWx0ZWRfXyHcCpww7q9jF YHt55QUV03TtyLk8nEQFfFMTekCBmAKpCBFnqAGqGveyOwaqJI9J7cmz2nR+TEsddtUymW3PSD3 /93RZbeyN89+84OtCQXXKKK/MD0PmVB4j3HUxYd4y8bI7FeQXYflxs9xZ3OXMzdb8nO7/ztIg9V 2+IoYSb9Tc75RcuqnQU7PzY0f4RgudRWfyM5VDFbRe+KBz0RlQXbi3W2gxiWS84mCPWGmpWbF4V 2THx1BC95yXDcv62ZsYB6k/GCJsM7T2NnUuVG+jGB97ad3GyCpE+cid4lFYOnLJQa+qi7TjPQ2U tF1lyIk+J6VXwkjKIE5efnY6r0slp+AgukeB3oU93DpkMTDlvXDZbXU+pA3XmlaOpGbWzsQ//it 6zIJrfco0/e3Cjws0+nJh0BQJOZc1JcuiqGCeJ9c7IN+oR2L3z/rprjKMxYF6tDrBF5BHpjuqA5 ua9lSSU+LXca8NOi8AQ== X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1143,Hydra:6.1.51,FMLib:17.12.100.49 definitions=2026-03-31_02,2026-03-31_01,2025-10-01_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 impostorscore=0 clxscore=1015 malwarescore=0 bulkscore=0 suspectscore=0 lowpriorityscore=0 adultscore=0 phishscore=0 spamscore=0 classifier=typeunknown authscore=0 authtc= authcc= route=outbound adjust=0 reason=mlx scancount=1 engine=8.22.0-2603050001 definitions=main-2603310120 In its current version, the manual for converting of board files from using GPIO lookup tables to software nodes recommends leaving the software nodes representing GPIO controllers as "free-floating", not attached objects and relying on the matching of their names against the GPIO controller's name. This is an abuse of the software node API and makes it impossible to create fw_devlinks between GPIO suppliers and consumers in this case. We want to remove this behavior from GPIOLIB and to this end, work on converting all existing drivers to using "attached" software nodes. Except for a few corner-cases where board files define consumers depending on GPIO controllers described in firmware - where we need to reference a real firmware node from a software node - which requires a more complex approach, most board files can easily be converted to using propert firmware node lookup. Update the documentation to recommend attaching the GPIO chip's software nodes to the actual platform devices and show how to do it. Signed-off-by: Bartosz Golaszewski --- Documentation/driver-api/gpio/board.rst | 15 +++++++++--- Documentation/driver-api/gpio/legacy-boards.rst | 32 ++++++++++++++++++---= ---- 2 files changed, 36 insertions(+), 11 deletions(-) diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver= -api/gpio/board.rst index 0993cac891fb5e4887a1aee6deae273197c6aae1..c2880533742b1b55108f28853a3= 903cb273fe791 100644 --- a/Documentation/driver-api/gpio/board.rst +++ b/Documentation/driver-api/gpio/board.rst @@ -108,9 +108,8 @@ macro, which ties a software node representing the GPIO= controller with consumer device. It allows consumers to use regular gpiolib APIs, such as gpiod_get(), gpiod_get_optional(). =20 -The software node representing a GPIO controller need not be attached to t= he -GPIO controller device. The only requirement is that the node must be -registered and its name must match the GPIO controller's label. +The software node representing a GPIO controller must be attached to the +GPIO controller device - either as the primary or the secondary firmware n= ode. =20 For example, here is how to describe a single GPIO-connected LED. This is = an alternative to using platform_data on legacy systems. @@ -153,6 +152,16 @@ alternative to using platform_data on legacy systems. }; software_node_register_node_group(swnodes); =20 + /* + * 5. Attach the GPIO controller's software node to the device and + * register it. + */ + static void gpio_foo_register(void) + { + gpio_foo_pdev.dev.fwnode =3D software_node_fwnode(&gpio_controller_node); + platform_device_register(&gpio_foo_pdev); + } + // Then register a platform_device for "leds-gpio" and associate // it with &led_device_swnode via .fwnode. =20 diff --git a/Documentation/driver-api/gpio/legacy-boards.rst b/Documentatio= n/driver-api/gpio/legacy-boards.rst index 46e3a26dba772e5e5117866b5d202e76c8e2adf2..fac63dd38d5b71c3bf43b5286a4= 32f6449f422d0 100644 --- a/Documentation/driver-api/gpio/legacy-boards.rst +++ b/Documentation/driver-api/gpio/legacy-boards.rst @@ -36,12 +36,10 @@ Requirements for GPIO Properties When using software nodes to describe GPIO connections, the following requirements must be met for the GPIO core to correctly resolve the refere= nce: =20 -1. **The GPIO controller's software node "name" must match the controller= 's - "label".** The gpiolib core uses this name to find the corresponding - struct gpio_chip at runtime. - This software node has to be registered, but need not be attached to t= he - device representing the GPIO controller that is providing the GPIO in - question. It may be left as a "free floating" node. +1. **The GPIO controller's software node must be registered and attached = to + the controller's ``struct device`` either as its primary or secondary + firmware node.** The gpiolib core uses the address of the firmware nod= e to + find the corresponding ``struct gpio_chip`` at runtime. =20 2. **The GPIO property must be a reference.** The ``PROPERTY_ENTRY_GPIO()= `` macro handles this as it is an alias for ``PROPERTY_ENTRY_REF()``. @@ -75,6 +73,11 @@ A typical legacy board file might look like this: =20 #define MYBOARD_GPIO_CONTROLLER "gpio-foo" =20 + static struct platform_device myboard_gpio =3D { + .name =3D MYBOARD_GPIO_CONTROLLER, + .id =3D PLATFORM_DEVID_NONE, + }; + /* LED setup */ static const struct gpio_led myboard_leds[] =3D { { @@ -124,6 +127,7 @@ A typical legacy board file might look like this: gpiod_add_lookup_table(&myboard_leds_gpios); gpiod_add_lookup_table(&myboard_buttons_gpios); =20 + platform_device_register(&myboard_gpio); platform_device_register_data(NULL, "leds-gpio", -1, &myboard_leds_pdata, sizeof(myboard_leds_pdata)); platform_device_register_data(NULL, "gpio-keys", -1, @@ -141,8 +145,7 @@ Step 1: Define the GPIO Controller Node *************************************** =20 First, define a software node that represents the GPIO controller that the -LEDs and buttons are connected to. The ``name`` of this node must match the -name of the driver for the GPIO controller (e.g., "gpio-foo"). +LEDs and buttons are connected to. The ``name`` of this node is optional. =20 .. code-block:: c =20 @@ -257,6 +260,16 @@ software nodes using the ``fwnode`` field in struct pl= atform_device_info. if (error) return error; =20 + memset(&pdev_info, 0, sizeof(pdev_info)); + pdev_info.name =3D MYBOARD_GPIO_CONTROLLER; + pdev_info.id =3D PLATFORM_DEVID_NONE; + pdev_info.fwnode =3D software_node_fwnode(&myboard_gpio_controller_node= ); + gpio_pdev =3D platform_device_register_full(&pdev_info); + if (IS_ERR(gpio_pdev)) { + error =3D PTR_ERR(gpio_pdev); + goto err_unregister_nodes; + } + memset(&pdev_info, 0, sizeof(pdev_info)); pdev_info.name =3D "leds-gpio"; pdev_info.id =3D PLATFORM_DEVID_NONE; @@ -264,6 +277,7 @@ software nodes using the ``fwnode`` field in struct pla= tform_device_info. leds_pdev =3D platform_device_register_full(&pdev_info); if (IS_ERR(leds_pdev)) { error =3D PTR_ERR(leds_pdev); + platform_device_unregister(gpio_pdev); goto err_unregister_nodes; } =20 @@ -274,6 +288,7 @@ software nodes using the ``fwnode`` field in struct pla= tform_device_info. keys_pdev =3D platform_device_register_full(&pdev_info); if (IS_ERR(keys_pdev)) { error =3D PTR_ERR(keys_pdev); + platform_device_unregister(gpio_pdev); platform_device_unregister(leds_pdev); goto err_unregister_nodes; } @@ -289,6 +304,7 @@ software nodes using the ``fwnode`` field in struct pla= tform_device_info. { platform_device_unregister(keys_pdev); platform_device_unregister(leds_pdev); + platform_device_unregister(gpio_pdev); software_node_unregister_node_group(myboard_swnodes); } =20 --- base-commit: 3b058d1aeeeff27a7289529c4944291613b364e9 change-id: 20260331-doc-gpio-swnodes-fc3ddf59b8dc Best regards, --=20 Bartosz Golaszewski