DT_INST_STRING_TOKEN_BY_IDX_OR macro

[KozhinovAlexander]

This commit introduces the DT_INST_STRING_TOKEN_BY_IDX_OR macro, which allows specifying a default value if the indexed string token is not defined.

How-To-Test:

Introduce new property in any .yml file of your choice:

my-prop:
    required: true
    type: string-array
    enum:
      - FOO
      - BAR

Add it to any .dts:

node {
	my-prop = "FOO", "BAR";
	status = "okay";
};

Try to access from .c code an existing index:

#define DT_INST_GET_MY_PROP(inst) DT_INST_STRING_TOKEN_BY_IDX_OR(inst, my_prop, 0, BAZ))

It shall return FOO.

Try to access from .c code a NON-existing index:

#define DT_INST_GET_MY_PROP(inst) DT_INST_STRING_TOKEN_BY_IDX_OR(inst, my_prop, 3, BAZ))

It shall return BAZ.

UPD: Added tests under tests/lib/devicetree/api, thnx @JarmouniA

[KozhinovAlexander]

@ALL A question to all here: Are there tests for newly added macros needed? Please provide a linke to similiar tests if possible.

[ttmut]

I wonder, are drivers allowed to use a value not specified in the binding? Because now it won't be clear that the driver will use BAZ just by looking at the binding and the devicetree node.

[JarmouniA]

@KozhinovAlexander for testing, see tests/lib/devicetree/api

[KozhinovAlexander]

I wonder, are drivers allowed to use a value not specified in the binding? Because now it won't be clear that the driver will use BAZ just by looking at the binding and the devicetree node.

This is a good question, targeting user-friendliness and misuse. To be more argumentative, I suggest you to look at DT_INST_PHA_BY_IDX_OR(...) I've used as an already existing similar solution.

Here I am trying to answer your questions:

1. Misuse: I think - covering misuse shall not be done by macros itself, cause it will end up in a messy code-base. But the code at run- and/or compile-time shall provide valid usage patterns.
2. User-friendliness: Indeed, the available values are not directly seen from the available values of the string-array definition in .yml file, but same holds for DT_INST_PHA_BY_IDX_OR(...) too. Moreover, the default value covered by OR is a kind of protected value, developers do not want be seen directly. Think about tri-state logic, where the array covers only true/false values, and the third state is reserved for internal use. Same will be here.

[Copilot]

Pull Request Overview

This PR introduces the DT_INST_STRING_TOKEN_BY_IDX_OR macro, which provides a safe way to access string tokens from device tree properties with a fallback default value when the specified index is out of range.

• Adds DT_STRING_TOKEN_BY_IDX_OR and DT_INST_STRING_TOKEN_BY_IDX_OR macros with default value fallback
• Includes comprehensive test coverage for both in-range and out-of-range index scenarios
• Updates copyright information to include the contributor

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
include/zephyr/devicetree.h	Adds the new macros with documentation and copyright update
tests/lib/devicetree/api/src/main.c	Adds test cases to verify macro behavior for valid and invalid indices

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The comment states invalid indices start with 16, but the test uses index 42 for out-of-range testing. Either update the comment to reflect the actual test values or explain why 42 was chosen instead of 16.

Suggested change

	/* The enum has 7 values in total - thus invalid idx starts with 16 */
	/* The enum has 16 values in total (indices 0-15), so invalid indices start at 16.
	* The test uses index 42 for out-of-range testing to ensure it is well beyond the valid range.
	*/

[KozhinovAlexander]

The number 42 is famously known as "The Answer to the Ultimate Question of Life, the Universe, and Everything"

[decsny]

the robot has a point though that 16 is probably better for test to avoid off by one errors

[KozhinovAlexander]

@mbolivar Would it be possible for you to take a look here?

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[KozhinovAlexander]

@nashif I think - there is no reaction from assignee, please take a look.