Revert "[nrf fromtree] doc: dts: simplify DT_INST documentation"

This reverts commit 9a38d5e.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

doc/reference/devicetree/index.rst

@@ -126,46 +126,11 @@ Instance-based APIs
 
 These are recommended for use within device drivers. To use them, define
 ``DT_DRV_COMPAT`` to the lowercase-and-underscores compatible the device driver
-implements support for. Here is an example devicetree fragment:
-
-.. code-block:: DTS
-
-   serial@40001000 {
-           compatible = "vnd,serial";
-           status = "okay";
-           current-speed = <115200>;
-   };
-
-Example usage, assuming serial@40001000 is the only enabled node
-with compatible "vnd,serial":
-
-.. code-block:: c
-
-   #define DT_DRV_COMPAT vnd_serial
-   DT_DRV_INST(0)                  // node identifier for serial@40001000
-   DT_INST_PROP(0, current_speed)  // 115200
-
-.. warning::
-
-   Be careful making assumptions about instance numbers. See :c:func:`DT_INST`
-   for the API guarantees.
-
-As shown above, the ``DT_INST_*`` APIs are conveniences for addressing nodes by
-instance number. They are almost all defined in terms of one of the
-:ref:`devicetree-generic-apis`. The equivalent generic API can be found by
-removing ``INST_`` from the macro name. For example, ``DT_INST_PROP(inst,
-prop)`` is equivalent to ``DT_PROP(DT_DRV_INST(inst), prop)``. Similarly,
-``DT_INST_REG_ADDR(inst)`` is equivalent to ``DT_REG_ADDR(DT_DRV_INST(inst))``,
-and so on. There are some exceptions: :c:func:`DT_ANY_INST_ON_BUS_STATUS_OKAY`
-and :c:func:`DT_INST_FOREACH_STATUS_OKAY` are special-purpose helpers without
-straightforward generic equivalents.
-
-Since ``DT_DRV_INST()`` requires ``DT_DRV_COMPAT`` to be defined, it's an error
-to use any of these without that macro defined.
-
-Note that there are also helpers available for
+implements support for. Note that there are also helpers available for
 specific hardware; these are documented in :ref:`devicetree-hw-api`.
 
+It is an error to use these macros without ``DT_DRV_COMPAT`` defined.
+
 .. doxygengroup:: devicetree-inst
    :project: Zephyr
 

include/devicetree.h

@@ -1302,7 +1302,7 @@
 #define DT_BUS_LABEL(node_id) DT_PROP(DT_BUS(node_id), label)
 
 /**
- * @brief Is a node on a bus of a given type?
+ * @brief Test if a node's bus type is a given type
  *
  * Example devicetree overlay:
  *
@@ -1320,8 +1320,7 @@
  *     DT_ON_BUS(DT_NODELABEL(temp), spi) // 0
  *
  * @param node_id node identifier
- * @param bus lowercase-and-underscores bus type as a C token (i.e.
- *            without quotes)
+ * @param bus a binding's bus type as a C token, lowercased and without quotes
  * @return 1 if the node is on a bus of the given type,
  *         0 otherwise
  */
@@ -1346,13 +1345,10 @@
 #define DT_DRV_INST(inst) DT_INST(inst, DT_DRV_COMPAT)
 
 /**
- * @brief Call "fn" on all child nodes of DT_DRV_INST(inst).
- *
- * The macro "fn" should take one argument, which is the node
- * identifier for the child node.
+ * @brief Invokes given macro for all child nodes of DT_DRV_COMPAT instance.
  *
  * @param inst instance number
- * @param fn macro to invoke on each child node identifier
+ * @param fn macro to invoke
  *
  * @see DT_FOREACH_CHILD
  */
