Device Tree Configuration Guidelines

[Alan Jones]

Can Nordic provide general guidelines for manipulating the device tree configuration files for custom boards?

For instance, does the application require the exact same pin mapping as the SPM loader? If not, what if there are pin mappings for a UART during boot for instance, but the application disables the UART and repurposes those pins to GPIO in either the application device tree or the project's overlay file? Is the application required to use only a subset of the SPM peripherals? How are peripheral or pin conflicts resolved by the current build process which defaults to generating a merged hex file?

There also seem to be build issues with locating the out of tree board directory in the application directory, which would be preferable for simplifying application version control.

[Simon]

The SPM sample (ncs\nrf\samples\nrf9160\spm) does not map any pins. The only thing the SPM sample does is to set the security attribute of the peripherals (It also configures flash/ram as secure/non-secure, but this is not relevant for your question) listed in periph_cfg periph[] to either secure or secure (depending on the configurations in ncs/nrf/subsys/spm/Kconfig).

However, some peripherals does not work with a non-secure application (e.g. PWM0), due to their absence in Kconfig or spm.c. You will have to add it, as the customer did here.

Best regards,

Simon

[Steven]

OfflineAlan Jonesover 2 years ago

What about this though?

"Can Nordic provide general guidelines for manipulating the device tree configuration files for custom boards?"

Can you point me to any examples please?

[Simon]

Check out this: https://devzone.nordicsemi.com/nordic/nrf-connect-sdk-guides/b/getting-started/posts/nrf-connect-sdk-tutorial---part-3-ncs-v1-4-0#h11sk6ks1jkp1figkuq6gxw1m1rctdp0 

[Steven]

With respect, I feel like you're coming from a place where you have a very good knowledge of the SDK and to you these things are obvious. To someone coming to this for the first time it's far from obvious!

If you take this paragraph...

If your board has LEDs and buttons connected to the chip's GPIOs, and you want to access it using the Zephyr API, you should include it into the Device Tree. This can be done by incorporating the nodes described in ../bindings/gpio/gpio-leds.yaml and ../bindings/gpio/gpio-keys.yaml into your dts files respectively. You simply select the pins the buttons and LEDs are connected to and choose a label. If you create aliases for the nodes, the generated names will be simplified and easier accessible in your samples. E.g. LED1_GPIO_PIN can be used instead of DT_GPIO_LEDS_LED_1_GPIO_PIN.

...it doesn't really help a very great deal!

For instance, you need to illustrate what you mean when you say "You simply select the pins the buttons and LEDs are connected to and choose a label. If you create aliases for the nodes, the generated names will be simplified and easier accessible in your samples"

Ok, well what does that look like? A worked example, using a development kit and some off board leds and switches, would be really useful. Something like this:

https://devzone.nordicsemi.com/nordic/nrf-connect-sdk-guides/b/peripherals/posts/adding-a-peripheral-to-an-ncs-zephyr-project 

Worked examples are really helpful and instructive way to  learn your way around the documentation and folder structure so you can understand how to manipulate the files and work towards building up an overlay file for a custom board. Because, ultimately, that's all we're interested in, right?

If I want to give my board overlay some meaningful labels, perhaps because I'm driving a relay or a buzzer, what does that look like? How do I move beyond predefined labels for the DK?

So, really, worked examples for each of the device peripherals, please.

PS I'd be happy to write a blog post(s) to document the process and help out, I could do with some guidance though!

[Simon]

The first part (2.1 The board files) are just theoretical explanations. I should probably have pointed you to the practical part (2.2 Walkthrough) which demonstrates step-by-step how to create a new custom board in NCS v1.4.0 (shouldn't be too different from NCS v1.5.0).

If you follow the steps in 2.2 Walkthrough you will end up with a custom board folder in zephyr/boards/arm/test_nrf9160, and you can manipulate the device tree configurations by modifying the files ending with dts (please tell me if I should elaborate on the different dts files).

Now you know what files to modfiy to change the device tree configurations for your custom board. However, how you should modify it is another question. That require some knowledge about how the device tree works, and for that I would recommend you to read the following: Devicetree API. Sometimes, if you just want to do some simple things, you may not need that deep knowledge of the device tree, you can just look at other board files and its dts files to understand how to go about it.

If you have some inputs of how 2.2 Walkthrough could get improved, I would be happy to hear. Do you think it would be useful for another blog post exending on this, that focuses on how to modify the dts files?

Best regards,

Simon