[PATCH 0/2] colibri_vf: fix NAND boot and add the board documentation

[PATCH 0/2] colibri_vf: fix NAND boot and add the board documentation

[Mehmet Fide]

From: Mehmet Fide <mehmet.fide@screeningeagle.com>

Following the CONFIG_TEXT_BASE report [1] and Francesco's suggestion,
two patches: the first restores the text base the Vybrid BootROM
actually accepts, measured on hardware both through the BootROM NAND
path and the WinCE-era loader; the second adds the missing
doc/board/toradex page for the Colibri VF50/VF61.

[1] https://lore.kernel.org/u-boot/20260806124816.262259-1-mehmet.fide@gmail.com/

Mehmet Fide (2):
  colibri_vf: restore the pre-2017 text base, the BootROM refuses the
    low one
  doc: board: toradex: add the Colibri VF50/VF61 page

 configs/colibri_vf_defconfig     |  4 +-
 doc/board/toradex/colibri_vf.rst | 70 ++++++++++++++++++++++++++++++++
 doc/board/toradex/index.rst      |  1 +
 3 files changed, 73 insertions(+), 2 deletions(-)
 create mode 100644 doc/board/toradex/colibri_vf.rst

-- 
2.54.0

[PATCH 1/2] colibri_vf: restore the pre-2017 text base, the BootROM refuses the low one

[Mehmet Fide]

From: Mehmet Fide <mehmet.fide@screeningeagle.com>

