Custom Board Creation with nrf53 and the pinectrl.dtsi, how do I rename the file? Do I edit the nrf5340_cpuapp_common-pinectrl.dtsi?

RE: Custom Board Creation with nrf53 and the pinectrl.dtsi, how do I rename the file? Do I edit the nrf5340_cpuapp_common-pinectrl.dtsi?

Marte Myrvold — Tue, 04 Mar 2025 14:40:27 GMT

Hi,

This might be easier if you are aware of the board terminology. A board target consists of a board name, revision (if relevant), and board qualifiers. The board qualifiers are things such as SoC, CPU cluster (cores) and variant.

I will use the diagram from Board Porting Guide as an example:

The full board target here is bl5340_dvk@1.2.0/nrf5340/cpuapp/ns and breaking it down into board name, revision and board qualifiers we have the following:

Board name: bl5340_dvk
Board revision: 1.2.0
Board qualifiers:
- SoC: nrf5350
- CPU cluster: cpuapp
- Variant: ns

As mention in the porting guide, this can also be seen as board name[@revision][/SoC[/CPU cluster][/variant]].

When you make a custom board, you should rename all instances of the "board name" part of the files to correspond with your board name. I know I said earlier that, for example, nrf5340dk_common.dtsi does not need to be renamed, and this is still true, since this file is only included locally in the board files. However, I would still recommend changing all places where the board name itself is used if you want to follow the standard convention.

You do not need to rename the files that do not have the board name in the filename, e.g. nrf5340_cpuapp_common.dtsi.

[quote user="lcj"]

Following the nrf9151 directions it would look like:

nrf5340_cpuapp_common-pinctrl.dtsi
nrf5340_cpuapp_common.dtsi
mycustomboard_common.dtsi
mycustomboard_nrf5340_cpuapp.dts
mycustomboard_nrf5340_cpuapp_ns.dts
mycustomboard_nrf5340_cpunet-pinctrl.dtsi
mycustomboard_nrf5340_cpunet.dts

[/quote]

This is correct.

[quote user="lcj"]

Would you need these two files at all (I understand you would need to update references) and if you did would you change them:

nrf5340_cpuapp_common-pinctrl.dtsi
nrf5340_cpuapp_common.dtsi

[/quote]

Technically, you do not need them. However, if you do not have these files, you would have to include the devicetree configurations, including what is in the pinctrl file, in the files that include these instead, so inside mycustomboard_nrf5340_cpuapp.dts and mycustomboard_nrf5340_cpuapp_ns.dts. The reason there are common files are because these devicetree settings are the same for both board variants, i.e. both nrf5340dk/nrf5340/cpuapp and nrf5340dk/nrf5340/cpuapp/ns. So it is just to simplify things by having everything that is common for the two variants in one file instead of having it in the devicetree files of both variants.

So when it comes to this, it all comes down to preference. The same goes for the exampleboard board you mention. The important thing is that the relevant devicetree nodes are included in the relevant files (<board_name>_nrf5340_cpuapp.dts, <board_name>_nrf5340_cpuapp_ns.dts, and <board_name>_nrf5340_cpunet.dts), but whether you choose to set them directly in these files or use some sort of common files is up to you. I would recommend using common files and pinctrl for simplicity.

Best regards,
Marte

RE: Custom Board Creation with nrf53 and the pinectrl.dtsi, how do I rename the file? Do I edit the nrf5340_cpuapp_common-pinectrl.dtsi?

lcj — Sun, 02 Mar 2025 16:25:26 GMT

