Skip to contentSkip to conversation

Add generic Overlay for Grove Sunlight Sensor

RFC PATCH In review Andrew Davis 4 participants 15 messages Jul 2, 2024 – Aug 27, 2024

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover Add generic Overlay for Grove Sunlight Sensor

Hello all,

A new attempt at solving the long standing "add-on board" problem was recently posted[0]. The current out-of-tree solutions usually involve Device Tree Overlays. Recently, Overlays have started being accepted into the kernel repo, this makes now the perfect time to solve this issue. Here is my attempt at a generic solution.

Problem statement
-----------------

The Device tree(DT) system provides hardware descriptions to the Linux kernel (or other DT compatible SW). When the hardware is modular this description becomes dynamic. For this we use DT Overlays which take a base hardware description and append the description of the add-on hardware. Due to the design of DT, these DT overlays are specific to a given base hardware board. The add-on itself is usually not specific to a single board. Some examples of add-on ecosystems to consider:

Beaglebone Cape
Raspberry Pi HAT
MikroBUS Click Boards
Seeed Grove
SparkFun Qwiic
etc..

Some of these ecosystems already have more than a thousand(!) add-on boards. If a DT description needed to be written specific to each of the multitude of base boards that support each add-on, the combinatorial explosion would be unmanageable. We need to define a scheme that allow for creating and applying generic add-on overlays.

Goals
-----

* Each add-on board should be described by only one DT overlay. That DT overlay should be generic enough to apply to the DT of any base board that supports that add-on.

* Some base boards have multiple instances of a given add-ons connector port. An add-on's overlay must apply to any available connection port without modification to the overlay.

* Some connectors are stackable, stacked application of overlays shall function as expected. Chained connectors from one ecosystem to another shall be supported also (i.g. This thing[1] which connects to a BeagleBone Cape connector and then exposes a number of Grove connectors).

* We should reuse as much existing infrastructure as possible (ideally no changes should be needed). The basic application of DT overlays is well supported and documented.

* An overlay for an add-on board that is not compatible with the base board shall fail to apply at application time, not silently later. Incompatibility includes add-ons which require a function from a pin for which the matching pin on the base board cannot provide. We see this with some HATs and Capes where they use non-standard muxing of pins that only work for some subset of base boards. For instance, the BeaglePlay's Grove connector supports Digital/UART/I2C functions but not "Analog". So any Grove module that uses Analog pins should fail to apply.

* Nothing in this solution should preclude runtime application of these DT overlays. Hardware auto-detection and runtime DT modification are orthogonal problems.

Solution
--------

This is a classic many-to-many problem, we propose to solve this the same as the database folks, with an associative(join) table like adapter overlay. We add an adapter overlay in-between the base board and the add-on. This adapter overlay prepares the base DTB for the application of an add-on targeting a specific connector. Adapting the base board's specifics to accept the generic connector names contained in the add-on overlay. There will be one adapter overlay per base board connector.

We already have the infrastructure to implement these adapter overlays today. The DT overlay system makes use of a symbol table in the base DT and a fixup table in the overlay. The magic is in using the __fixups__ table to modify the __symbols__ table itself.

Let's use the Grove connector[2] as an example. Grove is a good example target as it has

* Low pin count (2 signal pins keeps the example gasket DTBOs simple, everything here can be extended to any number of signal pins)
* Multiple connectors per base board
* Has an add-on board that exposes more add-on board connectors
* Each pin can have multiple functions depending on the base board
* Moderately sized collection of add-on boards which contain parts already supported in Linux/DT

To make an overlay generic we need a standard name scheme which we use across base boards. For the connector pins the pinmux phandle shall be:

<connector-name>_<pin-name>_mux_<pin-function>

All capitalized to make it easy to identify that this name is not the final phandle name, but will instead be fixed during overlay application.

Each pin will have a definition for each function it can take, so pin1 in the Grove ecosystem has 4 possible functions, and pin2 has the same, therefor 8 definitions are needed in the connector's adapter overlay:

/* Grove connector 0 Pin1 options */
GROVE_PIN1_MUX_I2C_SCL = &grove_pins_i2c;
GROVE_PIN1_MUX_DIGITAL = &grove_pins_digital;
/* GROVE_PIN1_MUX_ANALOG not available on this pin on this connector on this board */
...
GROVE_PIN2_MUX_UART_TX = &grove_pins_uart;
etc..

(see patch [2/3] for a complete example)

By listing each pin/function combination separately we allow for add-on boards that only use a subset of pins, or mix pin functions (pin1->digital and pin2->uart_tx).

This also means is if a given base board does not support some function on a connector pin, then it is not defined and application of an overlay which uses that pin/function will correctly fail as expected.

For the parent provider phandle, we use a similar naming scheme:

<connector-name>_<pin-name>_<pin-function>

Note we list this per-pin. Even though one IP/bus may service multiple pins, we cannot know this in a generic way. For instance some boards may have all GPIO functions served by one controller, others may have some pins on different controllers.

Patch [3/3] is a complete example overlay for an add-on board[3].

So what does this all look like? Let's take an example of a BeaglePlay with two Grove connectors for which we have physically attached a Sunlight module to the first connector, and an Air Quality sensor to the second. Doing ahead of time command-line DT overlay application:

./fdtoverlay \
	-o output.dtb \
	-i k3-am625-beagleplay.dtb
		k3-am625-beagleplay-grove-connector0.dtbo grove-sunlight-sensor.dtbo \
		k3-am625-beagleplay-grove-connector1.dtbo grove-air-quality.dtbo

We start with the base board, then apply the adapter overlay for the specific connector we are going to attach the add-on. The next add-on overlay applied will attach to the connector most recently applied. This can be continued as needed, simply apply the next connector's adapter overlay, then the next add-on, rinse, repeat.

Note that the connector adapter overlay is board specific, but the add-on overlay is completely generic. It can be applied to any base board.

./fdtoverlay \
	-o output.dtb \
	-i bcm2837-rpi-3-b.dtb \
		grove-base-hat.dtbo \
			grove-base-hat-connector0.dtbo grove-sunlight-sensor.dtbo \
			grove-base-hat-connector1.dtbo grove-air-quality.dtbo

Should work just the same for any board supporting that extender HAT, for instance the BeagleY-AI would be:

./fdtoverlay \
	-o output.dtb \
	-i k3-am67a-beagley-ai.dtb \
		grove-base-hat.dtbo \
			grove-base-hat-connector0.dtbo grove-sunlight-sensor.dtbo \
			grove-base-hat-connector1.dtbo grove-air-quality.dtbo \
			grove-base-hat-connector4.dtbo etc..

All of the above works just the same at boot time (U-Boot overlay support) or runtime using the in-kernel runtime overlay support (when that is enabled). For connectors with board detection I'd expect the detector to be described in the base board connector node. On board identification, the adapter overlay for that connector would be loaded by the detector driver followed by th overlay for the identified board.

Although this is an RFC, the patches in this series are functional and meet all the above goals. They require no additional DT schema nor kernel/tooling modifications. Nested adapters (add-ons on top of add-on connectors) require a small fix in DTC which will be sent separately.

Open items
----------

Variable cell count providers. The provider specifies the cell count and meaning. For GPIO this is handled very well, there is a standard 2 cell format (GPIO number and flags). Any device can request a controllers' 4th GPIO with active high output the exact same way for all controllers. Interrupts on the other hand have providers with one, two, and even three cells variations. There is no universal way to say "I want this controller's 4th IRQ line with rising edge triggering". These cells may need some level of indirection in the connector node itself to handle variable cell counts/meanings.

Where to store the add-on overlay source files. These are not specific to any one board, nor even to one architecture. For now I put the grove-sunlight-sensor.dtb in arch/arm64/boot/dts/ti but it needs a better home acceptable by all boards.

More testing, I currently have very few add-on boards to test with right now (but I did just put some on order). Hopefully I can get some more complex ones to really exercise this idea. Maybe a stack like the one in the 4th image here[4], a RPi HAT that exposes a couple MikroBUS connectors, that then have 4 Grove ports on that.

