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]

I have been through the devacademy lesson on custom boards and am using the nRF53 so have used the custom board for multi-core approach. The example uses the 9151 which has a simpler file structure. Do I equate the changes to the nrf9151ds_nrf9151_pinectrl.dtsi with the nrf5340_cpuapp_common-pinectrl.dtsi?

The naming convention is different in the nrf5340 directory. It does not start with the nrf5340dk. It starts with the nrf5340 and is not preceeded by the nrf5340dk. Do I change the name? Is that where I make my edits?

I also see the nrf5340dk_common.dtsi but it ony really has the leds, buttons, and some alias'.

I'm not sure how I should change my file structure to accomodate the changes. What should the file structure look like with a custom board (say mycustomboard)?

nrf5340_cpuapp_common.dtsi includes:

#include "mycustomboard_common.dtsi"
#include "nrf5340_cpuapp_common-pinctrl.dtsi"

neither the nrf5340_cpuapp_common.dtsi or the nrf5340_cpuapp_common-pinctrl.dtsi were renamed as demonstrated in the DevAcademy Adding Custom Board Support session because the files were not named nrf5340dk_nrf5340_cpuapp_common.dtsi  like the nrf9151dk. Here is the instruction:

 

Press (F2) or right-click on each file and select rename. Rename the files from the old name that is prefixed with nrf9151dk_****_**** to the new name devacademyl3e2_****_****. Also, make sure to rename Kconfig.nrf9151dk to Kconfig.devacademyl3e2 .

Which results in naming these files:

To these files:

In my directory, because I'm using the nrf5340, I have two addtional files:

Do I need to do something differently because of this?

[Marte Myrvold]

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

[lcj]

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?

[Marte Myrvold]

Hi,

lcj said:

but do not need to be renamed, correct?

Correct.

lcj said:

Which file do I edit for the pins on the new board and which files need to be included as is?

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

[lcj]

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.

[Marte Myrvold]

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 [email protected]/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.

lcj said:

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

This is correct.

lcj said:

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

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