What to do with dtsi files that come from Sysconfig?

General Discussion
1

I’ve been reading both generic websites and the various posts here (FAQ about device tree) and some threads, with the most useful one seeming to be Overlays: BeagleBone AI-64 [PWM] .

However I couldn’t find a straight-forward how-to of exactly what to do and the steps to do them when it comes to incorporating a dtsi file I get from TI Sysconfig. There’s lots of scattered information you can piece together, but I didn’t find a single location that walks you through step-by-step. So I thought maybe there would be benefit in starting a thread explicitly targeting that use-case. However if there is a doc/thread somewhere that does, please link to it.

I would fill in the details I’ve learned so far, but I’m not confident on anything I know (or rather think I know) right now. So here’s yet-another device-tree thread.

So just to give the thread some context, what I’m working on requires a fair number of pins on the P8 and P9 headers be muxed to work with ICSSG0_PRU0/1 on my BBAI64.

I’ve identified which header-pins map to which physical pins on the chip using the BBAI64’s hardware doc (I used the PDF).

Then I used TI’s SysConfig to identify which of these physical pins map to which PRUs.

This allowed me to pin-select the pins that worked best once I knew the endpoints of all available pins on the headers that also can be routed to PRUs. Sysconfig also allowed me to configure whether the pins are to be outputs or inputs. And for the inputs, whether the pin is to be internally pulled up, pulled down, or float (each of my pins have different needs so this was relevant).

Once I got a configuration that worked well for me, I exported all that from SysConfig into all the file-formats it allowed (at the time, I didn’t know which I’d want to use). With a bit more understanding, I realize what I want is to perform a device-tree overlay of this configuration ontop of the existing BBAI64 device-tree. And Sysconfig supplied me with the dtsi overlay (include) file to do just that.

So, at this point, what do I do with that file? It’s an include-file so I assume it is either already named something that will overwrite an existing file on the BBAI64? Or I’ll need to modify an existing file to include my file.

Once I’ve done whatever the correct thing to do is from the above paragraph, then I assume I need to run a make command to remake my device tree with my custom overlay configuration. Where do I do that and what target do I pass into make (if any)?

Any other steps necessary at this point?

And just so I understand the order at which things will be done, when will the dtb be processed? Is it one of the early tasks of Linux? Or does Uboot actually process the dtb before launching Linux? I’ve never been quite clear on that. Last time I looked at this on the AM335x (BBB’s processor), it seemed as if all Uboot did was load the dtb into RAM for Linux to process. But I can’t remember if its a coordinated location it gets put or if the address Uboot selected was passed to the Linux kernel as an arg. Or if I’m just completely wrong on that detail.

1 Like
2

For anybody else that finds this topic title interesting and also has the same questions, refer to this topic as it has some pretty good info about how to deal with device tree changes, specifically as it relates to PRUs, but I believe the instructions and principles are universal as they relate to device tree mods:
AI64 - PRU Basics (very)

3

I ran into your post a number of times while trying to figure things out.

Here is a bird’s eye view of what I did.

Note: I’m working with BeagleBone Black running kernel 4.14, not an AI64.

Warning

Making a mistake in an overlay can cause your Beaglebone to not boot. This only happened to me once so far. Keep a bootable uSD handy to recover.

Steps

  1. Create a .dtsi file using TI’s SysConfig tool.
    • I haven’t seen a difference between the cloud version and the desktop version, so I used desktop.
  2. Cleanup the .dtsi file. I clear-cut all the place holders for sleep wakeup placeholders.
  3. Make a .dts file that includes the .dtsi file.
    • This step was a bit involved to figure out the first time.
    • Lots of interations.
    • But the end product was simple; I put a copy below.
  4. Copy your .dts and .dtsi file to /opt/source/bb.org-overlays/src/arm.
    • You did a git pull first, right?
  5. cd opt/source/bb.org-overlays
  6. make ./src/arm/YOUR_FILE_NAME.dtbo
    • YOUR_FILE_NAME is your .dts file from step 3.
  7. mv ./src/arm/YOUR_FILE_NAME.dtbo /lib/firmware
  8. Edit /boot/uEnv.txt and add your firmware file into one of the uboot_overlay_addr# positions.
    • Disable what you’re supposed to, e.g. sound, video, WiFi
  9. Connect a serial cable to UART0 so you can see the uboot messages.
  10. Reboot
  11. Verify all the things.

Artifact for Step 2

This was just for a test. I probably shouldn’t have chosen P9_42 cuz it’s a dual-use pin, but whatever.

