Compiling barebox without PBL and using dts from Linux dts upstream for Zynq SoC

Compiling barebox without PBL and using dts from Linux dts upstream for Zynq SoC

[Michał Kruszewski]

Hello,

I try to boot Linux using barebox on the MYiR Z-turn board (Xilinx Zynq SoC).
I have generated the default configuration using `make zynq_defconfig`.
After compiling and trying to boot nothing works.
I am not surprised at all.
I started digging, and here are a few things that are not clear to me.

Issue number one.
Barebox consists of 2 bootloaders, the Pre-BootLoader (PBL) and Second-Stage BootLoader (SSBL).
However, in my case I use the First Stage BootLoader (FSBL) compiled by Vitis.
The FSBL does all the required hardware initialization.
In such a case, the PBL is superfluous.
I would like to disable it.
However, I can't disable PBL_IMAGE in menuconfig, it is forced to Y.
It is selected by PBL_MULTI_IMAGES [=y] && HAVE_PBL_MULTI_IMAGES [=y].
Moreover, I can't disable HAVE_PBL_MULTI_IMAGES, it is forced to Y by selecting ARM.
Disabling ARM of course makes no sense.
Is it even possible to configure barebox as a SSBL-only for the Zynq SoC?
How to achieve this?

The second issues is that the MYiR Z-turn board is not supported directly by barebox.
However, there is a valid dts description in the dts directory (Linux upstream device tree directory).
How can I tell barebox to use a dts from the Linux dts upstream directory?
I looked for some config in menuconfig but without success.

The third issue is that I can't compile dts in the dts directory.
The make help message says:
>   src/<ARCH>/<DTS>.dtb   Build a single device tree binary
However, when I try I get:
  [user@host] make src/arm/xilinx/zynq-zturn-v5.dtb
    DTC     src/arm/xilinx/zynq-zturn-v5.dtb
  /bin/sh: 1: -Wp,-MD,src/arm/xilinx/.zynq-zturn-v5.dtb.d.pre.tmp: not found
  make: *** [Makefile:148: src/arm/xilinx/zynq-zturn-v5.dtb] Error 127
Of course the ARCH and CROSS_COMPILE are exported.

Regards,
Michał Kruszewski

Re: Compiling barebox without PBL and using dts from Linux dts upstream for Zynq SoC

[Ahmad Fatoum]

Hello Michał,

Cc += Alexander, who worked on other MYIR boards in the past.

On 3/26/26 08:29, Michał Kruszewski wrote:
> Hello,
> 
> I try to boot Linux using barebox on the MYiR Z-turn board (Xilinx Zynq SoC).
> I have generated the default configuration using `make zynq_defconfig`.
> After compiling and trying to boot nothing works.

Do you use upstream or a fork? There seems to be no Z-turn board support
upstream. barebox can generate multiple images in a build, which image did
you use?

> I am not surprised at all.
> I started digging, and here are a few things that are not clear to me.
> 
> Issue number one.
> Barebox consists of 2 bootloaders, the Pre-BootLoader (PBL) and Second-Stage BootLoader (SSBL).

The Pre-Bootloader is not necessarily the first stage, we prefer the terms
PBL and barebox proper.

> However, in my case I use the First Stage BootLoader (FSBL) compiled by Vitis.
> The FSBL does all the required hardware initialization.
> In such a case, the PBL is superfluous.

Every barebox image on ARM has a prebootloader prepended that:

  - decompresses barebox proper
  - loads it and configures the MMU
  - executes it while passing a device tree

The PBL may have extra functions as well like setting up DRAM, but at the very
least it's required to load barebox.

In general, PBLs have extra logic to detect if they are loaded second-stage
(e.g. from barebox itself for development) and in that case skip redoing
one-time initialization.

> I would like to disable it.

The PBL in your case is linked into the final barebox image and they are
meant to be used together.

> However, I can't disable PBL_IMAGE in menuconfig, it is forced to Y.
> It is selected by PBL_MULTI_IMAGES [=y] && HAVE_PBL_MULTI_IMAGES [=y].
> Moreover, I can't disable HAVE_PBL_MULTI_IMAGES, it is forced to Y by selecting ARM.
> Disabling ARM of course makes no sense.
> Is it even possible to configure barebox as a SSBL-only for the Zynq SoC?
> How to achieve this?

I am looking at start_avnet_zedboard() and at the start of
avnet_zedboard_ps7_init(), it skips the low level init if started
second stage, which is what you seem to be after?

> The second issues is that the MYiR Z-turn board is not supported directly by barebox.
> However, there is a valid dts description in the dts directory (Linux upstream device tree directory).
> How can I tell barebox to use a dts from the Linux dts upstream directory?
> I looked for some config in menuconfig but without success.