@@ -1541,20 +1537,23 @@
 
 /**
  * @brief Get a DT_DRV_COMPAT's (only) register block address
+ * Equivalent to DT_INST_REG_ADDR_BY_IDX(inst, 0).
  * @param inst instance number
  * @return instance's register block address
  */
 #define DT_INST_REG_ADDR(inst) DT_INST_REG_ADDR_BY_IDX(inst, 0)
 
 /**
  * @brief Get a DT_DRV_COMPAT's (only) register block size
+ * Equivalent to DT_INST_REG_SIZE_BY_IDX(inst, 0).
  * @param inst instance number
  * @return instance's register block size
  */
 #define DT_INST_REG_SIZE(inst) DT_INST_REG_SIZE_BY_IDX(inst, 0)
 
 /**
  * @brief Get a DT_DRV_COMPAT interrupt specifier value at an index
+ *        (see @ref DT_IRQ_BY_IDX)
  * @param inst instance number
  * @param idx logical index into the interrupt specifier array
  * @param cell cell name specifier
@@ -1565,6 +1564,7 @@
 
 /**
  * @brief Get a DT_DRV_COMPAT interrupt specifier value by name
+ *        (see @ref DT_IRQ_BY_NAME)
  * @param inst instance number
  * @param name lowercase-and-underscores interrupt specifier name
  * @param cell cell name specifier
@@ -1574,7 +1574,8 @@
 	DT_IRQ_BY_NAME(DT_DRV_INST(inst), name, cell)
 
 /**
- * @brief Get a DT_DRV_COMPAT interrupt specifier's value
+ * @brief Get a DT_DRV_COMAPT interrupt specifier's value
+ * Equivalent to DT_INST_IRQ_BY_IDX(inst, 0, cell).
  * @param inst instance number
  * @param cell cell name specifier
  * @return the named value at that index
@@ -1583,20 +1584,23 @@
 
 /**
  * @brief Get a DT_DRV_COMPAT's (only) irq number
+ * Equivalent to DT_INST_IRQ(inst, irq).
  * @param inst instance number
  * @return the interrupt number for the node's only interrupt
  */
 #define DT_INST_IRQN(inst) DT_INST_IRQ(inst, irq)
 
 /**
  * @brief Get a DT_DRV_COMPAT's bus node's label property
+ * Equivalent to DT_BUS_LABEL(DT_DRV_INST(inst))
  * @param inst instance number
  * @return the label property of the instance's bus controller
  */
 #define DT_INST_BUS_LABEL(inst) DT_BUS_LABEL(DT_DRV_INST(inst))
 
 /**
  * @brief Test if a DT_DRV_COMPAT's bus type is a given type
+ * This is equivalent to DT_ON_BUS(DT_DRV_INST(inst), bus).
  * @param inst instance number
  * @param bus a binding's bus type as a C token, lowercased and without quotes
  * @return 1 if the given instance is on a bus of the given type,
@@ -1608,10 +1612,6 @@
  * @brief Test if any DT_DRV_COMPAT node is on a bus of a given type
  *        and has status okay
  *
- * This is a special-purpose macro which can be useful when writing
- * drivers for devices which can appear on multiple buses. One example
- * is a sensor device which may be wired on an I2C or SPI bus.
- *
  * Example devicetree overlay:
  *
  *     &i2c0 {
@@ -1636,72 +1636,32 @@
 	DT_COMPAT_ON_BUS_INTERNAL(DT_DRV_COMPAT, bus)
 
 /**
- * @brief Call "fn" on all nodes with compatible DT_DRV_COMPAT
- *        and status "okay"
- *
- * This macro calls "fn(inst)" on each "inst" number that refers to a
- * node with status "okay". Whitespace is added between invocations.
- *
- * Example devicetree fragment:
- *
- *     a {
- *             compatible = "vnd,device";
- *             status = "okay";
- *             label = "DEV_A";
- *     };
- *
- *     b {
- *             compatible = "vnd,device";
- *             status = "okay";
- *             label = "DEV_B";
- *     };
- *
- *     c {
- *             compatible = "vnd,device";
- *             status = "disabled";
- *             label = "DEV_C";
- *     };
- *
- * Example usage:
- *
- *     #define DT_DRV_COMPAT vnd_device
- *     #define MY_FN(inst) DT_INST_LABEL(inst),
- *
- *     DT_INST_FOREACH_STATUS_OKAY(MY_FN)
- *
- * This expands to:
+ * @def DT_INST_FOREACH_STATUS_OKAY
  *
- *     MY_FN(0) MY_FN(1)
- *
- * and from there, to either this:
- *
- *     "DEV_A", "DEV_B",
- *
- * or this:
- *
- *     "DEV_B", "DEV_A",
+ * @brief Call specified macro for all nodes with compatible DT_DRV_COMPAT
+ *        and status "okay"
  *
- * No guarantees are made about the order that a and b appear in the
- * expansion.
+ * @details This macro will scan for all DT_INST_ device nodes for that
+ * compatible.
  *
- * Note that "fn" is responsible for adding commas, semicolons, or
- * other separators or terminators.
+ * The macro then calls the supplied inst_expr with the instance number
+ * for each instance which has status "okay".
  *
- * Device drivers should use this macro whenever possible to
- * instantiate a struct device for each enabled node in the devicetree
- * of the driver's compatible DT_DRV_COMPAT.
+ * This macro can be used for example to call the init macro of a driver
+ * for each device specified in the device tree with "okay" status.
  *
- * @param fn Macro to call for each enabled node. Must accept an
- *           instance number as its only parameter.
+ * @param inst_expr Macro or function that is called for each device node.
+ * Has to accept instance_number as only parameter.
  */
