mfgtools
mfgtools copied to clipboard
NXPmicro
Steep learning curve; improving docs
I think UUU is a powerful tool, but learning how to use it is very challenging. Many things could be improved to ease the learning curve such as better docs (wiki/PDF) and app help info.
In order to understand the tool I have compiled a list of questions and issues. I also took the liberty to re-write both the command line help info and PDF. I tried to improve the wording and organization. Where I could, I tried to clarify and correct -- knowing that I might be wrong in my assumptions.
I realize this is a lot of information. I hope that some of it can be leveraged to improve the tool.
General
- A systemic issue is that although the documentation is in English, the grammar is poor. Please get editorial help from a skilled English speaker.
- Does uuu.exe (and usb dll) have to be in same dir as file(s) to load? Or can I use fully qualified paths? In some examples I read they are co-located, but nowhere does it say they have to be even though it sortof seems like it is required.
- In the CLI, what is the difference between emmc and emmc_all CLI options? CLI help says emmc burns ‘boot loader’ and emmc_all burns ‘whole image’. That begs the question what is boot loader vs. whole image? A guess: the input to emmc is expected to be a boot-only image whereas the input to emmc_all is expected to be a wic image that contains both the boot and kernel. Is that right?
- Does UUU support IMX8M Nano? My nano shows as PID 0x013E, but that is not listed in uuu.pdf. Did try to write an image to my nano EVK but always fails.
- Found no description of how to exit interactive mode. First, please document this. Second, I discovered via trial-and-error that it’s ‘quit’. Why not ‘done’ like a script?
- The script name auto.uuu seems special. In what ways is it special? I think it’s used if you specify a dir or zip file as bootloader arg in which case uuu uses auto.uuu in the dir or zip file with that name. Is that right? And is that the only condition in which the file name is special?
- CLI help includes “bootloader download bootloader to board by usb” and PDF says “uuu bootloader” is a typical use described as “download uboot”. What storage does this command write to? How is it possible that a relatively simple command like this can work when other commands have so many options to specify? Are there a bunch of defaults associated with this command syntax?
Documentation -- uuu.pdf
- In general, the PDF is hard to understand due to poor English, wording and organization.
- WRT use of “download”: I do not consider what uuu does to be downloading. IMO a device is either a server in which case uuu uploads, or a device is peer so it’s writing/loading/copying/burning. If the device was obtaining data from the host PC, then that might be called download.
- The Typical usage section is probably intended to simplify learning how to use, but it’s more confusing than helpful. In what way are the commands shown typical? They don’t seem typical to me. Maybe this section is what other docs might call examples.
- The Typical script section is confusing since is there a script that’s typical?
- WRT Table 1: what is this showing?? What is a fastboot environment?
- WRT What Firmware Need section: No idea what this is about.
- WRT section 1.7 L4.9.123_2.3.0_8MM GA: how this section important?
CLI help info
The help output from the app is better than some apps I’ve used, but it has some issues.
- It seems that the -b switch is very important, but it’s not listed as a switch. I assume it selects a built-in script to run. The built-in scripts are listed but there should be a line like: "-b
Run built-in script" - There is a syntax line that includes “-b[run]” which is good, but there still should be a line that describes -b (as mentioned above) and there should be a space between the switch and param. This space is very important since some CLI tools don’t require a space between the switch letter and its param, but uuu does.
- Typically, a param for a switch is shown next to the switch; not in the descriptive text in the second column. For example, it took me a long time to realize that “serial_no” was the placeholder param for -ms and so on for other switches with params.
- What is deamon mode? What capability does it provide? How does one use it?
- WRT -m option: what is a path? It seems to be a USB path. But what is that? How would I use that?
- WRT -bmap/-no-bmap options: what’s a bmap file?
- WRT -ms, -pp, -dm options: no idea what these do
I think UUU is a powerful tool, but learning how to use it is very challenging. Many things could be improved to ease the learning curve such as better docs (wiki/PDF) and app help info.
In order to understand the tool I have compiled a list of questions and issues. I also took the liberty to re-write both the command line help info and PDF. I tried to improve the wording and organization. Where I could, I tried to clarify and correct -- knowing that I might be wrong in my assumptions.
I realize this is a lot of information. I hope that some of it can be leveraged to improve the tool.
General
- A systemic issue is that although the documentation is in English, the grammar is poor. Please get editorial help from a skilled English speaker.
We can use AI to improve it now.
- Does uuu.exe (and usb dll) have to be in same dir as file(s) to load? Or can I use fully qualified paths? In some examples I read they are co-located, but nowhere does it say they have to be even though it sortof seems like it is required.
libusb.dll needn't now. Prebuilt image static link it.
- In the CLI, what is the difference between emmc and emmc_all CLI options? CLI help says emmc burns ‘boot loader’ and emmc_all burns ‘whole image’. That begs the question what is boot loader vs. whole image? A guess: the input to emmc is expected to be a boot-only image whereas the input to emmc_all is expected to be a wic image that contains both the boot and kernel. Is that right?
Yes
- Does UUU support IMX8M Nano? My nano shows as PID 0x013E, but that is not listed in uuu.pdf. Did try to write an image to my nano EVK but always fails.
Yes,
emplace_back(ConfigItem{"SDPS:", "MX815", nullptr, NXP_VID, 0x013E});
you can use
uuu -lsusb
- Found no description of how to exit interactive mode. First, please document this. Second, I discovered via trial-and-error that it’s ‘quit’. Why not ‘done’ like a script?
Oh, most script languadge use "quite"
- The script name auto.uuu seems special. In what ways is it special? I think it’s used if you specify a dir or zip file as bootloader arg in which case uuu uses auto.uuu in the dir or zip file with that name. Is that right? And is that the only condition in which the file name is special?
yes, uuu abc.zip, will scan auto.uuu in zip to avoid you have to extract abc.zip
- CLI help includes “bootloader download bootloader to board by usb” and PDF says “uuu bootloader” is a typical use described as “download uboot”.
It is just download uboot and run uboot. Don't write to any storage. It is useful to debug uboot.
What storage does this command write to?
Only write to ddr and run buoot.
How is it possible that a relatively simple command like this can work when other commands have so many options to specify? Are there a bunch of defaults associated with this command syntax?
It just only talk which chip ROM. uuu know which chip by PID/VID and know the protocol with ROM.
Documentation -- uuu.pdf
- In general, the PDF is hard to understand due to poor English, wording and organization.
PDF is generate from wiki page. We can use AI help. We improve one page by one page
- WRT use of “download”: I do not consider what uuu does to be downloading. IMO a device is either a server in which case uuu uploads, or a device is peer so it’s writing/loading/copying/burning. If the device was obtaining data from the host PC, then that might be called download.
the device was obtaining data from the host PC, then that might be called download. There are nothing about writing. CHIP ROM get data from UUU(host PC), then jump to an address.
- The Typical usage section is probably intended to simplify learning how to use, but it’s more confusing than helpful. In what way are the commands shown typical? They don’t seem typical to me. Maybe this section is what other docs might call examples.
- The Typical script section is confusing since is there a script that’s typical? Or Frequenctly use script
- WRT Table 1: what is this showing?? What is a fastboot environment?
fastboot is android system burn image command in uboot. It needs some android development background. some environement related this command
- WRT What Firmware Need section: No idea what this is about.
- WRT section 1.7 L4.9.123_2.3.0_8MM GA: how this section important?
It should be out of data.
CLI help info
The help output from the app is better than some apps I’ve used, but it has some issues.
- It seems that the -b switch is very important, but it’s not listed as a switch. I assume it selects a built-in script to run. The built-in scripts are listed but there should be a line like: "-b Run built-in script"
uuu [-d -m -v -bmap -no-bmap] -b[run] <emmc|emmc_all|fat_write|nand|nvme_all|qspi|sd|sd_all|spi_nand|spl> arg... Run Built-in scripts .... you can provide what you want to output to make more clear.
- There is a syntax line that includes “-b[run]” which is good, but there still should be a line that describes -b (as mentioned above) and there should be a space between the switch and param. This space is very important since some CLI tools don’t require a space between the switch letter and its param, but uuu does.
-b is shortcut of -brun, there are another option -bshow to show detail of built-in script.
- Typically, a param for a switch is shown next to the switch; not in the descriptive text in the second column. For example, it took me a long time to realize that “serial_no” was the placeholder param for -ms and so on for other switches with params.
Yes, we can improve it.
- What is deamon mode? What capability does it provide? How does one use it?
for exmaple: uuu -d uboot.imx
then, you just need press reset button, board will boot automatically. Needn't burn uboot.imx everytime when you change uboot.
- change uboot code
- make
- press board reset button
- goto 1 to next round debug.
If you write a script uuu -d script, we can download uboot/kernel/dtb by usb, needn't burn to SD/eMMC. it will save much time.
- WRT -m option: what is a path? It seems to be a USB path. But what is that? How would I use that?
uuu -lsusb
- WRT -bmap/-no-bmap options: what’s a bmap file?
yocto build will greate bmap file.
- WRT -ms, -pp, -dm options: no idea what these do
if you connect to multi board in PC, you can use -m /ms to tell uuu, which board do you want to burn or download.
Thank you feedback, can you create one issue for one problem. So we can fix one by one.
Hi,
This looks like a good place to dump some further Information for whomever might need it:
I'm referring to https://github.com/nxp-imx/mfgtools/blob/master/uuu/emmc_burn_all.lst
bmap
since it was asked, here is the explanation: https://github.com/yoctoproject/bmaptool bmap-file is created by yocto if you want. it speeds up the flashing process.
Bootloader extraction
Some commands can extract the bootloader from the wic image. This is done by using the "tag" at the end of the bootloader. If you're building using yocto, there is the uuu_bootloader_tag.bbclass that does this: https://github.com/nxp-upstream/meta-freescale/blob/master/classes/uuu_bootloader_tag.bbclass
without the tag, uuu can't automatically extract the bootloader and you have to explicitly supply it when calling uuu.
General workflow:
If you look at the file, you see the two steps:
- load u-boot (="_flash.bin") into the RAM (using SDP/SDPU/SDPV protocol) and execute it.
- in the last block of the file, you see the "FB" lines. This is the Fastboot protocol. It originates from the Android project, but is just a generic protocol to communicate with the bootloader: https://docs.u-boot.org/en/latest/android/fastboot-protocol.html Here, you can see two commands being used:
ucmd
which just calls u-boot commands like setenv and mmc:
https://docs.u-boot.org/en/latest/usage/cmd/env.html (setenv is an alias of env set)
https://docs.u-boot.org/en/latest/usage/cmd/mmc.html
flash
which writes data to the emmc: _flash.bin is the bootloader image (earlier, we wrote it only to RAM, now, we write it to mmc,) _image is the actual image
EMMC bootloader partition
One more thing to note: the EMMC (or SD-card, which is similar) has "hardware partitions": https://www.pengutronix.de/en/blog/2020-10-15-anpassen-einer-emmc.html https://www.embeddedartists.com/wp-content/uploads/2020/04/Working_with_eMMC.pdf When booting from emmc, the i.mx looks at the bootpartition switch and boots from one of the two boot partitions.
when using the FB command to flash the bootloader into one of the eMMC's boot partition, this command is used:
FB: flash -scanterm -scanlimited 0x800000 bootloader _flash.bin
The string bootloader (or bootloader0) is hard-coded in NXP's own u-boot branch, and tells their u-boot into which hardware-partition the data should be written to.
https://github.com/nxp-imx/uboot-imx/blob/lf_v2025.04/include/fb_fsl.h
#define FASTBOOT_PARTITION_BOOTLOADER "bootloader"
this is used by NXP's (formerly Freescale -> FSL) fastboot implementation:
drivers/fastboot/fb_fsl/fb_fsl_dev.c
drivers/fastboot/fb_fsl/fb_fsl_boot.c
drivers/fastboot/fb_fsl/fb_fsl_partitions.c
This always writes the bootloader to boot partition 1. So if you're using mainline u-boot, take care because you might have to modify the uuu scripts.
In the end, there is then the call of the mmc partconf subcommand.
https://docs.u-boot.org/en/latest/usage/cmd/mmc.html
The boot_partition value is set to 1, which refers to Boot partition1 enabled for boot.
(for older u-boot versions, partconf might be replaced by hwpartition instead)
For mainline u-boot, grep for these strings:
EMMC_HWPART_BOOT, EMMC_BOOT_PART_, CONFIG_FASTBOOT_MMC_BOOT
I had a hard time figuring out all of this. I hope it helps someone... Please, NXP, move close to mainline again... This would simplify a lot of things.
cheers
See https://github.com/nxp-imx/mfgtools/wiki/Buildin%20emmc_all%20script