For quick testing, you can replace in arch/arm/dts/zynq-zed.dts

#include <arm/xilinx/zynq-zed.dts>

with your own board. Check that the stdout-path is correct.

Once you got that working, proper board support entails adding a new
DT in arch/arm/dts/, creating a new directory in arch/arm/boards/
and adding the new image to images/Makefile.zynq as well as the
Kconfig/Kbuild additions. For details, see:

https://www.barebox.org/doc/latest/devel/porting.html#porting-to-a-new-board

> The third issue is that I can't compile dts in the dts directory.
> The make help message says:
>>   src/<ARCH>/<DTS>.dtb   Build a single device tree binary
> However, when I try I get:
>   [user@host] make src/arm/xilinx/zynq-zturn-v5.dtb
>     DTC     src/arm/xilinx/zynq-zturn-v5.dtb
>   /bin/sh: 1: -Wp,-MD,src/arm/xilinx/.zynq-zturn-v5.dtb.d.pre.tmp: not found
>   make: *** [Makefile:148: src/arm/xilinx/zynq-zturn-v5.dtb] Error 127
> Of course the ARCH and CROSS_COMPILE are exported.

dts/ are just the device trees as they are in Linux. You can only build
device tree in arch/${ARCH/dts/.

You can read more about barebox device tree handling at:

https://www.barebox.org/doc/latest/devicetree/index.html

Hope this helps.

Cheers,
Ahmad

> 
> Regards,
> Michał Kruszewski
> 
> 
> 
> 


-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: Compiling barebox without PBL and using dts from Linux dts upstream for Zynq SoC

[Michał Kruszewski]

> Do you use upstream or a fork? There seems to be no Z-turn board support upstream.

Upstream, release 2026.03.1.


> barebox can generate multiple images in a build, which image did you use?

I think I don't understand the question.


> Every barebox image on ARM has a prebootloader prepended that:
>
>   - decompresses barebox proper
>   - loads it and configures the MMU
>   - executes it while passing a device tree

How Does PBL pass a device tree to the barebox?


> I am looking at start_avnet_zedboard() and at the start of
> avnet_zedboard_ps7_init(), it skips the low level init if started
> second stage, which is what you seem to be after?

This is true.
However, I don't use the avnet zedboard board.
I don't want any code realted to some other board to be executed.
What is the point of this?
The FSBL has already configured everything at this stage.
If PBL is required, I just want minimal PBL that only does whatever is required to start barebox.
Is it possible to configure PBL in such a way?


> For quick testing, you can replace in arch/arm/dts/zynq-zed.dts
>
> #include <arm/xilinx/zynq-zed.dts>
>
> with your own board. Check that the stdout-path is correct.

If I do so, the dtb compilation fails with:
  FATAL ERROR: Couldn't open "zynq-zturn-common.dtsi": No such file or directory
'zynq-zturn-common.dtsi' is included in 'dts/src/arm/xilinx/zynq-zturn-v5.dts'.
Is is placed in the same directory as 'zynq-zturn-v5.dts' ('dts/src/arm/xilinx/').
If I replace
  /include/ "zynq-zturn-common.dtsi"
with
  /include/ "arm/xilinx/zynq-zturn-common.dtsi"
the dtc still can't find the file:
  FATAL ERROR: Couldn't open "arm/xilinx/zynq-zturn-common.dtsi": No such file or directory


> dts/ are just the device trees as they are in Linux. You can only build
> device tree in arch/${ARCH/dts/.
>
> You can read more about barebox device tree handling at:
>
> https://www.barebox.org/doc/latest/devicetree/index.html

So the help message of the Makefile in the dts directory is misleading.
Is is simply copied from the Linux?


Regards,
Michał Kruszewski

Re: Compiling barebox without PBL and using dts from Linux dts upstream for Zynq SoC

[Ahmad Fatoum]

Hello,

On 3/26/26 10:06 AM, Michał Kruszewski wrote:
>> Do you use upstream or a fork? There seems to be no Z-turn board support upstream.
> 
> Upstream, release 2026.03.1.
> 
> 
>> barebox can generate multiple images in a build, which image did you use?
> 
> I think I don't understand the question.

A zynq_defconfig build will report at the end the generated images:

images built:
barebox-avnet-zedboard.img
barebox-dt-2nd.img

Is images/barebox-avnet-zedboard.img the image you used?

>> Every barebox image on ARM has a prebootloader prepended that:
>>
>>   - decompresses barebox proper
>>   - loads it and configures the MMU
>>   - executes it while passing a device tree
> 
> How Does PBL pass a device tree to the barebox?

This is the line that does it for the Zynq Zedboard:

barebox_arm_entry(0, SZ_512M, __dtb_z_zynq_zed_start);

This function takes care to extract barebox and invoke it
with these arguments.

>> I am looking at start_avnet_zedboard() and at the start of
>> avnet_zedboard_ps7_init(), it skips the low level init if started
>> second stage, which is what you seem to be after?
> 
> This is true.
> However, I don't use the avnet zedboard board.
> I don't want any code realted to some other board to be executed.

barebox generates bootloader images for boards, so you must have
either used an image for an existing board or some intermediate build
artifact, hence my question above.

> What is the point of this?

I am asking to clarify what you did. Your original email didn't
elaborate what you did, only what you thought was the problem.

> The FSBL has already configured everything at this stage.
> If PBL is required, I just want minimal PBL that only does whatever is required to start barebox.
> Is it possible to configure PBL in such a way?

Yes, of course. Just add a new ENTRY_FUNCTION(_WITHSTACK) that does
only the parts you are interested in and reference it in
images/Makefile.zynq.

The skipping logic should still work though.

>> For quick testing, you can replace in arch/arm/dts/zynq-zed.dts
>>
>> #include <arm/xilinx/zynq-zed.dts>
>>
>> with your own board. Check that the stdout-path is correct.
> 
> If I do so, the dtb compilation fails with:
>   FATAL ERROR: Couldn't open "zynq-zturn-common.dtsi": No such file or directory
> 'zynq-zturn-common.dtsi' is included in 'dts/src/arm/xilinx/zynq-zturn-v5.dts'.
> Is is placed in the same directory as 'zynq-zturn-v5.dts' ('dts/src/arm/xilinx/').
> If I replace
>   /include/ "zynq-zturn-common.dtsi"
> with
>   /include/ "arm/xilinx/zynq-zturn-common.dtsi"
> the dtc still can't find the file:
>   FATAL ERROR: Couldn't open "arm/xilinx/zynq-zturn-common.dtsi": No such file or directory

Argh, I thought /include/ was something that only old PowerPC device
trees still had..

You can replace do

-#include <arm/xilinx/zynq-zed.dts>
+/include/ "../../../dts/src/arm/xilinx/zynq-zturn-v5.dts"

instead for now. Needs some more thought put into it how to do this
in a cleaner manner.

>> dts/ are just the device trees as they are in Linux. You can only build
>> device tree in arch/${ARCH/dts/.
>>
>> You can read more about barebox device tree handling at:
>>
>> https://www.barebox.org/doc/latest/devicetree/index.html
> 
> So the help message of the Makefile in the dts directory is misleading.

If you really want, you can build it if you use the correct Makefile:

make -C dts src/arm/xilinx/zynq-zturn-v5.dtb

But it doesn't make barebox magically use that DT, so not sure why
you want to.

> Is is simply copied from the Linux?

Here's the upstream:
https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/

But yes, these DTs are 1:1 from Linux. If you want to make use of them,
a device tree in arch/${ARCH}/dts/ needs to include them.

Cheers,
Ahmad



> 
> 
> Regards,
> Michał Kruszewski
> 

-- 
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

Re: Compiling barebox without PBL and using dts from Linux dts upstream for Zynq SoC

[Michał Kruszewski]

> A zynq_defconfig build will report at the end the generated images:
>
> images built:
> barebox-avnet-zedboard.img
> barebox-dt-2nd.img
> Is images/barebox-avnet-zedboard.img the image you used?

All I did was:
  make zynq_defconfig
  make

I used neither images/barebox-avnet-zedboard.img nor images/barebox-dt-2nd.img.
I used barebox file.
Why?
Because I use Vivado bootbin progam to generate the boot.bin file.
bootbin requires that the second stage bootloader is provided in the ELF format.
When I use u-boot.elf everything works correctly.


> This is the line that does it for the Zynq Zedboard:

> barebox_arm_entry(0, SZ_512M, __dtb_z_zynq_zed_start);

> This function takes care to extract barebox and invoke it
> with these arguments.

So the compiled device tree is placed into the final image, isn't it?


> barebox generates bootloader images for boards, so you must have
> either used an image for an existing board or some intermediate build
> artifact, hence my question above.

What is an "intermediate build artifact"?
How to use it instead a board image?


> I am asking to clarify what you did. Your original email didn't
> elaborate what you did, only what you thought was the problem.

All I did was:
  make zynq_defconfig
  make
I used the generated barebox elf file for Vivado bootbin.
I replaced u-boot.elf with barebox.
I did not expect the Linux to start.
However, I did expect the barebox to start.


> Yes, of course. Just add a new ENTRY_FUNCTION(_WITHSTACK) that does
> only the parts you are interested in and reference it in
> images/Makefile.zynq.

Is there any tutorial/documentation on that?
I thought that maybe there is a simple CONFIG for that.


Regards,
Michał Kruszewski

Re: Compiling barebox without PBL and using dts from Linux dts upstream for Zynq SoC

[Ahmad Fatoum]

Hello Michał,

On 3/26/26 11:35 AM, Michał Kruszewski wrote:
>> A zynq_defconfig build will report at the end the generated images:
>>
>> images built:
>> barebox-avnet-zedboard.img
>> barebox-dt-2nd.img
>> Is images/barebox-avnet-zedboard.img the image you used?
> 
> All I did was:
>   make zynq_defconfig
>   make
> 
> I used neither images/barebox-avnet-zedboard.img nor images/barebox-dt-2nd.img.
> I used barebox file.
> Why?
> Because I use Vivado bootbin progam to generate the boot.bin file.
> bootbin requires that the second stage bootloader is provided in the ELF format.

The images meant for end user use are printed at the end of the
make invocation.

> When I use u-boot.elf everything works correctly.

The "barebox" file is not even stripped. It's not meant for direct use,
it's just an intermediary step before being linked into the PBL or for
use with gdb.

That said, we can have barebox generate a stripped ELF suitable for
use by Vivado bootbin if needed, once we know what's needed.

>> This is the line that does it for the Zynq Zedboard:
> 
>> barebox_arm_entry(0, SZ_512M, __dtb_z_zynq_zed_start);
> 
>> This function takes care to extract barebox and invoke it
>> with these arguments.
> 
> So the compiled device tree is placed into the final image, isn't it?

Yes, the compiled device tree is shipped as part of the prebootloader.

>> barebox generates bootloader images for boards, so you must have
>> either used an image for an existing board or some intermediate build
>> artifact, hence my question above.
> 
> What is an "intermediate build artifact"?

Roughly, the build system does something like this:

common/version.c -> common/version.o -> common/built-in.a
	-> barebox -> vmbarebox -> build/images/start_avnet_zedboard.pbl
	-> build/images/start_avnet_zedboard.pblb
	-> barebox-avnet-zedboard.img


Everything except the first source file and the final image are
intermediate artifacts that are not meant to be used directly.

> How to use it instead a board image?

Try using build/images/start_avnet_zedboard.pbl
and if that works, we can have barebox generate a proper
stripped ELF with a normal name (e.g. barebox-avnet-zedboard.elf).

>> I am asking to clarify what you did. Your original email didn't
>> elaborate what you did, only what you thought was the problem.
> 
> All I did was:
>   make zynq_defconfig
>   make
> I used the generated barebox elf file for Vivado bootbin.
> I replaced u-boot.elf with barebox.
> I did not expect the Linux to start.
> However, I did expect the barebox to start.

For ARM, the images in images/ are what actually should be used.

>> Yes, of course. Just add a new ENTRY_FUNCTION(_WITHSTACK) that does
>> only the parts you are interested in and reference it in
>> images/Makefile.zynq.
> 
> Is there any tutorial/documentation on that?

https://www.barebox.org/doc/latest/devel/porting.html#porting-to-a-new-board

> I thought that maybe there is a simple CONFIG for that.

I got this feedback three times in the last few months and I agree we
should do something about this.

The usual model so far could be summarized as:

- barebox has one or more DTs embedded and you have some early low level
init that's board-specific anyway (e.g. RAM settings), so you wouldn't
change one of the DTs to something completely different anyway

- You have a bootloader that can boot Linux directly and want it to
start barebox, so you use the barebox-dt-2nd.img which accept an
external device tree

- If you have a UEFI already there, you can boot barebox-dt-2nd.img also
via EFI without a device tree if you enable the correct options in Kconfig


Your use case is in the middle, the device tree might be the only
thing you need to change, but it still needs to be linked into barebox
and there's no easy way for doing it from outside (yet).

Once you have something that works, I am sure we can find some way to
make it easier to extend to arbitrary device trees.

Cheers,
Ahmad

> 
> 
> Regards,
> Michał Kruszewski
> 
> 

-- 
Pengutronix e.K.                  |                             |
Steuerwalder Str. 21              | http://www.pengutronix.de/  |
31137 Hildesheim, Germany         | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

Re: Compiling barebox without PBL and using dts from Linux dts upstream for Zynq SoC

[Michał Kruszewski]

Of course, due to the hurry, I made a mistake in my previous message.
The program for the boot.bin generation is called bootgen not bootbin.

You can find AMD bootgen user guide here:
  https://docs.amd.com/r/en-US/ug1283-bootgen-user-guide/Introduction.

The ELF file provided to the bootgen can have multiple loadable sections, each of which forms a partition in the boot image.
The AMD/Xilinx FSBL will load and hand-off execution to the next executable partition found in the boot.bin file.
The u-boot.elf file has one LOAD section:
  [user@host] readelf -l u-boot.elf
  Elf file type is EXEC (Executable file)
  Entry point 0x4000000
  There is 1 program header, starting at offset 52
  Program Headers:
    Type           Offset   VirtAddr   PhysAddr   FileSiz MemSiz  Flg Align
    LOAD           0x010000 0x04000000 0x04000000 0x108ff0 0x108ff0 RW  0x10000
   Section to Segment mapping:
    Segment Sections...
     00     .data
The readelf for barebox shows 3 LOAD sections and 1 DYNAMIC section.
The second difference is that Elf file type for u-boot is EXEC (Executable file), for barebox DYN (Position-Independent Executable file).

The bootgen user guide has the table 49 with the following note for the ELF file format:
"Symbols and headers removed."
However, it is not clear whether bootgen automatically removes symbosls and headers, or whether it expects the elf file without symbols and headers.


Now, I would like to describe a few ideas and potential problems.
I am by far not bootloaders expert.
However, I had to boot and debug booting on a few custom and off-the-shelf boards with AMD/Xilinx SoCs and MPSoCs.
All the things I write below are related to booting ADM/Xilinx chips only.


There are 2 alternative paths you may chose when trying to boot AMD/Xilinx SoCs.

Path 1: The no-FSBL path
This is the path currently supported by barebox.
You do not want to utilize the AMD/Xilinx automatically generated FSBL.
In such a case, you have to define a board, and provide C code for the low-level board initialization.
The barebox PBL does the FSBL job in this case.
I think this path is fine for hobby projects and off-the-shelf boards when you want to quickly get things running.
However, I am not a fan of this path in professional projects because of the following reasons:
  a) The FSBL code is automatically generated, it may include some workarounds or fixes for hardware bugs.
     The copied low-level initialization C code may potentially miss them.
  b) Forget about getting official support from AMD/Xilinx if you mention you don't use the official FSBL for boot.

Path 2: The FSBL path
For me, this is the way to go in professional projects.
Barebox currently does not support this path.
In this case, you do not want to be forced to define a board.
This is simply pointless, the FSBL is responsible for initializing the low-level stuff.
All you need to boot Linux when FSBL stops execution is some SSBL and device tree.


Now, what a support for path 2 in the barebox could look like.
We could use the concept of the virtual board.
The virtual board is a board that:
  - is assumed to already be low-level initialized when barebox starts running,
  - can accept arbitrary device tree,
  - should not be bound to any specific device tree by default.
The boilerplate related to the board definition should not exist for the virtual board.
What the user experience would look like:
  1. make zynq_virt_defconfig,
  2. open menuconfig,
  3. find and set config containing path for the device tree file (can be out of tree),
  4. make,
  5. copy the required elf and/or bin files to your project.

The u-boot has a similar concept of virt defconfigs, for example:
xilinx_versal_virt_defconfig
xilinx_zynqmp_virt_defconfig
xilinx_zynq_virt_defconfig


What potential problems do I see?
The bootgen handles elf files with multiple loadable sections by putting each section into a separate partition.
The FSBL simply loads and hands-off to the next executable partition from the boot.bin.
I do not know how barebox works and prepares images.
However I can see 3 potential scenarios.

Scenario 1: PBL and SSBL are logical entities put into the same LOAD section
This scenario is easy.
FSBL will load both into memory.
The hand-off from PBL to SSBL does not require loading SSBL into memory since it was already done by FSBL.
The hand-off from PBL to SSBL is a simple jump.

Scenario 2: PBL and SSBL are puto into the same ELF file but separate LOAD sections
FSBL will load only PBL.
PBL has to parse boot.bin file, load SSBL into memory and hand-off to it.

Scenario 3: Only PBL is put in the ELF file, ELF file has one LOAD section
PBL must load SSBL from the SD card parition (not boot.bin file partition).
The SSBL can be an image in binary format since it is not put into boot.bin.


Unfortunately, I do not have enough skills to apply required changes to barebox to test these ideas on my own.
However, I would be more than happy to test your changes.
Let me know what you think.

Regards,
Michał Kruszewski