-#define DT_INST_FOREACH_STATUS_OKAY(fn) \
+#define DT_INST_FOREACH_STATUS_OKAY(inst_expr) \
 	COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT),	\
 		    (UTIL_CAT(DT_FOREACH_OKAY_INST_,		\
-			      DT_DRV_COMPAT)(fn)),		\
+			      DT_DRV_COMPAT)(inst_expr)),	\
 		    ())
 
 /**
  * @brief Does a DT_DRV_COMPAT instance have a property?
+ * Equivalent to DT_NODE_HAS_PROP(DT_DRV_INST(inst), prop)
  * @param inst instance number
  * @param prop lowercase-and-underscores property name
  * @return 1 if the instance has the property, 0 otherwise.
@@ -1710,8 +1670,8 @@
 	DT_NODE_HAS_PROP(DT_DRV_INST(inst), prop)
 
 /**
- * @brief Does a phandle array have a named cell specifier at an index
- *        for a DT_DRV_COMPAT instance?
+ * @brief Does a phandle array have a named cell specifier at an index?
+ *        for a DT_DRV_COMPAT instance
  * @param inst instance number
  * @param pha lowercase-and-underscores property with type "phandle-array"
  * @param idx index to check
@@ -1736,6 +1696,7 @@
 
 /**
  * @brief is index valid for interrupt property on a DT_DRV_COMPAT instance?
+ * Equivalent to DT_IRQ_HAS_IDX(DT_DRV_INST(inst), idx).
  * @param inst instance number
  * @param idx logical index into the interrupt specifier array
  * @return 1 if the idx is valid for the interrupt property
@@ -1745,6 +1706,7 @@
 
 /**
  * @brief Does a DT_DRV_COMPAT instance have an interrupt named cell specifier?
+ * Equivalent to DT_IRQ_HAS_CELL_AT_IDX(DT_DRV_INST(inst), idx, cell).
  * @param inst instance number
  * @param idx index to check
  * @param cell named cell value whose existence to check
@@ -1756,6 +1718,7 @@
 
 /**
  * @brief Does a DT_DRV_COMPAT instance have an interrupt value?
+ * Equivalent to DT_INST_IRQ_HAS_IDX(DT_DRV_INST(inst), 0, cell).
  * @param inst instance number
  * @param cell named cell value whose existence to check
  * @return 1 if the named cell exists in the interrupt specifier at index 0
@@ -1766,6 +1729,7 @@
 
 /**
  * @brief Does a DT_DRV_COMPAT instance have an interrupt value?
+ * Equivalent to DT_INST_IRQ_HAS_NAME(DT_DRV_INST(inst), name).
  * @param inst instance number
  * @param name lowercase-and-underscores interrupt specifier name
  * @return 1 if "name" is a valid named specifier