Differences

This shows you the differences between two versions of the page.

--- zephyr:device_drivers [2025/07/02 15:30] – [Brief] utedass
+++ zephyr:device_drivers [2025/07/08 19:08] (current) – utedass
@@ Line 21: / Line 21: @@
 | Device tree binding | ''compatible: "my,awesome-driver"'' | Also the file is named my,awesome-driver.yaml but it has no magic meaning like the rest, this is just by convention |
 | C Source | ''#define DT_DRV_COMPAT adi_ad5691'' | This is used during the building step somehow to tie the source code in |
+| C Source | ''DEVICE_DT_INST_DEFINE'' and other macros | This is probably what actually ties the driver to the device instances |
+===== DT Macros =====
+  * [[https://docs.zephyrproject.org/apidoc/latest/group__devicetree.html|Device tree documentation]]
+  * [[https://docs.zephyrproject.org/apidoc/latest/group__devicetree-generic-foreach.html|Foreach-macros]]
+  * [[https://docs.zephyrproject.org/apidoc/latest/group__devicetree-inst.html|DT_INST_ macros]]
+Many macros exist in two versions, ''DT_'' and ''DT_INST_''. The relation is for example:
+<code c>
+// Get property from node identifier
+#define DT_PROP(node_id, prop) DT_CAT3(node_id, _P_, prop)
+// Get node identifier from instance number
+#define DT_DRV_INST(inst) DT_INST(inst, DT_DRV_COMPAT)
+// Get property from instance number
+#define DT_INST_PROP(inst, prop) DT_PROP(DT_DRV_INST(inst), prop)
+</code>
+The instance number is, according to comment in ''devicetree.h'':
+<code c>
+/*
+ * All nodes with a particular compatible property value are assigned
+ * instance numbers, which are zero-based indexes specific to that
+ * compatible. You can get a node identifier for these nodes by
+ * passing DT_INST() an instance number, @p inst, along with the
+ * lowercase-and-underscores version of the compatible, @p compat.
+ *
+ * Instance numbers have the following properties:
+ *
+ * - for each compatible, instance numbers start at 0 and are contiguous
+ * - exactly one instance number is assigned for each node with a compatible,
+ *   **including disabled nodes**
+ * - enabled nodes (status property is `okay` or missing) are assigned the
+ *   instance numbers starting from 0, and disabled nodes have instance
+ *   numbers which are greater than those of any enabled node
+ * ...
+ * Nodes whose `compatible` property has multiple values are assigned
+ * independent instance numbers for each compatible.
+ */
+</code>
+So the instance nubmer is an index of all nodes with a particular compatible. Node identifier, I assume, is an index over ALL device tree nodes. So like a local vs global index.
+By checking the build folder and the generated include files, one can observe that
+<code c>
+// An instance number is a number 0 through n
+// But the node identifier will be something along the lines of DT_N_S_soc_S_i2c_40005400_S_si5351_60
+// The macro DT_INST(0, skyworks_si5351) would retrieve this define from the generated source
+#define DT_N_INST_0_skyworks_si5351 DT_N_S_soc_S_i2c_40005400_S_si5351_60
+// The DT_DRV_COMPAT that you define to something along the lines skyworks_si5351 will be just that, a token. Not anything magical.
+// But it will be used by the zephyr provided helper macros to construct the names for the defines generated by the build system to the devicetree_generated.h so that you can retrieve them
+// For example, the macro used to retrieve a property
+DT_INST_PROP(inst, plla_p1)
+// would expand to DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_plla_p1
+// According to the generated header:
+/*
+ * Devicetree node: /soc/i2c@40005400/si5351@60
+ *
+ * Node identifier: DT_N_S_soc_S_i2c_40005400_S_si5351_60
+ *
+ * Binding (compatible = skyworks,si5351):
+ *   /workspace/modules/si5351/dts/bindings/clock/skyworks,si5351.yaml
+ *
+ * (Descriptions have moved to the Devicetree Bindings Index
+ * in the documentation.)
+ */
+// Some of the generated properties looks like this
+/* Generic property macros: */
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_clkin_div 1
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_clkin_div_IDX_0_ENUM_IDX 0
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_clkin_div_IDX_0_EXISTS 1
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_clkin_div_IDX_0_ENUM_VAL_1_EXISTS 1
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_clkin_div_EXISTS 1
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_plla_p1 1638
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_plla_p1_EXISTS 1
+// For things like string enum there are a whole bunch of lines generated
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source "XTAL"
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_STRING_UNQUOTED XTAL
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_STRING_TOKEN XTAL
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_STRING_UPPER_TOKEN XTAL
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_IDX_0 "XTAL"
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_IDX_0_EXISTS 1
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_IDX_0_ENUM_IDX 0
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_IDX_0_ENUM_VAL_XTAL_EXISTS 1
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_FOREACH_PROP_ELEM(fn) fn(DT_N_S_soc_S_i2c_40005400_S_si5351_60, pllb_clock_source, 0)
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_FOREACH_PROP_ELEM_SEP(fn, sep) fn(DT_N_S_soc_S_i2c_40005400_S_si5351_60, pllb_clock_source, 0)
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_FOREACH_PROP_ELEM_VARGS(fn, ...) fn(DT_N_S_soc_S_i2c_40005400_S_si5351_60, pllb_clock_source, 0, __VA_ARGS__)
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_FOREACH_PROP_ELEM_SEP_VARGS(fn, sep, ...) fn(DT_N_S_soc_S_i2c_40005400_S_si5351_60, pllb_clock_source, 0, __VA_ARGS__)
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_LEN 1
+#define DT_N_S_soc_S_i2c_40005400_S_si5351_60_P_pllb_clock_source_EXISTS 1
+</code>