&am33xx_pinmux {
    gpio0_pins_default: gpio0_pins_default {
        pinctrl-single,pins = <
            AM33XX_IOPAD(0x964, PIN_INPUT_PULLUP | MUX_MODE5) /* (C18) eCAP0_in_PWM0_out.gpio0[7] */
        >;
    };
};

Artifact for Step 3

/*
 * Virtual cape test
 */


/dts-v1/;
/plugin/;

// header constants for most GPIO bindings, e.g. GPIO_ACTIVE_HIGH
#include <dt-bindings/gpio/gpio.h>
// header constants specific to AM33XX pinctrl bindings, e.g. PIN_OUTPUT
#include <dt-bindings/pinctrl/am33xx.h>
// header constants for IRQs
// #include <dt-bindings/interrupt-controller/irq.h>

/*
 * Helper to show loaded overlays under: /proc/device-tree/chosen/overlays/
 * or /sys/firmware/devicetree/base/chosen/overlays/
 */
&{/chosen} {
    overlays {
        Test-00A0.bb.org-overlays = __TIMESTAMP__;
    };
};

/*
 * Free up the pins used by the cape from the pinmux helpers.
 */
&ocp {
    P9_42_pinmux { status = "disabled"; };  /* P9_42 (C18): gpmc_a1.gpio0_07 */
};

// @am33xx_pinmux
// include file generated by SysConfig, i.e. one of ours.
// Positioned this below &ocp {} so the .dts decompile would better match the decompile of BB-UART4-00A0.dtbo.
#include "devicetree.dtsi"

// Do I want to redefine labels in the root node?
// I don't think this is needed for my overlay.
//&{/} {
//    model = "ABCDEFG";
//    compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx";
//    version = "00A0";
//};

// Yeah, I know I have another ocp section.
// GPIO pin entries here will show up in `show-pins` utility on the right hand side.
&ocp {

    /* An unused input pin. Should be MUX_MODE 7, although that may be the default. */
    P9_42A_pinmux {
        // The order of these properties matters only when checking against BB-UART4-00A0.dts
        compatible = "bone-pinmux-helper";
        pinctrl-names = "default";               // Could have more if more pinctrl-# are defined?
        pinctrl-0 = <&gpio0_pins_default /* P9_42A */>;
        status = "okay";
        line-name = "input-unused";              // not a clever name
    };

};

Verification (Step 11)

I ran into difficulties de-compiling the DT using dtc because my version is 1.4.7.

What I could do, however, is decompile the FDT. I suspect it’s pretty important to ensure the integrity of the FDT.

$ dtc -I dtb -O dts /sys/firmware/fdt > fdt.dts 2>/dev/null

How to ensure the integrity? Look around inside the fdt.dts artifact created by the above line.

Finally, ensure you got what you wanted using show-pins. For my example, I wanted to change P9_42A, and it changed, so cool.

$ show-pins --address --address | grep P9.42
P9.42                            964 fast rx  up  5 mmc 0 wp         ocp/P9_42A_pinmux (gpio0_pins_default)
P9.42                            9a0 fast rx down 7 gpio 3.18
2 Likes
4

One final word on the subject . . .

I ran into difficulties getting pru0 pins to change in the device tree. I finally found that the pinctrl-0 line was changing in the wrong node, i.e. pruss@0 instead of pruss@4a300000.

The comments in my .dts (below) describe the situation and how I fixed it. It may be some leftover issue that has been resolved since 4.14 days. It’s here in case anyone runs into the same issue when trying to use a .dtsi file from SysConfig directly.

&ocp {

.
.
.

    // This gives a warning of no register line:
    //    <stdout>: Warning (unit_address_vs_reg): /fragment@3/__overlay__/pruss@4a300000: node has a unit name, but no reg property
    // We're adding values to an existing node, so quit your whiningg.
    pruss@4a300000 {
        // P9_31, P9_30, P9_28, P9_29, P9_27
        pinctrl-names = "default";
        pinctrl-0 = <&pru_pru_0_pins_default>;
        status = "okay";
    };
};

// &pruss was suggest by this post
//      https://github.com/beagleboard/bb.org-overlays/issues/138
// and I see it in:
//      src/arm/am335x-boneblack-bbbmini.dts.
// The alias has a trailing \0, and I think that is why I cannot use the alias.
// It kept putting the values into the pruss@0 node.
//      pruss = "/ocp/pruss@4a300000\0";
//
//&pruss {
//    pinctrl-names = "default";
//    pinctrl-0 = <&pru_pru_0_pins_default>;
//    status = "okay";
//};