Support ROHM BD79124 ADC

There are a few use-cases where child nodes with a specific name need to be parsed. Code like:

fwnode_for_each_child_node()

	if (fwnode_name_eq())
		...

can be found from a various drivers/subsystems. Adding a macro for this can simplify things a bit.

In a few cases the data from the found nodes is later added to an array, which is allocated based on the number of found nodes. One example of such use is the IIO subsystem's ADC channel nodes, where the relevant nodes are named as channel[@N].

Add helpers for iterating and counting device's sub-nodes with certain name instead of open-coding this in every user.

Suggested-by Jonathan Cameron <[email protected]>

Signed-off-by Matti Vaittinen <[email protected]>

Reviewed-by Andy Shevchenko <[email protected]>

Reviewed-by Marcelo Schmitt <[email protected]>

---
Revision history:
v9 =>
- No changes
v8 => v9:
- Drop the fwnode_for_each_available_named_child_node() as suggested by Sakari during v8 review:
https://lore.kernel.org/all/[email protected]/
v7 => v8:
- Fix the example in fwnode_get_named_child_node_count() documentation to use the fwnode_get_named_child_node_count() and not the device_get_named_child_node_count()
- Fix the rest of the new macro's indentiations
v6 => v7:
- Improve kerneldoc
- Inline device_get_named_child_node_count() and change it to call fwnode_get_named_child_node_count() inside
- Fix indentiation of the new macros
v5 => v6:
- Add helpers to also iterate through the nodes.
v4 => v5:
- Use given name instead of string 'channel' when counting the nodes
- Add also fwnode_get_child_node_count_named() as suggested by Rob.
v3 => v4:
- New patch as suggested by Jonathan, see discussion in:
https://lore.kernel.org/lkml/20250223161338.5c896280@jic23-huawei/

---
 drivers/base/property.c  | 27 +++++++++++++++++++++++++++
 include/linux/property.h | 20 ++++++++++++++++++++
 2 files changed, 47 insertions(+)

drivers/base/property.c +27 -0

index c1392743df9c..f42f32ff45fc 100644
@@ -945,6 +945,33 @@ unsigned int device_get_child_node_count(const struct device *dev)
 }
 EXPORT_SYMBOL_GPL(device_get_child_node_count);
 
