[coreboot-gerrit] Change in coreboot[master]: device: add commentary to dev_find_slot()

[Aaron Durbin (Code Review)]

Aaron Durbin has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/35632 )

Change subject: device: add commentary to dev_find_slot()
......................................................................

device: add commentary to dev_find_slot()

dev_find_slot() can fail sometimes fail to return the
desired device object prior to full PCI enumeration. Comment
the declaration and implementation accordingly to help the
user understand the problem and avoid its usage.

Change-Id: I3fe1f24ff015d3e4f272323947f057e4c910186c
Signed-off-by: Aaron Durbin 
---
M src/device/device_const.c
M src/include/device/device.h
2 files changed, 14 insertions(+), 1 deletion(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/32/35632/1

diff --git a/src/device/device_const.c b/src/device/device_const.c
index 5143563..27197f2 100644
--- a/src/device/device_const.c
+++ b/src/device/device_const.c
@@ -24,6 +24,12 @@
 /**
  * Given a PCI bus and a devfn number, find the device structure.
  *
+ * Note that this function can return the incorrect device prior
+ * to PCI enumeration because the secondary field of the bus object
+ * is 0. The failing scenario is determined by the order of the
+ * devices in all_devices singly-linked list as well as the time
+ * when this function is called (secondary reflecting topology).
+ *
  * @param bus The bus number.
  * @param devfn A device/function number.
  * @return Pointer to the device structure (if found), 0 otherwise.
diff --git a/src/include/device/device.h b/src/include/device/device.h
index b2221cc..f24e4b2 100644
--- a/src/include/device/device.h
+++ b/src/include/device/device.h
@@ -298,7 +298,14 @@
 DEVTREE_CONST struct device *pcidev_on_root(uint8_t dev, uint8_t fn);
 DEVTREE_CONST struct bus *pci_root_bus(void);

-/* To be deprecated, avoid using. */
+/* To be deprecated, avoid using.
+ *
+ * Note that this function can return the incorrect device prior
+ * to PCI enumeration because the secondary field of the bus object
+ * is 0. The failing scenario is determined by the order of the
+ * devices in all_devices singly-linked list as well as the time
+ * when this function is called (secondary reflecting topology).
+ */
 DEVTREE_CONST struct device *dev_find_slot(unsigned int bus, unsigned int devfn);
 DEVTREE_CONST struct device *pcidev_path_on_root_debug(pci_devfn_t devfn, const char *func);