This isn't perfect, but the Goals section should be applicable to any solution, and the adapter overlay concept hopefully can be reused as needed for whatever solution the community chooses.

Thanks,
Andrew

[0] https://lore.kernel.org/linux-arm-kernel/[email protected]/
[1] https://wiki.seeedstudio.com/Grove_Base_Cape_for_BeagleBone_v2/
[2] https://wiki.seeedstudio.com/Grove_System/
[3] https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/
[4] https://www.tindie.com/products/pmunts/mikrobus-grove-adapter-3/

Andrew Davis (3):
arm64: dts: ti: k3-am625-beagleplay: Add Grove connector pinmux
options
arm64: dts: ti: k3-am625-beagleplay: Add Grove connector adapter
overlays
arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

 arch/arm64/boot/dts/ti/Makefile               |  5 +++
 .../boot/dts/ti/grove-sunlight-sensor.dtso    | 31 ++++++++++++++
 .../k3-am625-beagleplay-grove-connector0.dtso | 41 +++++++++++++++++++
 .../k3-am625-beagleplay-grove-connector1.dtso | 22 ++++++++++
 .../arm64/boot/dts/ti/k3-am625-beagleplay.dts | 32 +++++++++++----
 5 files changed, 124 insertions(+), 7 deletions(-)
 create mode 100644 arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso
 create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector0.dtso
 create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector1.dtso
Signature · 1 line
2.39.2
#1 lore raw

RFC PATCH 1/3 arm64: dts: ti: k3-am625-beagleplay: Add Grove connector pinmux options

The Grove connector pins on BeaglePlay supports 3 different functions. Describe these here.

Also move the default to be selected by a new Grove connector node. As I2C is not the only possible function, do not enable main_i2c1. It should only be enabled when a add-on board is connected that makes use of it. That enabling should be done by the add-on board's overlay.

---
 .../arm64/boot/dts/ti/k3-am625-beagleplay.dts | 32 +++++++++++++++----
 1 file changed, 25 insertions(+), 7 deletions(-)
arch/arm64/boot/dts/ti/k3-am625-beagleplay.dts +25 -7
index 70de288d728e4..004eb5c24a84c 100644
@@ -227,6 +227,10 @@ simple-audio-card,codec {
 		};
 	};
 
+	grove_connector0: grove-connector0 {
+		pinctrl-names = "default";
+		pinctrl-0 = <&grove_pins_default>;
+	};
 };
 
 &main_pmx0 {
@@ -270,6 +274,27 @@ AM62X_IOPAD(0x01ec, PIN_INPUT_PULLUP, 0) /* (A17) I2C1_SDA */
 		>;
 	};
 
+	grove_pins_digital: grove-digital-pins {
+		pinctrl-single,pins = <
+			AM62X_IOPAD(0x01e8, PIN_INPUT, 7) /* (B17) I2C1_SCL.GPIO1_28 */
+			AM62X_IOPAD(0x01ec, PIN_INPUT, 7) /* (A17) I2C1_SDA.GPIO1_29 */
+		>;
+	};
+
+	grove_pins_uart: grove-uart-pins {
+		pinctrl-single,pins = <
+			AM62X_IOPAD(0x01e8, PIN_INPUT, 1) /* (B17) I2C1_SCL.UART1_RXD */
+			AM62X_IOPAD(0x01ec, PIN_OUTPUT, 1) /* (A17) I2C1_SDA.UART1_TXD */
+		>;
+	};
+
+	grove_pins_i2c: grove-i2c-pins {
+		pinctrl-single,pins = <
+			AM62X_IOPAD(0x01e8, PIN_INPUT_PULLUP, 0) /* (B17) I2C1_SCL */
+			AM62X_IOPAD(0x01ec, PIN_INPUT_PULLUP, 0) /* (A17) I2C1_SDA */
+		>;
+	};
+
 	local_i2c_pins_default: local-i2c-default-pins {
 		bootph-all;
 		pinctrl-single,pins = <
@@ -753,13 +778,6 @@ ldo4_reg: ldo4 {
 	};
 };
 
