Device Tree Handling in Fire Gateware

BeagleV
, , ,
1

Hey everybody,

I am currently trying to figure out a how to best handle device tree overlays for custom FPGA IP cores on my BeagleV-Fire. I have been studying the gateware for a while but do not understand the full process that is used here. I am using Yocto Linux, so using the gateware directly is not an option (plus I want to understand how it works). Here is how far I have gotten:

  1. The device trees are written by hand to source files .dtso
  2. The device tree compiler and binary equivalents are created .dtbo
  3. These are packaged to some magic package that includes all overlays, the exact structure is still a mystery to me.
  4. These are then flashed to the SPI and somehow magically loaded at boot

From the perspective of U-Boot there are multiple ways to load the overlays:

  1. It can be a given as an additional argument to the U-Boot boot command
  2. the memory address is for the blob is given to U-Boot
  3. the overlays are in some intermediary step written to /boot/overlays where U-Boot searches
    I am not sure which method is used / supposed to be used to load from SPI.

It might also be that the HSS plays a role in this, I have found some references in the source code that uses libftd to apply an ftd overlay from, maybe from the SPI? But this part is even more fuzzy to me.

I would greatly appreciate any help or pointers on how this works internally. Thanks in advance!

2

The HSS currently plays no role in handling device-tree overlays, so ignore that part for now.

u-boot starts by loading the ITB file from /boot/firmware; this contains the base device-tree.
It then proceeds to load and apply the overlays from SPI directly.
No overlay files are fetched from the eMMC file-systems.

You can see exactly what’s going on by referencing boot.scr found here.

3

Thanks for the reply. As I understand this file the base device tree is loaded from the beaglev_fire.itb and edited on the fly with the device tree overlays from the spi by running run design_overlays, but I could not find the code for this function. Do you have a pointer as well? Is this the same for yocto layer for the beaglev-fire or is this specific to the Ubuntu build? I am still not really sure how this relates to the gateware, which as I understood builds a debian, that then would have to do the same, right?

4

The specific version of u-boot is found here
and is pulled from tag: linux4microchip+fpga-2025.10 (currently).

You should be able to find what you’re looking for
by searching for BOOTENV_DESIGN_OVERLAYS.

I couldn’t possibly comment on your Yocto setup…

Since change-gateware.sh reprograms the SPI with matching overlays,
this process is decoupled from the Yocto build, so I’d have to say no.

5

I have found the same line run design_overlays you posted from the Ubuntu image in the provided layers from microchip, so that clears how they can load the device tree overlay dynamically. What I am still missing is how they know where to load the blob from and documentation for the structure. I have found the magic numbers that are prepended to the blob in mpfs_syscontroller_process_dtbo of u-boot, which seems to set the no_of_overlays and dtbo_size variables. And there seems to be an fdtoverlay_addr_r=0x8a080000 but I can not yet see the connection. Could you help me once again?

6

Suffice to say that it seems to be an agreed upon convention,
seeing how every MPFS based kit Microchip makes has that SPI chip connected.

I have personally never felt the need to delve this deeply into the
implementation details. I believe they hardcoded the source (the SPI flash)
into their version of u-boot to take advantage of the before-mentioned decoupling.

If you absolutely, positively, need to know,
I suggest you pour over the u-boot source until you find the commits you’re looking for.
(link above)