+/**
+ * fwnode_get_named_child_node_count - number of child nodes with given name
+ * @fwnode: Node which child nodes are counted.
+ * @name: String to match child node name against.
+ *
+ * Scan child nodes and count all the nodes with a specific name. Potential
+ * 'number' -ending after the 'at sign' for scanned names is ignored.
+ * E.g.::
+ *   fwnode_get_named_child_node_count(fwnode, "channel");
+ * would match all the nodes::
+ *   channel { }, channel@0 {}, channel@0xabba {}...
+ *
+ * Return: the number of child nodes with a matching name for a given device.
+ */
+unsigned int fwnode_get_named_child_node_count(const struct fwnode_handle *fwnode,
+					       const char *name)
+{
+	struct fwnode_handle *child;
+	unsigned int count = 0;
+
+	fwnode_for_each_named_child_node(fwnode, child, name)
+		count++;
+
+	return count;
+}
+EXPORT_SYMBOL_GPL(fwnode_get_named_child_node_count);
+
 bool device_dma_supported(const struct device *dev)
 {
 	return fwnode_call_bool_op(dev_fwnode(dev), device_dma_supported);

include/linux/property.h +20 -0

index e214ecd241eb..3e83babac0b0 100644
@@ -167,6 +167,10 @@ struct fwnode_handle *fwnode_get_next_available_child_node(
 	for (child = fwnode_get_next_child_node(fwnode, NULL); child;	\
 	     child = fwnode_get_next_child_node(fwnode, child))
 
+#define fwnode_for_each_named_child_node(fwnode, child, name)		\
+	fwnode_for_each_child_node(fwnode, child)			\
+		if (!fwnode_name_eq(child, name)) { } else
+
 #define fwnode_for_each_available_child_node(fwnode, child)		       \
 	for (child = fwnode_get_next_available_child_node(fwnode, NULL); child;\
 	     child = fwnode_get_next_available_child_node(fwnode, child))

@@ -178,11 +182,19 @@ struct fwnode_handle *device_get_next_child_node(const struct device *dev,
 	for (child = device_get_next_child_node(dev, NULL); child;	\
 	     child = device_get_next_child_node(dev, child))
 
+#define device_for_each_named_child_node(dev, child, name)		\
+	device_for_each_child_node(dev, child)				\
+		if (!fwnode_name_eq(child, name)) { } else
+
 #define device_for_each_child_node_scoped(dev, child)			\
 	for (struct fwnode_handle *child __free(fwnode_handle) =	\
 		device_get_next_child_node(dev, NULL);			\
 	     child; child = device_get_next_child_node(dev, child))
 
+#define device_for_each_named_child_node_scoped(dev, child, name)	\
+	device_for_each_child_node_scoped(dev, child)			\
+		if (!fwnode_name_eq(child, name)) { } else
+
 struct fwnode_handle *fwnode_get_named_child_node(const struct fwnode_handle *fwnode,
 						  const char *childname);
 struct fwnode_handle *device_get_named_child_node(const struct device *dev,

@@ -210,6 +222,14 @@ int fwnode_irq_get_byname(const struct fwnode_handle *fwnode, const char *name);
 
 unsigned int device_get_child_node_count(const struct device *dev);
 
+unsigned int fwnode_get_named_child_node_count(const struct fwnode_handle *fwnode,
+					       const char *name);
+static inline unsigned int device_get_named_child_node_count(const struct device *dev,
+							     const char *name)
+{
+	return fwnode_get_named_child_node_count(dev_fwnode(dev), name);
+}
+
 static inline int device_property_read_u8(const struct device *dev,
 					  const char *propname, u8 *val)
 {

There are a few use-cases where child nodes with a specific name need to be parsed. Code like:

fwnode_for_each_child_node()

	if (fwnode_name_eq())
		...

can be found from a various drivers/subsystems. Adding a macro for this can simplify things a bit.

In a few cases the data from the found nodes is later added to an array, which is allocated based on the number of found nodes. One example of such use is the IIO subsystem's ADC channel nodes, where the relevant nodes are named as channel[@N].

Add helpers for iterating and counting device's sub-nodes with certain name instead of open-coding this in every user.

Suggested-by Jonathan Cameron <[email protected]>

Signed-off-by Matti Vaittinen <[email protected]>

Reviewed-by Andy Shevchenko <[email protected]>

Reviewed-by Marcelo Schmitt <[email protected]>

There are ADC ICs which may have some of the AIN pins usable for other functions. These ICs may have some of the AIN pins wired so that they should not be used for ADC.

(Preferred?) way for marking pins which can be used as ADC inputs is to add corresponding channels@N nodes in the device tree as described in the ADC binding yaml.

Add couple of helper functions which can be used to retrieve the channel information from the device node.

Signed-off-by Matti Vaittinen <[email protected]>

Reviewed-by Andy Shevchenko <[email protected]>

Hi Matti,

The new helpers for ADC drivers look good to me.
I am now very late to complain about anything but am leaving some minor comments below that can be completely ignored.

Reviewed-by Marcelo Schmitt <[email protected]>

Thanks,
Marcelo

Quoted 4 lines · Matti Vaittinen

There are ADC ICs which may have some of the AIN pins usable for other functions. These ICs may have some of the AIN pins wired so that they should not be used for ADC.

Quoted 3 lines

(Preferred?) way for marking pins which can be used as ADC inputs is to add corresponding channels@N nodes in the device tree as described in the ADC binding yaml.

Not sure it's preferred to have ADC channels always declared in dt. That question was somewhat also raised during ADC doc review [1].

In short, ADC
channel may and may not be declared under ADC dt node. ADC bindings often don't enforce channels to be declared. On IIO side of things, many ADC drivers just populate channels even if they are not declared in dt.
The ADCs you are supporting in the other patches of this series seem to require dt declared channels though.

[1]: https://lore.kernel.org/linux-iio/20250118155153.2574dbe5@jic23-huawei/

Would something like

A common way of marking pins that can be used as ADC inputs is to add corresponding channel@N nodes in the device tree as described in the ADC binding yaml.

be a good rephrasing of the above paragraph?

Quoted 7 lines

Add couple of helper functions which can be used to retrieve the channel information from the device node.

Signed-off-by Matti Vaittinen <[email protected]>

Reviewed-by Andy Shevchenko <[email protected]>

...

include/linux/iio/adc-helpers.h line 20

Quoted 4 lines

include/linux/iio/adc-helpers.h new file +4 -0

+static inline int iio_adc_device_num_channels(struct device *dev)
+{
+	return device_get_named_child_node_count(dev, "channel");
+}

I wonder if this function name can eventually become misleading.

In Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml we have temperature sensor with channel nodes named after external hardware connected to the sensor, leading to channels having different node names. Can anything like that ever be accepted for ADC bindings?

Hi Marcelo,

Thanks for the review!

Quoted 16 lines · Marcelo Schmitt

Hi Matti,

The new helpers for ADC drivers look good to me.
I am now very late to complain about anything but am leaving some minor comments below that can be completely ignored.

Reviewed-by Marcelo Schmitt <[email protected]>

Thanks,
Marcelo

Quoted 4 lines · Matti Vaittinen

There are ADC ICs which may have some of the AIN pins usable for other functions. These ICs may have some of the AIN pins wired so that they should not be used for ADC.

Quoted 5 lines

Quoted 3 lines

(Preferred?) way for marking pins which can be used as ADC inputs is to add corresponding channels@N nodes in the device tree as described in the ADC binding yaml.

Not sure it's preferred to have ADC channels always declared in dt. That question was somewhat also raised during ADC doc review [1].

I had missed that doc and the review. Interesting read, thanks for pointing it :)

We did also do a bit discussion about this during the review of the earlier versions. I am not sure if we found an ultimate common consensus though :)

A recap as seen through my eyes:

- It is preferred to have either _all_ or _none_ of the channels described in the device tree.
https://lore.kernel.org/all/20250201162631.2eab9a9a@jic23-huawei/

- This, however, is not _always_ required to be followed, and it may be impractical in some cases:
https://lore.kernel.org/linux-iio/[email protected]/#t

- We do have bunch of existing drivers which we need to support. With some very different approaches to bindings.
https://lore.kernel.org/linux-iio/20250302032054.1fb8a011@jic23-huawei/

My _personal_ thinking is that:

This means that we can't hide the binding parsing in the IIO-core. We can't go and change the channels in existing drivers.

But, we can provide helpers (like this one) for drivers to use. I also believe we should still try to have common (and preferred!) approach for the _new_ drivers. Eventually, the new ones will be majority. Some of the old ones die, and if we keep same practices for new ones, the old ones will become rare exceptions while majority follows same principles ;)

Quoted 9 lines

In short, ADC
channel may and may not be declared under ADC dt node. ADC bindings often don't enforce channels to be declared. On IIO side of things, many ADC drivers just populate channels even if they are not declared in dt.
The ADCs you are supporting in the other patches of this series seem to require dt declared channels though.

[1]: https://lore.kernel.org/linux-iio/20250118155153.2574dbe5@jic23-huawei/

Quoted 7 lines

Would something like

A common way of marking pins that can be used as ADC inputs is to add corresponding channel@N nodes in the device tree as described in the ADC binding yaml.

be a good rephrasing of the above paragraph?

Yes, if we don't want to guide new drivers to either have all usable channels, or no channels in the device tree.

I think Jonathan said he'll be rebasing this to rc1. I am a newcomer and I should not enforce my view over more experienced ones ;) So, feel free to reword the description as Marcelo suggests if you don't think we should prefer one direction or the other.

Quoted 15 lines

Quoted 8 lines

Add couple of helper functions which can be used to retrieve the channel information from the device node.

Signed-off-by Matti Vaittinen <[email protected]>

Reviewed-by Andy Shevchenko <[email protected]>

...

include/linux/iio/adc-helpers.h line 20

Quoted 4 lines

include/linux/iio/adc-helpers.h new file +4 -0

+static inline int iio_adc_device_num_channels(struct device *dev)
+{
+	return device_get_named_child_node_count(dev, "channel");
+}  

I wonder if this function name can eventually become misleading.

Quoted 4 lines

In Documentation/devicetree/bindings/iio/temperature/adi,ltc2983.yaml we have temperature sensor with channel nodes named after external hardware connected to the sensor, leading to channels having different node names. Can anything like that ever be accepted for ADC bindings?

My initial thinking is that the hardware which is connected to the ADC should have it's own node - and there should be only a reference from the ADC to the other hardware's description. I think the connected hardware should not be a property of the ADC channel.

Anyways, the current ADC binding (bindings/iio/adc/adc.yaml) says the node name must be channel[@xxx] (which, I believe makes sense as it makes it easier to understand device-trees for ICs which may provide other nodes but ADC channels too).

properties:
$nodename:
pattern: "^channel(@[0-9a-f]+)?$"
description:
A channel index should match reg.

Yours,
-- Matti

Quoted 77 lines · On Mon, 31 Mar 2025 08:39:35 +0300 Matti Vaittinen <[email protected]>…

Hi Marcelo,

Thanks for the review!

Quoted 16 lines · Marcelo Schmitt

Hi Matti,

The new helpers for ADC drivers look good to me.
I am now very late to complain about anything but am leaving some minor comments below that can be completely ignored.

Reviewed-by Marcelo Schmitt <[email protected]>

Thanks,
Marcelo

Quoted 4 lines · Matti Vaittinen

There are ADC ICs which may have some of the AIN pins usable for other functions. These ICs may have some of the AIN pins wired so that they should not be used for ADC.

Quoted 5 lines

Quoted 3 lines

(Preferred?) way for marking pins which can be used as ADC inputs is to add corresponding channels@N nodes in the device tree as described in the ADC binding yaml.

Not sure it's preferred to have ADC channels always declared in dt. That question was somewhat also raised during ADC doc review [1].

I had missed that doc and the review. Interesting read, thanks for pointing it :)

We did also do a bit discussion about this during the review of the earlier versions. I am not sure if we found an ultimate common consensus though :)

