device: Add helper function to find matching device on bus

This change adds a helper function dev_find_matching_device_on_bus()
which scans all the child devices on the given bus and calls a
match function provided by the caller. It returns the first device
that the match function returns true for, else NULL if no such device
is found.

Change-Id: I2e3332c0a175ab995c523f078f29a9f498f17931
Signed-off-by: Furquan Shaikh <furquan@google.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/40543
Reviewed-by: Aaron Durbin <adurbin@chromium.org>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

src/device/device_const.c

@@ -70,6 +70,19 @@ DEVTREE_CONST struct device *dev_find_path(
 	return result;
 }
 
+DEVTREE_CONST struct device *dev_find_matching_device_on_bus(const struct bus *bus,
+							match_device_fn fn)
+{
+	DEVTREE_CONST struct device *child = NULL;
+
+	while ((child = dev_bus_each_child(bus, child)) != NULL) {
+		if (fn(child))
+			break;
+	}
+
+	return child;
+}
+
 /**
  * Given a device pointer, find the next PCI device.
  *

src/include/device/device.h

@@ -207,6 +207,19 @@ DEVTREE_CONST struct device *dev_find_path(
 struct device *dev_find_lapic(unsigned int apic_id);
 int dev_count_cpu(void);
 
+/*
+ * Signature for matching function that is used by dev_find_matching_device_on_bus() to decide
+ * if the device being considered is the one that matches the caller's criteria. This function
+ * is supposed to return true if the provided device matches the criteria, else false.
+ */
+typedef bool (*match_device_fn)(DEVTREE_CONST struct device *dev);
+/*
+ * Returns the first device on the bus that the match_device_fn returns true for. If no such
+ * device is found, it returns NULL.
+ */
+DEVTREE_CONST struct device *dev_find_matching_device_on_bus(const struct bus *bus,
+							match_device_fn fn);
+
 struct device *add_cpu_device(struct bus *cpu_bus, unsigned int apic_id,
 				int enabled);
 void set_cpu_topology(struct device *cpu, unsigned int node,