-&main_i2c1 {
-	pinctrl-names = "default";
-	pinctrl-0 = <&grove_pins_default>;
-	clock-frequency = <100000>;
-	status = "okay";
-};
-
 &main_i2c2 {
 	pinctrl-names = "default";
 	pinctrl-0 = <&i2c2_1v8_pins_default>;
Signature · 1 line
2.39.2
#2 lore raw

RFC PATCH 2/3 arm64: dts: ti: k3-am625-beagleplay: Add Grove connector adapter overlays

In reply to Andrew Davis

The second connector is only an example and will be removed.

---
 arch/arm64/boot/dts/ti/Makefile               |  2 +
 .../k3-am625-beagleplay-grove-connector0.dtso | 41 +++++++++++++++++++
 .../k3-am625-beagleplay-grove-connector1.dtso | 22 ++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector0.dtso
 create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector1.dtso
arch/arm64/boot/dts/ti/Makefile +2 -0
index e20b27ddf9011..a859629a6072c 100644
@@ -12,6 +12,8 @@
 dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay.dtb
 dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay-csi2-ov5640.dtbo
 dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay-csi2-tevi-ov5640.dtbo
+dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay-grove-connector0.dtbo
+dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay-grove-connector1.dtbo
 dtb-$(CONFIG_ARCH_K3) += k3-am625-phyboard-lyra-rdk.dtb
 dtb-$(CONFIG_ARCH_K3) += k3-am625-sk.dtb
 dtb-$(CONFIG_ARCH_K3) += k3-am625-verdin-nonwifi-dahlia.dtb
arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector0.dtso new file +41 -0

41 lines not on this page · raw message

arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector1.dtso new file +22 -0
new file mode 100644
index 0000000000000..1a0e463d4ec65
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: GPL-2.0-or-later OR MIT
+/**
+ * Gasket Overlay for BeaglePlay Grove Connector 1
+ *
+ * Copyright (C) 2024 Texas Instruments Incorporated - http://www.ti.com/
+ */
+
+/dts-v1/;
+/plugin/;
+
+&{/} {
+	__symbols__ {
+		GROVE_CONNECTOR = "/grove-connector1";
+
+		/* This connector does not exist on BeaglePlay, this
+		 * file is here as an example to show that add-ons cannot
+		 * be applied when the needed pins are unavailable. No
+		 * pin is available so all add-on overlays should fail
+		 * to attach to this connector.
+		 */
+	};
+};
Signature · 1 line
2.39.2
#3 lore raw

RFC PATCH 3/3 arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

In reply to Andrew Davis

Add DT overlay for the Grove Sunlight Sensor[0].

[0] https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/

---
 arch/arm64/boot/dts/ti/Makefile               |  3 ++
 .../boot/dts/ti/grove-sunlight-sensor.dtso    | 31 +++++++++++++++++++
 2 files changed, 34 insertions(+)
 create mode 100644 arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso
arch/arm64/boot/dts/ti/Makefile +3 -0
index a859629a6072c..7d1ce7a5d97bc 100644
@@ -8,6 +8,9 @@
 # Entries are grouped as per SoC present on the board. Groups are sorted
 # alphabetically.
 
+# This needs a better directory location
+dtb-$(CONFIG_OF_OVERLAY) += grove-sunlight-sensor.dtbo
+
 # Boards with AM62x SoC
 dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay.dtb
 dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay-csi2-ov5640.dtbo
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +31 -0
new file mode 100644
index 0000000000000..ab2f102e1f8ab
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-2.0-or-later OR MIT
+/**
+ * Grove - Sunlight Sensor v1.0
+ *
+ * https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/
+ *
+ * Copyright (C) 2024 Texas Instruments Incorporated - http://www.ti.com/
+ */
+
+/dts-v1/;
+/plugin/;
+
+&GROVE_CONNECTOR {
+	status = "okay";
+	pinctrl-names = "default";
+	pinctrl-0 = <&GROVE_PIN1_MUX_I2C_SCL>,
+	            <&GROVE_PIN2_MUX_I2C_SDA>;
+};
+
+&GROVE_PIN1_I2C {
+	status = "okay";
+	#address-cells = <1>;
+	#size-cells = <0>;
+
+	clock-frequency = <100000>;
+
+	si1145@60 {
+		compatible = "si,si1145";
+		reg = <0x60>;
+	};
+};
Signature · 1 line
2.39.2
#8 lore raw
In reply to Andrew Davis
Quoted 8 lines · Andrew Davis

Hello all,

A new attempt at solving the long standing "add-on board" problem was recently posted[0]. The current out-of-tree solutions usually involve Device Tree Overlays. Recently, Overlays have started being accepted into the kernel repo, this makes now the perfect time to solve this issue. Here is my attempt at a generic solution.

Thanks Andrew for taking some time to look into this. I really like the individual modules and how you can connect each overlay for multiple combinations.

I will play with/commit this in our current 6.6.x branches.

Regards,

Signature · 2 lines
Robert Nelson
https://rcn-ee.com/
#9 lore raw
In reply to Andrew Davis
Quoted 234 lines · Andrew Davis

Hello all,

A new attempt at solving the long standing "add-on board" problem was recently posted[0]. The current out-of-tree solutions usually involve Device Tree Overlays. Recently, Overlays have started being accepted into the kernel repo, this makes now the perfect time to solve this issue. Here is my attempt at a generic solution.

Problem statement
-----------------

The Device tree(DT) system provides hardware descriptions to the Linux kernel (or other DT compatible SW). When the hardware is modular this description becomes dynamic. For this we use DT Overlays which take a base hardware description and append the description of the add-on hardware. Due to the design of DT, these DT overlays are specific to a given base hardware board. The add-on itself is usually not specific to a single board. Some examples of add-on ecosystems to consider:

Beaglebone Cape
Raspberry Pi HAT
MikroBUS Click Boards
Seeed Grove
SparkFun Qwiic
etc..

Some of these ecosystems already have more than a thousand(!) add-on boards. If a DT description needed to be written specific to each of the multitude of base boards that support each add-on, the combinatorial explosion would be unmanageable. We need to define a scheme that allow for creating and applying generic add-on overlays.

Goals
-----

* Each add-on board should be described by only one DT overlay. That DT overlay should be generic enough to apply to the DT of any base board that supports that add-on.

* Some base boards have multiple instances of a given add-ons connector port. An add-on's overlay must apply to any available connection port without modification to the overlay.

* Some connectors are stackable, stacked application of overlays shall function as expected. Chained connectors from one ecosystem to another shall be supported also (i.g. This thing[1] which connects to a BeagleBone Cape connector and then exposes a number of Grove connectors).

* We should reuse as much existing infrastructure as possible (ideally no changes should be needed). The basic application of DT overlays is well supported and documented.

* An overlay for an add-on board that is not compatible with the base board shall fail to apply at application time, not silently later. Incompatibility includes add-ons which require a function from a pin for which the matching pin on the base board cannot provide. We see this with some HATs and Capes where they use non-standard muxing of pins that only work for some subset of base boards. For instance, the BeaglePlay's Grove connector supports Digital/UART/I2C functions but not "Analog". So any Grove module that uses Analog pins should fail to apply.

* Nothing in this solution should preclude runtime application of these DT overlays. Hardware auto-detection and runtime DT modification are orthogonal problems.

Solution
--------

This is a classic many-to-many problem, we propose to solve this the same as the database folks, with an associative(join) table like adapter overlay. We add an adapter overlay in-between the base board and the add-on. This adapter overlay prepares the base DTB for the application of an add-on targeting a specific connector. Adapting the base board's specifics to accept the generic connector names contained in the add-on overlay. There will be one adapter overlay per base board connector.

We already have the infrastructure to implement these adapter overlays today. The DT overlay system makes use of a symbol table in the base DT and a fixup table in the overlay. The magic is in using the __fixups__ table to modify the __symbols__ table itself.

Let's use the Grove connector[2] as an example. Grove is a good example target as it has

* Low pin count (2 signal pins keeps the example gasket DTBOs simple, everything here can be extended to any number of signal pins)
* Multiple connectors per base board
* Has an add-on board that exposes more add-on board connectors
* Each pin can have multiple functions depending on the base board
* Moderately sized collection of add-on boards which contain parts already supported in Linux/DT

To make an overlay generic we need a standard name scheme which we use across base boards. For the connector pins the pinmux phandle shall be:

<connector-name>_<pin-name>_mux_<pin-function>

All capitalized to make it easy to identify that this name is not the final phandle name, but will instead be fixed during overlay application.

Each pin will have a definition for each function it can take, so pin1 in the Grove ecosystem has 4 possible functions, and pin2 has the same, therefor 8 definitions are needed in the connector's adapter overlay:

/* Grove connector 0 Pin1 options */
GROVE_PIN1_MUX_I2C_SCL = &grove_pins_i2c;
GROVE_PIN1_MUX_DIGITAL = &grove_pins_digital;
/* GROVE_PIN1_MUX_ANALOG not available on this pin on this connector on this board */
...
GROVE_PIN2_MUX_UART_TX = &grove_pins_uart;
etc..

(see patch [2/3] for a complete example)

By listing each pin/function combination separately we allow for add-on boards that only use a subset of pins, or mix pin functions (pin1->digital and pin2->uart_tx).

This also means is if a given base board does not support some function on a connector pin, then it is not defined and application of an overlay which uses that pin/function will correctly fail as expected.

For the parent provider phandle, we use a similar naming scheme:

<connector-name>_<pin-name>_<pin-function>

Note we list this per-pin. Even though one IP/bus may service multiple pins, we cannot know this in a generic way. For instance some boards may have all GPIO functions served by one controller, others may have some pins on different controllers.

Patch [3/3] is a complete example overlay for an add-on board[3].

So what does this all look like? Let's take an example of a BeaglePlay with two Grove connectors for which we have physically attached a Sunlight module to the first connector, and an Air Quality sensor to the second. Doing ahead of time command-line DT overlay application:

./fdtoverlay \
	-o output.dtb \
	-i k3-am625-beagleplay.dtb
		k3-am625-beagleplay-grove-connector0.dtbo grove-sunlight-sensor.dtbo \
		k3-am625-beagleplay-grove-connector1.dtbo grove-air-quality.dtbo

We start with the base board, then apply the adapter overlay for the specific connector we are going to attach the add-on. The next add-on overlay applied will attach to the connector most recently applied. This can be continued as needed, simply apply the next connector's adapter overlay, then the next add-on, rinse, repeat.

Note that the connector adapter overlay is board specific, but the add-on overlay is completely generic. It can be applied to any base board.

./fdtoverlay \
	-o output.dtb \
	-i bcm2837-rpi-3-b.dtb \
		grove-base-hat.dtbo \
			grove-base-hat-connector0.dtbo grove-sunlight-sensor.dtbo \
			grove-base-hat-connector1.dtbo grove-air-quality.dtbo

Should work just the same for any board supporting that extender HAT, for instance the BeagleY-AI would be:

./fdtoverlay \
	-o output.dtb \
	-i k3-am67a-beagley-ai.dtb \
		grove-base-hat.dtbo \
			grove-base-hat-connector0.dtbo grove-sunlight-sensor.dtbo \
			grove-base-hat-connector1.dtbo grove-air-quality.dtbo \
			grove-base-hat-connector4.dtbo etc..

All of the above works just the same at boot time (U-Boot overlay support) or runtime using the in-kernel runtime overlay support (when that is enabled). For connectors with board detection I'd expect the detector to be described in the base board connector node. On board identification, the adapter overlay for that connector would be loaded by the detector driver followed by th overlay for the identified board.

Although this is an RFC, the patches in this series are functional and meet all the above goals. They require no additional DT schema nor kernel/tooling modifications. Nested adapters (add-ons on top of add-on connectors) require a small fix in DTC which will be sent separately.

Open items
----------

Variable cell count providers. The provider specifies the cell count and meaning. For GPIO this is handled very well, there is a standard 2 cell format (GPIO number and flags). Any device can request a controllers' 4th GPIO with active high output the exact same way for all controllers. Interrupts on the other hand have providers with one, two, and even three cells variations. There is no universal way to say "I want this controller's 4th IRQ line with rising edge triggering". These cells may need some level of indirection in the connector node itself to handle variable cell counts/meanings.

Where to store the add-on overlay source files. These are not specific to any one board, nor even to one architecture. For now I put the grove-sunlight-sensor.dtb in arch/arm64/boot/dts/ti but it needs a better home acceptable by all boards.

More testing, I currently have very few add-on boards to test with right now (but I did just put some on order). Hopefully I can get some more complex ones to really exercise this idea. Maybe a stack like the one in the 4th image here[4], a RPi HAT that exposes a couple MikroBUS connectors, that then have 4 Grove ports on that.

This isn't perfect, but the Goals section should be applicable to any solution, and the adapter overlay concept hopefully can be reused as needed for whatever solution the community chooses.

Thanks,
Andrew

[0] https://lore.kernel.org/linux-arm-kernel/[email protected]/
[1] https://wiki.seeedstudio.com/Grove_Base_Cape_for_BeagleBone_v2/
[2] https://wiki.seeedstudio.com/Grove_System/
[3] https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/
[4] https://www.tindie.com/products/pmunts/mikrobus-grove-adapter-3/

Andrew Davis (3):
arm64: dts: ti: k3-am625-beagleplay: Add Grove connector pinmux
options
arm64: dts: ti: k3-am625-beagleplay: Add Grove connector adapter
overlays
arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

  arch/arm64/boot/dts/ti/Makefile               |  5 +++
  .../boot/dts/ti/grove-sunlight-sensor.dtso    | 31 ++++++++++++++
  .../k3-am625-beagleplay-grove-connector0.dtso | 41 +++++++++++++++++++
  .../k3-am625-beagleplay-grove-connector1.dtso | 22 ++++++++++
  .../arm64/boot/dts/ti/k3-am625-beagleplay.dts | 32 +++++++++++----
  5 files changed, 124 insertions(+), 7 deletions(-)
Quoted 4 lines

create mode 100644 arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector0.dtso create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector1.dtso

Thanks for this work. I will try this setup for mikroBUS and report if I encounter any issues.

I do have a question: How and where should the documentation regarding these symbols live? Or is it possible to just use dt bindings for this?

Ayush Singh

#4 lore raw

Re: [PATCH RFC 3/3] arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

In reply to Andrew Davis
Quoted 39 lines · Andrew Davis

Add DT overlay for the Grove Sunlight Sensor[0].

[0] https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/

---
  arch/arm64/boot/dts/ti/Makefile               |  3 ++
  .../boot/dts/ti/grove-sunlight-sensor.dtso    | 31 +++++++++++++++++++
  2 files changed, 34 insertions(+)

create mode 100644 arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso

arch/arm64/boot/dts/ti/Makefile +3 -0
index a859629a6072c..7d1ce7a5d97bc 100644
@@ -8,6 +8,9 @@
  # Entries are grouped as per SoC present on the board. Groups are sorted
  # alphabetically.
 
+# This needs a better directory location
+dtb-$(CONFIG_OF_OVERLAY) += grove-sunlight-sensor.dtbo
+
  # Boards with AM62x SoC
  dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay.dtb
  dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay-csi2-ov5640.dtbo
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +8 -0
new file mode 100644
index 0000000000000..ab2f102e1f8ab
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-2.0-or-later OR MIT
+/**
+ * Grove - Sunlight Sensor v1.0
+ *
+ * https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/
+ *
+ * Copyright (C) 2024 Texas Instruments Incorporated - http://www.ti.com/
+ */

arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso line 18

Quoted 10 lines
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +10 -0
+
+/dts-v1/;
+/plugin/;
+
+&GROVE_CONNECTOR {
+	status = "okay";
+	pinctrl-names = "default";
+	pinctrl-0 = <&GROVE_PIN1_MUX_I2C_SCL>,
+	            <&GROVE_PIN2_MUX_I2C_SDA>;
+};

On setting pinctrl in the mikrobus connector, I seem to encounter problem with the SPI driver trying to use the device before the pins are ready. So I think, the pinctrl should probably be defined in the respective i2c, spi, etc nodes instead of connector.

arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso line 31

Quoted 13 lines
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +13 -0
+
+&GROVE_PIN1_I2C {
+	status = "okay";
+	#address-cells = <1>;
+	#size-cells = <0>;
+
+	clock-frequency = <100000>;
+
+	si1145@60 {
+		compatible = "si,si1145";
+		reg = <0x60>;
+	};
+};

I also have question regarding how to define reg property in SPI (chipselect). Ideally, we want to define it relative to the connector pins, but since the SPI device(s) is a child of SPI controller, I am not sure how I can do remapping.

Ayush Singh

#5 lore raw

Re: [PATCH RFC 3/3] arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

Quoted 44 lines · Ayush Singh
Quoted 42 lines · Andrew Davis

Add DT overlay for the Grove Sunlight Sensor[0].

[0] https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/

---
  arch/arm64/boot/dts/ti/Makefile               |  3 ++ .../boot/dts/ti/grove-sunlight-sensor.dtso    | 31 +++++++++++++++++++

  2 files changed, 34 insertions(+)

  create mode 100644 arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso

arch/arm64/boot/dts/ti/Makefile +3 -0
index a859629a6072c..7d1ce7a5d97bc 100644
@@ -8,6 +8,9 @@
   # Entries are grouped as per SoC present on the board. Groups are sorted
   # alphabetically.
+# This needs a better directory location
+dtb-$(CONFIG_OF_OVERLAY) += grove-sunlight-sensor.dtbo
+
   # Boards with AM62x SoC

  dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay.dtb dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay-csi2-ov5640.dtbo

arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +12 -0
new file mode 100644
index 0000000000000..ab2f102e1f8ab
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-2.0-or-later OR MIT
+/**
+ * Grove - Sunlight Sensor v1.0
+ *
+ * https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/
+ *
+ * Copyright (C) 2024 Texas Instruments Incorporated - http://www.ti.com/
+ */
+
+/dts-v1/;
+/plugin/;
+
Quoted 9 lines

arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso line 18

Quoted 6 lines
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +6 -0
+&GROVE_CONNECTOR {
+    status = "okay";
+    pinctrl-names = "default";
+    pinctrl-0 = <&GROVE_PIN1_MUX_I2C_SCL>,
+                <&GROVE_PIN2_MUX_I2C_SDA>;
+};

On setting pinctrl in the mikrobus connector, I seem to encounter problem with the SPI driver trying to use the device before the pins are ready. So I think, the pinctrl should probably be defined in the respective i2c, spi, etc nodes instead of connector.

Maybe, I originally did that but the issue there is it can overwrite any existing pinmux for that IP node. For instance if you add the pinmux to a GPIO node, any other users of that GPIO lose their mux.

But you are right, they belong in the IP node. Maybe even in the specific consumer device node (si1145@60 in this case).

The general idea with all of this is that if we have a board in a static state (with add-ons already attached) we could write a DTS that fully describes that steady state. Our challenge is to create an overlay that transforms the base board into what we would have written in the static case. In the static case we would have added the pinmux to the IP node, so that is where it belongs.

The issue then is the overlay mechanism is not complete. We can add properties to nodes, and add nodes to nodes, and append properties to nodes, but cannot append values to existing properties, only replace them completely. This gap in the overlay system will prevent a general solution. So I've started to work on adding that property appending ability to the overlay system. I should have some patches posted against the upstream dtc/libfdt here in the next week or so.

Quoted 8 lines
Quoted 8 lines
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +8 -0
+
+&GROVE_PIN1_I2C {
+    status = "okay";
+    #address-cells = <1>;
+    #size-cells = <0>;
+
+    clock-frequency = <100000>;
+
Quoted 9 lines

arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso line 31

Quoted 5 lines
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +5 -0
+    si1145@60 {
+        compatible = "si,si1145";
+        reg = <0x60>;
+    };
+};

I also have question regarding how to define reg property in SPI (chipselect). Ideally, we want to define it relative to the connector pins, but since the SPI device(s) is a child of SPI controller, I am not sure how I can do remapping.

Could you give me an example? Sounds like the interrupt issue, where we want say the interrupt belonging to "pin 5", but need to specify it relative to the base interrupt controller, which we cannot know anything about in the general case. Instead we need a map, from pin number to both interrupt controller and IRQ number (or SPI controller and chipselect number, etc..). I think you are on to something with the GPIO names, select the GPIO by generic name, not by board specific number. That might be extendable to IRQs and other numbered items (but yes, that is still an open item and I'm waiting on some add-on boards to arrive before I can start testing ideas on this..).

Andrew

Quoted 3 lines

Ayush Singh

#6 lore raw

Re: [PATCH RFC 3/3] arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

Quoted 71 lines · Andrew Davis
Quoted 46 lines · Ayush Singh
Quoted 44 lines · Andrew Davis

Add DT overlay for the Grove Sunlight Sensor[0].

[0] https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/

---
  arch/arm64/boot/dts/ti/Makefile               |  3 ++ .../boot/dts/ti/grove-sunlight-sensor.dtso    | 31
+++++++++++++++++++

  2 files changed, 34 insertions(+)

  create mode 100644 arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso

arch/arm64/boot/dts/ti/Makefile +3 -0
index a859629a6072c..7d1ce7a5d97bc 100644
@@ -8,6 +8,9 @@
   # Entries are grouped as per SoC present on the board. Groups are sorted
   # alphabetically.
+# This needs a better directory location
+dtb-$(CONFIG_OF_OVERLAY) += grove-sunlight-sensor.dtbo
+
   # Boards with AM62x SoC

  dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay.dtb dtb-$(CONFIG_ARCH_K3) += k3-am625-beagleplay-csi2-ov5640.dtbo

arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +7 -0
new file mode 100644
index 0000000000000..ab2f102e1f8ab
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: GPL-2.0-or-later OR MIT
+/**
+ * Grove - Sunlight Sensor v1.0
+ *
+ * https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/
+ *
+ * Copyright (C) 2024 Texas Instruments Incorporated - 

http://www.ti.com/
+ */

arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +4 -0
+
+/dts-v1/;
+/plugin/;
+
Quoted 9 lines
Quoted 6 lines

+&GROVE_CONNECTOR {
+    status = "okay";
+    pinctrl-names = "default";
+    pinctrl-0 = <&GROVE_PIN1_MUX_I2C_SCL>,
+                <&GROVE_PIN2_MUX_I2C_SDA>;
+};

On setting pinctrl in the mikrobus connector, I seem to encounter problem with the SPI driver trying to use the device before the pins are ready. So I think, the pinctrl should probably be defined in the respective i2c, spi, etc nodes instead of connector.

Maybe, I originally did that but the issue there is it can overwrite any existing pinmux for that IP node. For instance if you add the pinmux to a GPIO node, any other users of that GPIO lose their mux.

But you are right, they belong in the IP node. Maybe even in the specific consumer device node (si1145@60 in this case).

The general idea with all of this is that if we have a board in a static state (with add-ons already attached) we could write a DTS that fully describes that steady state. Our challenge is to create an overlay that transforms the base board into what we would have written in the static case. In the static case we would have added the pinmux to the IP node, so that is where it belongs.

Quoted 8 lines

The issue then is the overlay mechanism is not complete. We can add properties to nodes, and add nodes to nodes, and append properties to nodes, but cannot append values to existing properties, only replace them completely. This gap in the overlay system will prevent a general solution. So I've started to work on adding that property appending ability to the overlay system. I should have some patches posted against the upstream dtc/libfdt here in the next week or so.

Sure. Will look forward to testing it.

Quoted 19 lines
Quoted 18 lines
Quoted 4 lines
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +3 -0
+
+&GROVE_PIN1_I2C {
+    status = "okay";

arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso line 31

Quoted 10 lines
arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso new file +10 -0
+    #address-cells = <1>;
+    #size-cells = <0>;
+
+    clock-frequency = <100000>;
+
+    si1145@60 {
+        compatible = "si,si1145";
+        reg = <0x60>;
+    };
+};

I also have question regarding how to define reg property in SPI (chipselect). Ideally, we want to define it relative to the connector pins, but since the SPI device(s) is a child of SPI controller, I am not sure how I can do remapping.

Quoted 11 lines

Could you give me an example? Sounds like the interrupt issue, where we want say the interrupt belonging to "pin 5", but need to specify it relative to the base interrupt controller, which we cannot know anything about in the general case. Instead we need a map, from pin number to both interrupt controller and IRQ number (or SPI controller and chipselect number, etc..). I think you are on to something with the GPIO names, select the GPIO by generic name, not by board specific number. That might be extendable to IRQs and other numbered items (but yes, that is still an open item and I'm waiting on some add-on boards to arrive before I can start testing ideas on this..).

Yes, the same problem will also occur for interrupt. What I am referring to here is the SPI chipselect. In a child of SPI controller, the reg property in child specifies the logical chipselect using a u32 number which is then mapped to the physical chipselect by the controller. So the Mikrobus CS pin might be SPI_CS0 on one system while it might be SPI_CS1 on another. This means we need a way to do the following:

&MIKROBUS_SCK_SPI {
    status = "okay";

    #address-cells = <1>;
    #size-cells = <0>;

    lsm6dsl_click: lsm6dsl-click@MIKROBUS_CS_SPI_REG { reg = <MIKROBUS_CS_SPI_REG>; compatible = "st,lsm6ds3"; spi-max-frequency = <1000000>;
    };
};

Additionally, other pins can also be used as chipselect (Eg, SPI Extend Click uses RST and AN as chipselect). Some chipselect might be directly controlled by SPI controller while others might be normal GPIOs which were added using cs-gpios property in the controller.

of_spi_parse_dt(): https://github.com/torvalds/linux/blob/795c58e4c7fc6163d8fb9f2baa86cfe898fa4b19/drivers/spi/spi.c#L2468

Quoted 6 lines

Andrew

Quoted 3 lines

Ayush Singh

#10 lore raw
In reply to Andrew Davis

Hi Andrew,

Thanks for your series!

Quoted 11 lines · Andrew Davis

So what does this all look like? Let's take an example of a BeaglePlay with two Grove connectors for which we have physically attached a Sunlight module to the first connector, and an Air Quality sensor to the second. Doing ahead of time command-line DT overlay application:

./fdtoverlay \
        -o output.dtb \
        -i k3-am625-beagleplay.dtb
                k3-am625-beagleplay-grove-connector0.dtbo grove-sunlight-sensor.dtbo \
                k3-am625-beagleplay-grove-connector1.dtbo grove-air-quality.dtbo
Quoted 5 lines

We start with the base board, then apply the adapter overlay for the specific connector we are going to attach the add-on. The next add-on overlay applied will attach to the connector most recently applied. This can be continued as needed, simply apply the next connector's adapter overlay, then the next add-on, rinse, repeat.

Oh, that's a neat trick, eliminating the need to enhance fdtoverlay and friends with support for translating anchors while applying.

Gr{oetje,eeting}s,

Geert

Signature · 5 lines
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds
#7 lore raw

Re: [PATCH RFC 3/3] arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

In reply to Andrew Davis

Hi Andrew,

Quoted 8 lines · Andrew Davis

The issue then is the overlay mechanism is not complete. We can add properties to nodes, and add nodes to nodes, and append properties to nodes, but cannot append values to existing properties, only replace them completely. This gap in the overlay system will prevent a general solution. So I've started to work on adding that property appending ability to the overlay system. I should have some patches posted against the upstream dtc/libfdt here in the next week or so.

This is not limited to overlays, but also true for plain dts. We have /delete-node/ and /delete-property/, but lack /append-property/.

Hence we end up having to repeat all existing values when appending to a property (e.g. see [1] appending to clocks from [2]).

[2] https://elixir.bootlin.com/linux/latest/source/arch/arm64/boot/dts/renesas/r8a77951-salvator-xs.dts#L39
[1] https://elixir.bootlin.com/linux/latest/source/arch/arm64/boot/dts/renesas/r8a77951.dtsi#L3334

Gr{oetje,eeting}s,

Geert

Signature · 5 lines
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds
#11 lore raw
In reply to Andrew Davis
Quoted 234 lines · Andrew Davis

Hello all,

A new attempt at solving the long standing "add-on board" problem was recently posted[0]. The current out-of-tree solutions usually involve Device Tree Overlays. Recently, Overlays have started being accepted into the kernel repo, this makes now the perfect time to solve this issue. Here is my attempt at a generic solution.

Problem statement
-----------------

The Device tree(DT) system provides hardware descriptions to the Linux kernel (or other DT compatible SW). When the hardware is modular this description becomes dynamic. For this we use DT Overlays which take a base hardware description and append the description of the add-on hardware. Due to the design of DT, these DT overlays are specific to a given base hardware board. The add-on itself is usually not specific to a single board. Some examples of add-on ecosystems to consider:

Beaglebone Cape
Raspberry Pi HAT
MikroBUS Click Boards
Seeed Grove
SparkFun Qwiic
etc..

Some of these ecosystems already have more than a thousand(!) add-on boards. If a DT description needed to be written specific to each of the multitude of base boards that support each add-on, the combinatorial explosion would be unmanageable. We need to define a scheme that allow for creating and applying generic add-on overlays.

Goals
-----

* Each add-on board should be described by only one DT overlay. That DT overlay should be generic enough to apply to the DT of any base board that supports that add-on.

* Some base boards have multiple instances of a given add-ons connector port. An add-on's overlay must apply to any available connection port without modification to the overlay.

* Some connectors are stackable, stacked application of overlays shall function as expected. Chained connectors from one ecosystem to another shall be supported also (i.g. This thing[1] which connects to a BeagleBone Cape connector and then exposes a number of Grove connectors).

* We should reuse as much existing infrastructure as possible (ideally no changes should be needed). The basic application of DT overlays is well supported and documented.

* An overlay for an add-on board that is not compatible with the base board shall fail to apply at application time, not silently later. Incompatibility includes add-ons which require a function from a pin for which the matching pin on the base board cannot provide. We see this with some HATs and Capes where they use non-standard muxing of pins that only work for some subset of base boards. For instance, the BeaglePlay's Grove connector supports Digital/UART/I2C functions but not "Analog". So any Grove module that uses Analog pins should fail to apply.

* Nothing in this solution should preclude runtime application of these DT overlays. Hardware auto-detection and runtime DT modification are orthogonal problems.

Solution
--------

This is a classic many-to-many problem, we propose to solve this the same as the database folks, with an associative(join) table like adapter overlay. We add an adapter overlay in-between the base board and the add-on. This adapter overlay prepares the base DTB for the application of an add-on targeting a specific connector. Adapting the base board's specifics to accept the generic connector names contained in the add-on overlay. There will be one adapter overlay per base board connector.

We already have the infrastructure to implement these adapter overlays today. The DT overlay system makes use of a symbol table in the base DT and a fixup table in the overlay. The magic is in using the __fixups__ table to modify the __symbols__ table itself.

Let's use the Grove connector[2] as an example. Grove is a good example target as it has

* Low pin count (2 signal pins keeps the example gasket DTBOs simple, everything here can be extended to any number of signal pins)
* Multiple connectors per base board
* Has an add-on board that exposes more add-on board connectors
* Each pin can have multiple functions depending on the base board
* Moderately sized collection of add-on boards which contain parts already supported in Linux/DT

To make an overlay generic we need a standard name scheme which we use across base boards. For the connector pins the pinmux phandle shall be:

<connector-name>_<pin-name>_mux_<pin-function>

All capitalized to make it easy to identify that this name is not the final phandle name, but will instead be fixed during overlay application.

Each pin will have a definition for each function it can take, so pin1 in the Grove ecosystem has 4 possible functions, and pin2 has the same, therefor 8 definitions are needed in the connector's adapter overlay:

/* Grove connector 0 Pin1 options */
GROVE_PIN1_MUX_I2C_SCL = &grove_pins_i2c;
GROVE_PIN1_MUX_DIGITAL = &grove_pins_digital;
/* GROVE_PIN1_MUX_ANALOG not available on this pin on this connector on this board */
...
GROVE_PIN2_MUX_UART_TX = &grove_pins_uart;
etc..

(see patch [2/3] for a complete example)

By listing each pin/function combination separately we allow for add-on boards that only use a subset of pins, or mix pin functions (pin1->digital and pin2->uart_tx).

This also means is if a given base board does not support some function on a connector pin, then it is not defined and application of an overlay which uses that pin/function will correctly fail as expected.

For the parent provider phandle, we use a similar naming scheme:

<connector-name>_<pin-name>_<pin-function>

Note we list this per-pin. Even though one IP/bus may service multiple pins, we cannot know this in a generic way. For instance some boards may have all GPIO functions served by one controller, others may have some pins on different controllers.

Patch [3/3] is a complete example overlay for an add-on board[3].

So what does this all look like? Let's take an example of a BeaglePlay with two Grove connectors for which we have physically attached a Sunlight module to the first connector, and an Air Quality sensor to the second. Doing ahead of time command-line DT overlay application:

./fdtoverlay \
	-o output.dtb \
	-i k3-am625-beagleplay.dtb
		k3-am625-beagleplay-grove-connector0.dtbo grove-sunlight-sensor.dtbo \
		k3-am625-beagleplay-grove-connector1.dtbo grove-air-quality.dtbo

We start with the base board, then apply the adapter overlay for the specific connector we are going to attach the add-on. The next add-on overlay applied will attach to the connector most recently applied. This can be continued as needed, simply apply the next connector's adapter overlay, then the next add-on, rinse, repeat.

Note that the connector adapter overlay is board specific, but the add-on overlay is completely generic. It can be applied to any base board.

./fdtoverlay \
	-o output.dtb \
	-i bcm2837-rpi-3-b.dtb \
		grove-base-hat.dtbo \
			grove-base-hat-connector0.dtbo grove-sunlight-sensor.dtbo \
			grove-base-hat-connector1.dtbo grove-air-quality.dtbo

Should work just the same for any board supporting that extender HAT, for instance the BeagleY-AI would be:

./fdtoverlay \
	-o output.dtb \
	-i k3-am67a-beagley-ai.dtb \
		grove-base-hat.dtbo \
			grove-base-hat-connector0.dtbo grove-sunlight-sensor.dtbo \
			grove-base-hat-connector1.dtbo grove-air-quality.dtbo \
			grove-base-hat-connector4.dtbo etc..

All of the above works just the same at boot time (U-Boot overlay support) or runtime using the in-kernel runtime overlay support (when that is enabled). For connectors with board detection I'd expect the detector to be described in the base board connector node. On board identification, the adapter overlay for that connector would be loaded by the detector driver followed by th overlay for the identified board.

Although this is an RFC, the patches in this series are functional and meet all the above goals. They require no additional DT schema nor kernel/tooling modifications. Nested adapters (add-ons on top of add-on connectors) require a small fix in DTC which will be sent separately.

Open items
----------

Variable cell count providers. The provider specifies the cell count and meaning. For GPIO this is handled very well, there is a standard 2 cell format (GPIO number and flags). Any device can request a controllers' 4th GPIO with active high output the exact same way for all controllers. Interrupts on the other hand have providers with one, two, and even three cells variations. There is no universal way to say "I want this controller's 4th IRQ line with rising edge triggering". These cells may need some level of indirection in the connector node itself to handle variable cell counts/meanings.

Where to store the add-on overlay source files. These are not specific to any one board, nor even to one architecture. For now I put the grove-sunlight-sensor.dtb in arch/arm64/boot/dts/ti but it needs a better home acceptable by all boards.

More testing, I currently have very few add-on boards to test with right now (but I did just put some on order). Hopefully I can get some more complex ones to really exercise this idea. Maybe a stack like the one in the 4th image here[4], a RPi HAT that exposes a couple MikroBUS connectors, that then have 4 Grove ports on that.

This isn't perfect, but the Goals section should be applicable to any solution, and the adapter overlay concept hopefully can be reused as needed for whatever solution the community chooses.

Thanks,
Andrew

[0] https://lore.kernel.org/linux-arm-kernel/[email protected]/
[1] https://wiki.seeedstudio.com/Grove_Base_Cape_for_BeagleBone_v2/
[2] https://wiki.seeedstudio.com/Grove_System/
[3] https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/
[4] https://www.tindie.com/products/pmunts/mikrobus-grove-adapter-3/

Andrew Davis (3):
arm64: dts: ti: k3-am625-beagleplay: Add Grove connector pinmux
options
arm64: dts: ti: k3-am625-beagleplay: Add Grove connector adapter
overlays
arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

  arch/arm64/boot/dts/ti/Makefile               |  5 +++
  .../boot/dts/ti/grove-sunlight-sensor.dtso    | 31 ++++++++++++++
  .../k3-am625-beagleplay-grove-connector0.dtso | 41 +++++++++++++++++++
  .../k3-am625-beagleplay-grove-connector1.dtso | 22 ++++++++++
  .../arm64/boot/dts/ti/k3-am625-beagleplay.dts | 32 +++++++++++----
  5 files changed, 124 insertions(+), 7 deletions(-)
Quoted 4 lines

create mode 100644 arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector0.dtso create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector1.dtso

Hi Andrew,

Has there been any progress regarding this? I would be happy to help in any way if it can speed up the process.

Ayush Singh

#12 lore raw
Quoted 240 lines · Ayush Singh
Quoted 230 lines · Andrew Davis

Hello all,

A new attempt at solving the long standing "add-on board" problem was recently posted[0]. The current out-of-tree solutions usually involve Device Tree Overlays. Recently, Overlays have started being accepted into the kernel repo, this makes now the perfect time to solve this issue. Here is my attempt at a generic solution.

Problem statement
-----------------

The Device tree(DT) system provides hardware descriptions to the Linux kernel (or other DT compatible SW). When the hardware is modular this description becomes dynamic. For this we use DT Overlays which take a base hardware description and append the description of the add-on hardware. Due to the design of DT, these DT overlays are specific to a given base hardware board. The add-on itself is usually not specific to a single board. Some examples of add-on ecosystems to consider:

Beaglebone Cape
Raspberry Pi HAT
MikroBUS Click Boards
Seeed Grove
SparkFun Qwiic
etc..

Some of these ecosystems already have more than a thousand(!) add-on boards. If a DT description needed to be written specific to each of the multitude of base boards that support each add-on, the combinatorial explosion would be unmanageable. We need to define a scheme that allow for creating and applying generic add-on overlays.

Goals
-----

* Each add-on board should be described by only one DT overlay. That DT overlay should be generic enough to apply to the DT of any base board that supports that add-on.

* Some base boards have multiple instances of a given add-ons connector port. An add-on's overlay must apply to any available connection port without modification to the overlay.

* Some connectors are stackable, stacked application of overlays shall function as expected. Chained connectors from one ecosystem to another shall be supported also (i.g. This thing[1] which connects to a BeagleBone Cape connector and then exposes a number of Grove connectors).

* We should reuse as much existing infrastructure as possible (ideally no changes should be needed). The basic application of DT overlays is well supported and documented.

* An overlay for an add-on board that is not compatible with the base board shall fail to apply at application time, not silently later. Incompatibility includes add-ons which require a function from a pin for which the matching pin on the base board cannot provide. We see this with some HATs and Capes where they use non-standard muxing of pins that only work for some subset of base boards. For instance, the BeaglePlay's Grove connector supports Digital/UART/I2C functions but not "Analog". So any Grove module that uses Analog pins should fail to apply.

* Nothing in this solution should preclude runtime application of these DT overlays. Hardware auto-detection and runtime DT modification are orthogonal problems.

Solution
--------

This is a classic many-to-many problem, we propose to solve this the same as the database folks, with an associative(join) table like adapter overlay. We add an adapter overlay in-between the base board and the add-on. This adapter overlay prepares the base DTB for the application of an add-on targeting a specific connector. Adapting the base board's specifics to accept the generic connector names contained in the add-on overlay. There will be one adapter overlay per base board connector.

We already have the infrastructure to implement these adapter overlays today. The DT overlay system makes use of a symbol table in the base DT and a fixup table in the overlay. The magic is in using the __fixups__ table to modify the __symbols__ table itself.

Let's use the Grove connector[2] as an example. Grove is a good example target as it has

  * Low pin count (2 signal pins keeps the example gasket DTBOs simple, everything here can be extended to any number of signal pins)
  * Multiple connectors per base board
  * Has an add-on board that exposes more add-on board connectors
  * Each pin can have multiple functions depending on the base board
  * Moderately sized collection of add-on boards which contain parts already supported in Linux/DT

To make an overlay generic we need a standard name scheme which we use across base boards. For the connector pins the pinmux phandle shall be:

<connector-name>_<pin-name>_mux_<pin-function>

All capitalized to make it easy to identify that this name is not the final phandle name, but will instead be fixed during overlay application.

Each pin will have a definition for each function it can take, so pin1 in the Grove ecosystem has 4 possible functions, and pin2 has the same, therefor 8 definitions are needed in the connector's adapter overlay:

  /* Grove connector 0 Pin1 options */
GROVE_PIN1_MUX_I2C_SCL = &grove_pins_i2c;
GROVE_PIN1_MUX_DIGITAL = &grove_pins_digital;
/* GROVE_PIN1_MUX_ANALOG not available on this pin on this connector on this board */
...
GROVE_PIN2_MUX_UART_TX = &grove_pins_uart;
etc..

(see patch [2/3] for a complete example)

By listing each pin/function combination separately we allow for add-on boards that only use a subset of pins, or mix pin functions (pin1->digital and pin2->uart_tx).

This also means is if a given base board does not support some function on a connector pin, then it is not defined and application of an overlay which uses that pin/function will correctly fail as expected.

For the parent provider phandle, we use a similar naming scheme:

<connector-name>_<pin-name>_<pin-function>

Note we list this per-pin. Even though one IP/bus may service multiple pins, we cannot know this in a generic way. For instance some boards may have all GPIO functions served by one controller, others may have some pins on different controllers.

Patch [3/3] is a complete example overlay for an add-on board[3].

So what does this all look like? Let's take an example of a BeaglePlay with two Grove connectors for which we have physically attached a Sunlight module to the first connector, and an Air Quality sensor to the second. Doing ahead of time command-line DT overlay application:

./fdtoverlay \
    -o output.dtb \
    -i k3-am625-beagleplay.dtb k3-am625-beagleplay-grove-connector0.dtbo grove-sunlight-sensor.dtbo \
        k3-am625-beagleplay-grove-connector1.dtbo grove-air-quality.dtbo

We start with the base board, then apply the adapter overlay for the specific connector we are going to attach the add-on. The next add-on overlay applied will attach to the connector most recently applied. This can be continued as needed, simply apply the next connector's adapter overlay, then the next add-on, rinse, repeat.

Note that the connector adapter overlay is board specific, but the add-on overlay is completely generic. It can be applied to any base board.

./fdtoverlay \
    -o output.dtb \
    -i bcm2837-rpi-3-b.dtb \
        grove-base-hat.dtbo \
            grove-base-hat-connector0.dtbo grove-sunlight-sensor.dtbo \
            grove-base-hat-connector1.dtbo grove-air-quality.dtbo

Should work just the same for any board supporting that extender HAT, for instance the BeagleY-AI would be:

./fdtoverlay \
    -o output.dtb \
    -i k3-am67a-beagley-ai.dtb \
        grove-base-hat.dtbo \
            grove-base-hat-connector0.dtbo grove-sunlight-sensor.dtbo \
            grove-base-hat-connector1.dtbo grove-air-quality.dtbo \
            grove-base-hat-connector4.dtbo etc..

All of the above works just the same at boot time (U-Boot overlay support) or runtime using the in-kernel runtime overlay support (when that is enabled). For connectors with board detection I'd expect the detector to be described in the base board connector node. On board identification, the adapter overlay for that connector would be loaded by the detector driver followed by th overlay for the identified board.

Although this is an RFC, the patches in this series are functional and meet all the above goals. They require no additional DT schema nor kernel/tooling modifications. Nested adapters (add-ons on top of add-on connectors) require a small fix in DTC which will be sent separately.

Open items
----------

Variable cell count providers. The provider specifies the cell count and meaning. For GPIO this is handled very well, there is a standard 2 cell format (GPIO number and flags). Any device can request a controllers' 4th GPIO with active high output the exact same way for all controllers. Interrupts on the other hand have providers with one, two, and even three cells variations. There is no universal way to say "I want this controller's 4th IRQ line with rising edge triggering". These cells may need some level of indirection in the connector node itself to handle variable cell counts/meanings.

Where to store the add-on overlay source files. These are not specific to any one board, nor even to one architecture. For now I put the grove-sunlight-sensor.dtb in arch/arm64/boot/dts/ti but it needs a better home acceptable by all boards.

More testing, I currently have very few add-on boards to test with right now (but I did just put some on order). Hopefully I can get some more complex ones to really exercise this idea. Maybe a stack like the one in the 4th image here[4], a RPi HAT that exposes a couple MikroBUS connectors, that then have 4 Grove ports on that.

This isn't perfect, but the Goals section should be applicable to any solution, and the adapter overlay concept hopefully can be reused as needed for whatever solution the community chooses.

Thanks,
Andrew

[0] https://lore.kernel.org/linux-arm-kernel/[email protected]/
[1] https://wiki.seeedstudio.com/Grove_Base_Cape_for_BeagleBone_v2/
[2] https://wiki.seeedstudio.com/Grove_System/
[3] https://wiki.seeedstudio.com/Grove-Sunlight_Sensor/
[4] https://www.tindie.com/products/pmunts/mikrobus-grove-adapter-3/

Andrew Davis (3):
   arm64: dts: ti: k3-am625-beagleplay: Add Grove connector pinmux options
   arm64: dts: ti: k3-am625-beagleplay: Add Grove connector adapter overlays
   arm64: dts: ti: grove: Add Grove Sunlight Sensor overlay

  arch/arm64/boot/dts/ti/Makefile               |  5 +++ .../boot/dts/ti/grove-sunlight-sensor.dtso    | 31 ++++++++++++++

Quoted 8 lines
  .../k3-am625-beagleplay-grove-connector0.dtso | 41 +++++++++++++++++++
  .../k3-am625-beagleplay-grove-connector1.dtso | 22 ++++++++++
  .../arm64/boot/dts/ti/k3-am625-beagleplay.dts | 32 +++++++++++----
  5 files changed, 124 insertions(+), 7 deletions(-)

  create mode 100644 arch/arm64/boot/dts/ti/grove-sunlight-sensor.dtso create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector0.dtso create mode 100644 arch/arm64/boot/dts/ti/k3-am625-beagleplay-grove-connector1.dtso

Quoted 5 lines

Hi Andrew,

Has there been any progress regarding this? I would be happy to help in any way if it can speed up the process.

Sorry, no I've not had time to circle back to this for the last couple weeks, and don't expect to be able to for a couple more :(

The two parts I see that are missing are:

1) The /append-property/ tag [0].
2) Allowing the __symbols__ table properties to be phandles, not just full path strings.

For item 2, this will make the "adapter overlays" look much nicer, but more importantly allow chaining together adapters more easily.

Both these changes will need to be made in the DTC project, then moved back into kernel. Neither change breaks any existing compatibility so I don't expect much resistance there. It just takes some time to get changes in, then have them migrated to a kernel release before we can make use of them.

If you want to help with either of those two items (I can provide more details if needed), that could help keep this moving along. :)

Thanks,
Andrew

[0] https://lkml.org/lkml/2024/7/5/311

Quoted 3 lines

Ayush Singh

#13 lore raw
Quoted 2 lines

Sorry, no I've not had time to circle back to this for the last couple weeks, and don't expect to be able to for a couple more :(

Np, I will see what I can do.

Quoted 4 lines

The two parts I see that are missing are:

1) The /append-property/ tag [0].

So how do you envision it? Maybe something like the following:

Base:

/ {

    node {

        prop = <0x00>;

    };

};

Overlay:

&node {

    /append-property/ prop;

    prop = <0x01>;

};

Or would it be better to append 1 element at a time, as follows:

&node {

    /append-property/ prop 0x01;

};

Quoted 13 lines

2) Allowing the __symbols__ table properties to be phandles, not just full path strings.