A recap as seen through my eyes:

- It is preferred to have either _all_ or _none_ of the channels described in the device tree.
https://lore.kernel.org/all/20250201162631.2eab9a9a@jic23-huawei/

- This, however, is not _always_ required to be followed, and it may be impractical in some cases:
https://lore.kernel.org/linux-iio/[email protected]/#t

- We do have bunch of existing drivers which we need to support. With some very different approaches to bindings.
https://lore.kernel.org/linux-iio/20250302032054.1fb8a011@jic23-huawei/

My _personal_ thinking is that:

This means that we can't hide the binding parsing in the IIO-core. We can't go and change the channels in existing drivers.

But, we can provide helpers (like this one) for drivers to use. I also believe we should still try to have common (and preferred!) approach for the _new_ drivers. Eventually, the new ones will be majority. Some of the old ones die, and if we keep same practices for new ones, the old ones will become rare exceptions while majority follows same principles ;)

Quoted 9 lines

In short, ADC
channel may and may not be declared under ADC dt node. ADC bindings often don't enforce channels to be declared. On IIO side of things, many ADC drivers just populate channels even if they are not declared in dt.
The ADCs you are supporting in the other patches of this series seem to require dt declared channels though.

[1]: https://lore.kernel.org/linux-iio/20250118155153.2574dbe5@jic23-huawei/

