Steep learning curve; improving docs

[stevebroshar]

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

UUU.docx
uuu-help.txt

[nxpfrankli]

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.

1. change uboot code
2. make
3. press board reset button
4. 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.

UUU.docx uuu-help.txt

Thank you feedback, can you create one issue for one problem. So we can fix one by one.