I think I need more prescriptive guidance. If you were to create a custom board based on the nrf5340 would you copy the nrf5340dk directory into a new directory (let's use mycustomboard) and:

What files would you need and need to rename?
What files would you need and NOT rename?
What edits would you make to the files?

The files I see are:

nrf5340_cpuapp_common-pinctrl.dtsi
nrf5340_cpuapp_common.dtsi
nrf5340dk_common.dtsi
nrf5340dk_nrf5340_cpuapp.dts
nrf5340dk_nrf5340_cpuapp_ns.dts
nrf5340dk_nrf5340_cpunet-pinctrl.dtsi
nrf5340dk_nrf5340_cpunet.dts

Following the nrf9151 directions it would look like:

nrf5340_cpuapp_common-pinctrl.dtsi
nrf5340_cpuapp_common.dtsi
mycustomboard_common.dtsi
mycustomboard_nrf5340_cpuapp.dts
mycustomboard_nrf5340_cpuapp_ns.dts
mycustomboard_nrf5340_cpunet-pinctrl.dtsi
mycustomboard_nrf5340_cpunet.dts

Would you need these two files at all (I understand you would need to update references) and if you did would you change them:

nrf5340_cpuapp_common-pinctrl.dtsi
nrf5340_cpuapp_common.dtsi

If you didn't you would need a pinctrl file, right? In a custom board you would have a different set of pins all connected to specific components, but you would not touch the net ones, correct? If that were the case you would need a different pinctrl file for this or would you only edit some of the entries in the common one?

I saw another example:

exampleboard_nrf5340_common-pinctrl.dtsi
exampleboard_nrf5340_common.dts
exampleboard_nrf5340_cpuapp.dts
exampleboard_nrf5340_cpuapp_ns.dts
exampleboard_nrf5340_cpunet-pinctrl.dtsi
exampleboard_nrf5340_cpunet.dts
exampleboard_nrf5340_partition_conf.dts

And the exampleboard_nrf5340_cpunet.dts includes changed to:

#include <nordic/nrf5340_cpunet_qkaa.dtsi>
#include "exampleboard_nrf5340_cpunet-pinctrl.dtsi"

The exampleboard_nrf5340_cpuapp.dts included:

#include <nordic/nrf5340_cpuapp_qkaa.dtsi>
#include "exampleboard_nrf5340_common.dts"

And the exampleboard_nrf5340_common.dts included:

#include "exampleboard_nrf5340_common-pinctrl.dtsi"

So they essentially created a new pinctrl file for the cpuapp, combined all cpuapp configurations into 3 files, and repointed the cpunet components not to use a common file.

It would really be helpful to know the approach from Nordic on this and more specific instructions/guidance as the nrf53 has significant differences from the nrf9151.

RE: Custom Board Creation with nrf53 and the pinectrl.dtsi, how do I rename the file? Do I edit the nrf5340_cpuapp_common-pinectrl.dtsi?

Marte Myrvold — Tue, 25 Feb 2025 09:29:36 GMT

Hi,

[quote user="lcj"]but do not need to be renamed, correct?[/quote]

Correct.

[quote user="lcj"]Which file do I edit for the pins on the new board and which files need to be included as is?[/quote]

Which file you edit depends on which core will use the pins, e.g. nrf5340_cpuapp_common-pinctrl.dtsi or nrf5340dk_nrf5340_cpunet-pinctrl.dtsi.

Best regards,
Marte

RE: Custom Board Creation with nrf53 and the pinectrl.dtsi, how do I rename the file? Do I edit the nrf5340_cpuapp_common-pinectrl.dtsi?

lcj — Thu, 20 Feb 2025 12:47:33 GMT

So a difference in the demos is that these files are needed:

nrf5340_cpuapp_common-pinctrl.dtsi
nrf5340_cpuapp_common.dtsi
nrf5340dk_common.dtsi

but do not need to be renamed, correct? They are referenced in the renamed files, so they are used.

The DevAcademy lesson only goes so far, which is understandable, but when moving from a development kit (in my case the nrf5340dk) it would be good to know what to do next. Which file do I edit for the pins on the new board and which files need to be included as is?

RE: Custom Board Creation with nrf53 and the pinectrl.dtsi, how do I rename the file? Do I edit the nrf5340_cpuapp_common-pinectrl.dtsi?

Marte Myrvold — Wed, 19 Feb 2025 09:38:34 GMT

Hi,

The nRF9151 has a simpler file structure than the nRF5340 because the nRF5340 has two cores: one application core and one network core. Because of this, there will be separate files for the two cores, and you might also have files for things common for both cores, such as the nrf5340dk_common.dtsi. You can see which core the files are for by looking at the filenames and whether they include "cpuapp" or "cpunet".

The file nrf5340dk_common.dtsi does not need to be renamed, as it is only included in the nrf5340_cpuapp_common.dtsi and nrf5340dk_nrf5340_cpunet.dts files, so as long as the filename corresponds with what is included there, then it is fine. The same is true for nrf5340_cpuapp_common.dtsi and nrf5340_cpuapp_common-pinctrl.dtsi. However, renaming them to not mix them with the DK files can still be a good idea. In that case, you can rename them whatever you want, for example, "nrf5340_devacademyl3e2-pinctrl.dtsi" if you have called your board "devacademyl3e2" Then you need to make sure to change this in the files that include the files you rename.

Best regards,
Marte