Quoted 7 lines

Would something like

A common way of marking pins that can be used as ADC inputs is to add corresponding channel@N nodes in the device tree as described in the ADC binding yaml.

be a good rephrasing of the above paragraph?

Quoted 7 lines

Yes, if we don't want to guide new drivers to either have all usable channels, or no channels in the device tree.

I think Jonathan said he'll be rebasing this to rc1. I am a newcomer and I should not enforce my view over more experienced ones ;) So, feel free to reword the description as Marcelo suggests if you don't think we should prefer one direction or the other.

I've gone with Marcelo's suggestion because I don't want to be too specific
here given the complex history. We can absolutely encourage the all or
nothing description going forwards though as it is logical in the vast majority of cases.

The ROHM BD79124 is a 12-bit, 8-channel, SAR ADC. The ADC supports an automatic measurement mode, with an alarm interrupt for out-of-window measurements. The window is configurable for each channel.

The I2C protocol for manual start of the measurement and data reading is somewhat peculiar. It requires the master to do clock stretching after sending the I2C slave-address until the slave has captured the data. Needless to say this is not well suopported by the I2C controllers.

Thus do not support the BD79124's manual measurement mode but implement the measurements using automatic measurement mode, relying on the BD79124's ability of storing latest measurements into register.

Support also configuring the threshold events for detecting the out-of-window events.