For item 2, this will make the "adapter overlays" look much nicer, but more importantly allow chaining together adapters more easily.

Both these changes will need to be made in the DTC project, then moved back into kernel. Neither change breaks any existing compatibility so I don't expect much resistance there. It just takes some time to get changes in, then have them migrated to a kernel release before we can make use of them.

Quoted 7 lines

If you want to help with either of those two items (I can provide more details if needed), that could help keep this moving along. :)

Thanks,
Andrew

[0] https://lkml.org/lkml/2024/7/5/311

I am in the process of understanding the dtc codebase. Will send patches to device-tree mailing list since that seems to be easier to keep track of with the Linux patches instead of GitHub PRs.

Ayush Singh

#14 lore raw
Quoted 37 lines · Ayush Singh
Quoted 2 lines

Sorry, no I've not had time to circle back to this for the last couple weeks, and don't expect to be able to for a couple more :(

Np, I will see what I can do.

Quoted 4 lines

The two parts I see that are missing are:

1) The /append-property/ tag [0].

So how do you envision it? Maybe something like the following:

Base:

/ {

    node {

        prop = <0x00>;

    };

};

Overlay:

&node {

    /append-property/ prop;

    prop = <0x01>;

};

Quoted 8 lines

Or would it be better to append 1 element at a time, as follows:

&node {

    /append-property/ prop 0x01;

};

Does

/append-property/ prop = <0x01 0x02 0x03>;

work? We will want to be able to append lists. Some type checking will be needed, but shouldn't be too bad.

Probably good to get input from the DT folks which syntax looks best to them.

Quoted 17 lines
Quoted 17 lines

2) Allowing the __symbols__ table properties to be phandles, not just full path strings.

For item 2, this will make the "adapter overlays" look much nicer, but more importantly allow chaining together adapters more easily.

Both these changes will need to be made in the DTC project, then moved back into kernel. Neither change breaks any existing compatibility so I don't expect much resistance there. It just takes some time to get changes in, then have them migrated to a kernel release before we can make use of them.

If you want to help with either of those two items (I can provide more details if needed), that could help keep this moving along. :)

Quoted 8 lines
Quoted 4 lines

Thanks,
Andrew

[0] https://lkml.org/lkml/2024/7/5/311

I am in the process of understanding the dtc codebase. Will send patches to device-tree mailing list since that seems to be easier to keep track of with the Linux patches instead of GitHub PRs.

IIRC they have a dedicated mailing list for DTC,

[email protected]

Andrew

Quoted 4 lines

Ayush Singh