Message-ID: <8bdf668d-c120-4ed5-a0f4-fe8c0876c8d2@infradead.org>
Date: Sat, 16 Aug 2025 15:08:45 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Dmitry Torokhov <dmitry.torokhov@...il.com>,
 Linus Walleij <linus.walleij@...aro.org>, Bartosz Golaszewski
 <brgl@...ev.pl>, Jonathan Corbet <corbet@....net>
Cc: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>,
 Arnd Bergmann <arnd@...nel.org>, Hans de Goede <hansg@...nel.org>,
 linux-gpio@...r.kernel.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2] Documentation: gpio: add documentation about using
 software nodes

Hi,

I have a few more nits...


On 8/15/25 10:30 AM, Dmitry Torokhov wrote:
> Introduce documentation regarding use of software nodes to describe
> GPIOs on legacy boards that have not been converted to device tree.
> 
> Signed-off-by: Dmitry Torokhov <dmitry.torokhov@...il.com>
> ---
> 
> v2: Addressed Randy's comments.
> 
>  Documentation/driver-api/gpio/board.rst       |  65 ++++
>  Documentation/driver-api/gpio/index.rst       |   1 +
>  .../driver-api/gpio/legacy-boards.rst         | 298 ++++++++++++++++++
>  3 files changed, 364 insertions(+)
> 
> diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst
> index 4fd1cbd8296e..b802b4eef2cd 100644
> --- a/Documentation/driver-api/gpio/board.rst
> +++ b/Documentation/driver-api/gpio/board.rst
> @@ -94,6 +94,71 @@ with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
>  For more information about the ACPI GPIO bindings see
>  Documentation/firmware-guide/acpi/gpio-properties.rst.
>  
> +Software Nodes
> +--------------
> +
> +Software nodes allow board specific code to construct an in-memory,

                        board-specific

> +device-tree-like structure using struct software_node and struct
> +property_entry. This structure can then be associated with a platform device,
> +allowing drivers to use the standard device properties API to query
> +configuration, just as they would on an ACPI or device tree system.
> +
> +Software-node-backed GPIOs are described using ``PROPERTY_ENTRY_GPIO()`` macro,

                                            using the ...

> +which ties a software node representing GPIO controller with consumer device.

                              representing {a | the} GPIO controller ...

> +It allows consumers to use regular gpiolib APIs, such as gpiod_get(),
> +gpiod_get_optional().
> +
> +The software node representing GPIO controller need not be attached to the GPIO

                     representing a GPIO ...

> +controller device. The only requirement is that the node must be registered and
> +its name must match the GPIO controller's label.
> +
> +For example, here is how to describe a single GPIO-connected LED. This is an
> +alternative to using platform_data on legacy systems.
> +
> +.. code-block:: c
> +
> +	#include <linux/property.h>
> +	#include <linux/gpio/machine.h>
> +	#include <linux/gpio/property.h>
> +
> +	/*
> +	 * 1. Define a node for the GPIO controller. Its .name must match the
> +	 *    controller's label.
> +	 */
> +	static const struct software_node gpio_controller_node = {
> +		.name = "gpio-foo",
> +	};
> +
> +	/* 2. Define the properties for the LED device. */
> +	static const struct property_entry led_device_props[] = {
> +		PROPERTY_ENTRY_STRING("label", "myboard:green:status"),
> +		PROPERTY_ENTRY_STRING("linux,default-trigger", "heartbeat"),
> +		PROPERTY_ENTRY_GPIO("gpios", &gpio_controller_node, 42, GPIO_ACTIVE_HIGH),
> +		{ }
> +	};
> +
> +	/* 3. Define the software node for the LED device. */
> +	static const struct software_node led_device_swnode = {
> +		.name = "status-led",
> +		.properties = led_device_props,
> +	};
> +
> +	/*
> +	 * 4. Register the software nodes and the platform device.
> +	 */
> +	const struct software_node *swnodes[] = {
> +		&gpio_controller_node,
> +		&led_device_swnode,
> +		NULL
> +	};
> +	software_node_register_node_group(swnodes);
> +
> +	// Then register a platform_device for "leds-gpio" and associate
> +	// it with &led_device_swnode via .fwnode.
> +
> +For a complete guide on converting board files to use software nodes, see
> +Documentation/driver-api/gpio/legacy-boards.rst.
> +
>  Platform Data
>  -------------
>  Finally, GPIOs can be bound to devices and functions using platform data. Board
> diff --git a/Documentation/driver-api/gpio/index.rst b/Documentation/driver-api/gpio/index.rst
> index 43f6a3afe10b..87929840e85a 100644
> --- a/Documentation/driver-api/gpio/index.rst
> +++ b/Documentation/driver-api/gpio/index.rst
> @@ -12,6 +12,7 @@ Contents:
>     driver
>     consumer
>     board
> +   legacy-boards
>     drivers-on-gpio
>     bt8xxgpio
>  
> diff --git a/Documentation/driver-api/gpio/legacy-boards.rst b/Documentation/driver-api/gpio/legacy-boards.rst
> new file mode 100644
> index 000000000000..deef5c5cf417
> --- /dev/null
> +++ b/Documentation/driver-api/gpio/legacy-boards.rst
> @@ -0,0 +1,298 @@
> +Supporting Legacy Boards
> +========================
> +
> +Many drivers in the kernel, such as ``leds-gpio`` and ``gpio-keys``, are
> +migrating away from using board-specific ``platform_data`` to a unified device
> +properties interface. This interface allows drivers to be simpler and more
> +generic, as they can query properties in a standardized way.
> +
> +On modern systems, these properties are provided via device tree. However, some
> +older platforms have not been converted to device tree and instead rely on
> +board files to describe their hardware configuration. To bridge this gap and
> +allow these legacy boards to work with modern, generic drivers, the kernel
> +provides a mechanism called **software nodes**.
> +
> +This document provides a guide on how to convert a legacy board file from using
> +``platform_data`` and ``gpiod_lookup_table`` to the modern software node
> +approach for describing GPIO-connected devices.
> +
> +The Core Idea: Software Nodes
> +-----------------------------
> +
> +Software nodes allow board specific code to construct an in-memory,

                        board-specific

> +device-tree-like structure using struct software_node and struct
> +property_entry. This structure can then be associated with a platform device,
> +allowing drivers to use the standard device properties API (e.g.,
> +device_property_read_u32(), device_property_read_string()) to query
> +configuration, just as they would on an ACPI or device tree system.
> +
> +The gpiolib code has support for handling software nodes, so that if GPIO is
> +described properly, as detailed in the section below, then regular gpiolib APIs,
> +such as gpiod_get(), gpiod_get_optional(), and others will work.
> +
> +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 reference:
> +
> +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 the
> +    device representing GPIO controller that is providing GPIO in question.

              representing the GPIO controller that is providing the GPIO in question.


> +    It may be left as a "free floating" node.
> +


Overall, this looks good. Thanks.

Reviewed-by: Randy Dunlap <rdunlap@...radead.org>

-- 
~Randy

Powered by blists - more mailing lists