The BD79124 keeps asserting IRQ for as long as the measured voltage is out of the configured window. Thus, prevent the user-space from choking on the events and mask the received event for a fixed duration (1 second) when an event is handled.

The ADC input pins can be also configured as general purpose outputs. Make those pins which don't have corresponding ADC channel node in the device-tree controllable as GPO.

Quoted 16 lines · Matti Vaittinen

The ROHM BD79124 is a 12-bit, 8-channel, SAR ADC. The ADC supports an automatic measurement mode, with an alarm interrupt for out-of-window measurements. The window is configurable for each channel.

The I2C protocol for manual start of the measurement and data reading is somewhat peculiar. It requires the master to do clock stretching after sending the I2C slave-address until the slave has captured the data. Needless to say this is not well suopported by the I2C controllers.

Thus do not support the BD79124's manual measurement mode but implement the measurements using automatic measurement mode, relying on the BD79124's ability of storing latest measurements into register.

Support also configuring the threshold events for detecting the out-of-window events.

Quoted 8 lines

The BD79124 keeps asserting IRQ for as long as the measured voltage is out of the configured window. Thus, prevent the user-space from choking on the events and mask the received event for a fixed duration (1 second) when an event is handled.

The ADC input pins can be also configured as general purpose outputs. Make those pins which don't have corresponding ADC channel node in the device-tree controllable as GPO.

Thank you for the nicely written driver! However, I have one big issue with it (see below).

...

drivers/iio/adc/rohm-bd79124.c line 207

Quoted 3 lines

drivers/iio/adc/rohm-bd79124.c new file +3 -0

+static void bd79124gpo_set(struct gpio_chip *gc, unsigned int offset, int value)
+static void bd79124gpo_set_multiple(struct gpio_chip *gc, unsigned long *mask,
+				    unsigned long *bits)  

These will be _rv variants anyway as there is no chance this series goes before that.

...

drivers/iio/adc/rohm-bd79124.c line 266

Quoted 9 lines

drivers/iio/adc/rohm-bd79124.c new file +9 -0

+struct bd79124_raw {
+	u8 val_bit3_0; /* Is set in high bits of the byte */
+	u8 val_bit11_4;
+};
+#define BD79124_RAW_TO_INT(r) ((r.val_bit11_4 << 4) | (r.val_bit3_0 >> 4))
+#define BD79124_INT_TO_RAW(val) {					\
+	.val_bit11_4 = (val) >> 4,					\
+	.val_bit3_0 = (val) << 4,					\
+}  