Since commit c0f432c37780 ("configs: vf610: increase maximum size and
enforce correct limit") U-Boot for the Vybrid boards links at 0x3f401000, right
at the start of the OCRAM gfxRAM area. On a Colibri VF50 the BootROM
does not start such an image from NAND at all: the module drops into
the serial downloader, verified by the 0x23454523 UART association
pattern echoing back. The WinCE-era Toradex loader dies the same way
when handed such an image with its flashloader command. Relinking the
same tree at 0x3f408000, the value used before that commit and by the
vendor fork since, boots through both paths.

The low 28 KiB of the gfxRAM area are evidently not usable as a load
address for the ROM, so give them back and correct the size limit to
match (0x3f480000 - 0x3f408000).

Tested on a Colibri VF50 128MB IT V1.2B on an Iris carrier: cold boot
from NAND, both text bases, one build apart.

Fixes: c0f432c37780 ("configs: vf610: increase maximum size and enforce correct limit")
Signed-off-by: Mehmet Fide <mehmet.fide@screeningeagle.com>
---
 configs/colibri_vf_defconfig | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/configs/colibri_vf_defconfig b/configs/colibri_vf_defconfig
index 5145e947e88..beb64189d5c 100644
--- a/configs/colibri_vf_defconfig
+++ b/configs/colibri_vf_defconfig
@@ -2,7 +2,7 @@ CONFIG_ARM=y
 CONFIG_SKIP_LOWLEVEL_INIT=y
 CONFIG_SYS_THUMB_BUILD=y
 CONFIG_ARCH_VF610=y
-CONFIG_TEXT_BASE=0x3f401000
+CONFIG_TEXT_BASE=0x3f408000
 CONFIG_SYS_MALLOC_LEN=0x0220000
 CONFIG_NR_DRAM_BANKS=1
 CONFIG_ENV_SIZE=0x20000
@@ -16,7 +16,7 @@ CONFIG_SYS_MEMTEST_START=0x80010000
 CONFIG_SYS_MEMTEST_END=0x87c00000
 CONFIG_ENV_VARS_UBOOT_CONFIG=y
 CONFIG_HAS_BOARD_SIZE_LIMIT=y
-CONFIG_BOARD_SIZE_LIMIT=520192
+CONFIG_BOARD_SIZE_LIMIT=491520
 # CONFIG_EFI_LOADER is not set
 CONFIG_BOOTDELAY=1
 CONFIG_FDT_FIXUP_PARTITIONS=y
-- 
2.54.0

[PATCH 2/2] doc: board: toradex: add the Colibri VF50/VF61 page

[Mehmet Fide]

From: Mehmet Fide <mehmet.fide@screeningeagle.com>

The other Toradex modules are documented here, the Vybrid ones were
not. Describe the build, the two ways of getting the image into NAND,
and the flashloader command of the WinCE-era bootloader that modules
from that era still carry.

Signed-off-by: Mehmet Fide <mehmet.fide@screeningeagle.com>
---
 doc/board/toradex/colibri_vf.rst | 70 ++++++++++++++++++++++++++++++++
 doc/board/toradex/index.rst      |  1 +
 2 files changed, 71 insertions(+)
 create mode 100644 doc/board/toradex/colibri_vf.rst

diff --git a/doc/board/toradex/colibri_vf.rst b/doc/board/toradex/colibri_vf.rst
new file mode 100644
index 00000000000..d2809bda2e8
--- /dev/null
+++ b/doc/board/toradex/colibri_vf.rst
@@ -0,0 +1,70 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+.. sectionauthor:: Mehmet Fide <mehmet.fide@screeningeagle.com>
+
+Colibri VF50/VF61 Modules
+=========================
+
+- SoM: https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-vybrid-vf5xx-vf6xx
+- Carrier boards: https://www.toradex.com/products/carrier-board/colibri-evaluation-board
+  and https://www.toradex.com/products/carrier-board/iris-carrier-board
+
+Quick Start
+-----------
+
+- Build U-Boot
+- Flash to NAND from a running U-Boot
+- Flash to NAND over recovery mode
+- Modules still carrying the WinCE bootloader
+
+Build U-Boot
+------------
+
+.. code-block:: bash
+
+    $ export CROSS_COMPILE=arm-linux-gnueabi-
+    $ make colibri_vf_defconfig
+    $ make
+
+This produces ``u-boot.imx``, the image with the IVT for the Vybrid
+BootROM, ready to be written to the ``u-boot`` NAND partition.
+
+Flash to NAND from a running U-Boot
+-----------------------------------
+
+Load the image over TFTP or from a FAT formatted SD card and use the
+``update_uboot`` script from the default environment:
+
+.. code-block:: none
+
+    Colibri VFxx # fatload mmc 0:1 ${loadaddr} u-boot.imx
+    Colibri VFxx # run update_uboot
+    Colibri VFxx # reset
+
+Flash to NAND over recovery mode
+--------------------------------
+
+With nothing bootable in NAND, the Vybrid BootROM falls back to the
+serial downloader on the USB client port. The `imx_usb_loader
+<https://github.com/boundarydevices/imx_usb_loader>`_ tool can push
+``u-boot.imx`` straight into OCRAM and run it:
+
+.. code-block:: bash
+
+    $ imx_usb u-boot.imx
+
+From the running U-Boot, flash NAND as in the previous section.
+
+Modules still carrying the WinCE bootloader
+-------------------------------------------
+
+Modules that were shipped with the WinCE-era Toradex bootloader (eBoot)
+offer a ``flashloader`` command that writes a U-Boot image to NAND:
+
+.. code-block:: none
+
+    > flashloader u-boot.imx
+    > reboot
+
+The image must be linked at ``CONFIG_TEXT_BASE=0x3f408000``; the BootROM
+does not start an image linked at the bottom of the gfxRAM area, whether
+loaded through eBoot or from NAND.
diff --git a/doc/board/toradex/index.rst b/doc/board/toradex/index.rst
index 2a45bde6991..5bf2d052462 100644
--- a/doc/board/toradex/index.rst
+++ b/doc/board/toradex/index.rst
@@ -10,6 +10,7 @@ Toradex
    aquila-am69
    colibri_imx7
    colibri-imx8x
+   colibri_vf
    smarc-imx8mp
    smarc-imx95
    verdin-am62
-- 
2.54.0

Re: [PATCH 1/2] colibri_vf: restore the pre-2017 text base, the BootROM refuses the low one

[Francesco Dolcini]

On Thu, Aug 13, 2026 at 05:07:25PM +0200, Mehmet Fide wrote:
> From: Mehmet Fide <mehmet.fide@screeningeagle.com>
> 
> Since commit c0f432c37780 ("configs: vf610: increase maximum size and
> enforce correct limit") U-Boot for the Vybrid boards links at 0x3f401000, right
> at the start of the OCRAM gfxRAM area. On a Colibri VF50 the BootROM
> does not start such an image from NAND at all: the module drops into
> the serial downloader, verified by the 0x23454523 UART association
> pattern echoing back. The WinCE-era Toradex loader dies the same way
> when handed such an image with its flashloader command. Relinking the
> same tree at 0x3f408000, the value used before that commit and by the
> vendor fork since, boots through both paths.
> 
> The low 28 KiB of the gfxRAM area are evidently not usable as a load
> address for the ROM, so give them back and correct the size limit to
> match (0x3f480000 - 0x3f408000).
> 
> Tested on a Colibri VF50 128MB IT V1.2B on an Iris carrier: cold boot
> from NAND, both text bases, one build apart.
> 
> Fixes: c0f432c37780 ("configs: vf610: increase maximum size and enforce correct limit")
> Signed-off-by: Mehmet Fide <mehmet.fide@screeningeagle.com>

Stefan: do you remember any of this? any comment?

Unless Stefan says anything against this change, I am ok with it. But I
really have no idea about it, I trust your analysis Mehmet.

Acked-by: Francesco Dolcini <francesco.dolcini@toradex.com>

Re: [PATCH 2/2] doc: board: toradex: add the Colibri VF50/VF61 page

[Francesco Dolcini]

Hello Mehmet,
thanks for the patch.

On Thu, Aug 13, 2026 at 05:07:26PM +0200, Mehmet Fide wrote:
> From: Mehmet Fide <mehmet.fide@screeningeagle.com>
> 
> The other Toradex modules are documented here, the Vybrid ones were
> not. Describe the build, the two ways of getting the image into NAND,
> and the flashloader command of the WinCE-era bootloader that modules
> from that era still carry.
> 
> Signed-off-by: Mehmet Fide <mehmet.fide@screeningeagle.com>
> ---
>  doc/board/toradex/colibri_vf.rst | 70 ++++++++++++++++++++++++++++++++
>  doc/board/toradex/index.rst      |  1 +
>  2 files changed, 71 insertions(+)
>  create mode 100644 doc/board/toradex/colibri_vf.rst
> 
> diff --git a/doc/board/toradex/colibri_vf.rst b/doc/board/toradex/colibri_vf.rst
> new file mode 100644
> index 00000000000..d2809bda2e8
> --- /dev/null
> +++ b/doc/board/toradex/colibri_vf.rst
> @@ -0,0 +1,70 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +.. sectionauthor:: Mehmet Fide <mehmet.fide@screeningeagle.com>
> +
> +Colibri VF50/VF61 Modules
> +=========================
> +
> +- SoM: https://www.toradex.com/computer-on-modules/colibri-arm-family/nxp-vybrid-vf5xx-vf6xx
> +- Carrier boards: https://www.toradex.com/products/carrier-board/colibri-evaluation-board
> +  and https://www.toradex.com/products/carrier-board/iris-carrier-board
> +
> +Quick Start
> +-----------
> +
> +- Build U-Boot
> +- Flash to NAND from a running U-Boot
> +- Flash to NAND over recovery mode
> +- Modules still carrying the WinCE bootloader
> +
> +Build U-Boot
> +------------
> +
> +.. code-block:: bash

this should be 'console', not bash. Likewise in other places.

> +
> +    $ export CROSS_COMPILE=arm-linux-gnueabi-
> +    $ make colibri_vf_defconfig
> +    $ make
> +
> +This produces ``u-boot.imx``, the image with the IVT for the Vybrid
> +BootROM, ready to be written to the ``u-boot`` NAND partition.
> +
> +Flash to NAND from a running U-Boot
> +-----------------------------------
> +
> +Load the image over TFTP or from a FAT formatted SD card and use the
> +``update_uboot`` script from the default environment:
> +
> +.. code-block:: none
> +
> +    Colibri VFxx # fatload mmc 0:1 ${loadaddr} u-boot.imx
> +    Colibri VFxx # run update_uboot
> +    Colibri VFxx # reset
> +
> +Flash to NAND over recovery mode
> +--------------------------------
> +
> +With nothing bootable in NAND, the Vybrid BootROM falls back to the
> +serial downloader on the USB client port. The `imx_usb_loader
> +<https://github.com/boundarydevices/imx_usb_loader>`_ tool can push
> +``u-boot.imx`` straight into OCRAM and run it:
> +
> +.. code-block:: bash
> +
> +    $ imx_usb u-boot.imx
> +
> +From the running U-Boot, flash NAND as in the previous section.
> +
> +Modules still carrying the WinCE bootloader
> +-------------------------------------------
> +
> +Modules that were shipped with the WinCE-era Toradex bootloader (eBoot)
> +offer a ``flashloader`` command that writes a U-Boot image to NAND:
> +
> +.. code-block:: none
> +
> +    > flashloader u-boot.imx
> +    > reboot
> +
> +The image must be linked at ``CONFIG_TEXT_BASE=0x3f408000``; the BootROM
Not sure that this comment must be here, once you fix the defconfig.
It does not seem specific on the colibri, this is about the SoC.


in any case,

Acked-by: Francesco Dolcini <francesco.dolcini@toradex.com>

Francesco

Re: [PATCH 1/2] colibri_vf: restore the pre-2017 text base, the BootROM refuses the low one

[Mehmet Fide]

From: Mehmet Fide <mehmet.fide@screeningeagle.com>

Hello Francesco,

> Stefan: do you remember any of this? any comment?
>
> Unless Stefan says anything against this change, I am ok with it. But I
> really have no idea about it, I trust your analysis Mehmet.

Some more background that may make this less scary.

The value this restores is not a new invention: 0x3f408000 is what
mainline used until 2017 and what the Toradex 2015.04 fork has been
shipping since, including on our seven Colibri VF products in the
field, so it is the most field-proven number this board has.

As for why the low base fails, the reference manual gives a hint. For
NAND boot the ROM first stages the 4 KiB "initial load region" of the
image in internal RAM, parses the IVT at offset 0x400 inside it, and
only then copies the whole image to the address the IVT names (VFxxx
RM, table 7-51). Where that staging buffer lives is not documented,
but the imx_usb_loader Vybrid configuration points its scratch/DCD
address at 0x3f400000, the very bottom of the gfxRAM. An image linked
at 0x3f401000 asks the ROM to copy the image right over that region,
which would corrupt the staged source header mid-copy, and it matches
what I observe: the ROM never jumps, it falls straight back to the
serial downloader. With 0x3f408000 the copy target starts at
0x3f4074e8 and the bottom of the SRAM is never touched.

That said, this is my best reading of it; what the commit message
relies on is the A/B measurement only. If Stefan remembers the actual
constraint I am happy to spell it out in the commit message.

Thanks for the ack!

Mehmet