All the rest is fine to me and looks good, but above is a principal impediment to give you my tag. In case you update the type to __le16, feel free to add my Reviewed-by tag.

Quoted 31 lines · On Mon, 24 Mar 2025 10:23:52 +0200 Andy Shevchenko…

Quoted 16 lines · Matti Vaittinen

The ROHM BD79124 is a 12-bit, 8-channel, SAR ADC. The ADC supports an automatic measurement mode, with an alarm interrupt for out-of-window measurements. The window is configurable for each channel.

The I2C protocol for manual start of the measurement and data reading is somewhat peculiar. It requires the master to do clock stretching after sending the I2C slave-address until the slave has captured the data. Needless to say this is not well suopported by the I2C controllers.

Thus do not support the BD79124's manual measurement mode but implement the measurements using automatic measurement mode, relying on the BD79124's ability of storing latest measurements into register.

Support also configuring the threshold events for detecting the out-of-window events.

Quoted 8 lines

The BD79124 keeps asserting IRQ for as long as the measured voltage is out of the configured window. Thus, prevent the user-space from choking on the events and mask the received event for a fixed duration (1 second) when an event is handled.

The ADC input pins can be also configured as general purpose outputs. Make those pins which don't have corresponding ADC channel node in the device-tree controllable as GPO.

Thank you for the nicely written driver! However, I have one big issue with it (see below).

...

Quoted 5 lines

drivers/iio/adc/rohm-bd79124.c line 207

Quoted 3 lines

drivers/iio/adc/rohm-bd79124.c new file +3 -0

+static void bd79124gpo_set(struct gpio_chip *gc, unsigned int offset, int value)
+static void bd79124gpo_set_multiple(struct gpio_chip *gc, unsigned long *mask,
+				    unsigned long *bits)

These will be _rv variants anyway as there is no chance this series goes before that.

I don't mind seeing this as a follow up series, but I would like that to hit this cycle if possible.

The ROHM BD79124 is a 12-bit, 8-channel, SAR ADC. The ADC supports an automatic measurement mode, with an alarm interrupt for out-of-window measurements. The window is configurable for each channel.

The I2C protocol for manual start of the measurement and data reading is somewhat peculiar. It requires the master to do clock stretching after sending the I2C slave-address until the slave has captured the data. Needless to say this is not well suopported by the I2C controllers.

Thus do not support the BD79124's manual measurement mode but implement the measurements using automatic measurement mode, relying on the BD79124's ability of storing latest measurements into register.

Support also configuring the threshold events for detecting the out-of-window events.

The BD79124 keeps asserting IRQ for as long as the measured voltage is out of the configured window. Thus, prevent the user-space from choking on the events and mask the received event for a fixed duration (1 second) when an event is handled.

The ADC input pins can be also configured as general purpose outputs. Make those pins which don't have corresponding ADC channel node in the device-tree controllable as GPO.

Signed-off-by Matti Vaittinen <[email protected]>

drivers/iio/adc/rohm-bd79124.c new file +24 -0

new file mode 100644
index 000000000000..099eccaa2232
@@ -0,0 +1,1147 @@
 
 
+static int bd79124_read_event_value(struct iio_dev *iio_dev,
+				    const struct iio_chan_spec *chan,
+				    enum iio_event_type type,
+				    enum iio_event_direction dir,
+				    enum iio_event_info info, int *val,
+				    int *val2)
+{
+	struct bd79124_data *data = iio_priv(iio_dev);
+	int ret, reg;
+
+	if (chan->channel >= BD79124_MAX_NUM_CHANNELS)
+		return -EINVAL;
+
+	switch (info) {
+	case IIO_EV_INFO_VALUE:
+		if (dir == IIO_EV_DIR_RISING)
+			*val = data->alarm_r_limit[chan->channel];
+		else if (dir == IIO_EV_DIR_FALLING)
+			*val = data->alarm_f_limit[chan->channel];
+		else
+			return -EINVAL;
+
+		return IIO_VAL_INT;
+