Skip to content

Commit cda1a0a

Browse files
Charliechen114514Charliechen114514
authored
feat: support sd card and emmc ums flash (#61)
* feat: support sd card and emmc ums flash * feat: upload the tutorials
1 parent def3ffd commit cda1a0a

29 files changed

Lines changed: 4830 additions & 1951 deletions

‎document/notes/2026-06-08-sd-card-flashing-bringup.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# 2026-06-08 SD Card Flashing Bring-up Note
2+
3+
## Goal
4+
5+
Build a full i.MX6ULL AES SD card image, write it through a host SD card reader, then boot the board from SD.
6+
7+
This flow is intentionally different from the eMMC UUU + UMS flow:
8+
9+
- SD card: write the raw image directly with a card reader.
10+
- eMMC: boot U-Boot through UUU, expose eMMC with UMS, then write the raw image.
11+
12+
## Project Assumptions
13+
14+
Current project convention:
15+
16+
```text
17+
SD: U-Boot mmc 0, Linux root /dev/mmcblk0p2
18+
eMMC: U-Boot mmc 1, Linux root /dev/mmcblk1p2
19+
```
20+
21+
Generated SD image:
22+
23+
```text
24+
out/release-latest/images/imx6ull-aes-sd.img
25+
```
26+
27+
Generated eMMC image:
28+
29+
```text
30+
out/release-latest/images/imx6ull-aes-emmc.img
31+
```
32+
33+
## Build SD Image
34+
35+
From the project root:
36+
37+
```bash
38+
./scripts/release-all.sh --continue --stage 5 --boot-media sd
39+
```
40+
41+
Equivalent direct image-builder command:
42+
43+
```bash
44+
./scripts/image_builder/build_imx6ull_image.sh --release-dir=out/release-latest --boot-media=sd
45+
```
46+
47+
Expected outputs:
48+
49+
```text
50+
out/release-latest/images/imx6ull-aes-sd.img
51+
out/release-latest/images/imx6ull-aes-sd.img.manifest
52+
out/release-latest/images/imx6ull-aes-sd.img.sha256
53+
```
54+
55+
The manifest should include:
56+
57+
```text
58+
boot_media=sd
59+
uboot_mmc_dev=0
60+
linux_root_dev=/dev/mmcblk0p2
61+
```
62+
63+
## Find Host SD Card Device
64+
65+
Before inserting the SD card:
66+
67+
```bash
68+
lsblk
69+
```
70+
71+
Insert the SD card, then run again:
72+
73+
```bash
74+
lsblk
75+
```
76+
77+
Record the new whole-disk device, for example:
78+
79+
```text
80+
/dev/sdX
81+
```
82+
83+
Do not use a partition path such as `/dev/sdX1` when writing the full image.
84+
85+
## Write SD Image
86+
87+
Replace `/dev/sdX` with the actual whole-disk SD card device:
88+
89+
```bash
90+
sudo dd if=out/release-latest/images/imx6ull-aes-sd.img of=/dev/sdX bs=4M status=progress conv=fsync
91+
sync
92+
```
93+
94+
Alternative GUI tools:
95+
96+
- Rufus: choose DD/raw image mode.
97+
- BalenaEtcher: choose the `.img` file and the SD card device.
98+
99+
## Boot From SD
100+
101+
Insert the SD card into the board and set the board boot mode to SD.
102+
103+
In U-Boot, useful manual checks:
104+
105+
```text
106+
mmc list
107+
mmc dev 0
108+
mmc part
109+
ext4ls mmc 0:1 /
110+
ext4ls mmc 0:2 /
111+
```
112+
113+
If the default environment contains `sdbootaes`, boot with:
114+
115+
```text
116+
run sdbootaes
117+
```
118+
119+
Manual boot fallback:
120+
121+
```text
122+
setenv bootargs console=ttymxc0,115200 root=/dev/mmcblk0p2 rootwait rw
123+
ext4load mmc 0:1 ${loadaddr} /zImage
124+
ext4load mmc 0:1 ${fdt_addr} /imx6ull-aes.dtb
125+
bootz ${loadaddr} - ${fdt_addr}
126+
```
127+
128+
## Linux Verification
129+
130+
After Linux boots:
131+
132+
```bash
133+
cat /proc/cmdline
134+
mount | grep ' / '
135+
lsblk
136+
```
137+
138+
Expected root device:
139+
140+
```text
141+
/dev/mmcblk0p2
142+
```
143+
144+
## Pitfall Log
145+
146+
Use this section during bring-up.
147+
148+
### Pitfall 1
149+
150+
Symptom:
151+
152+
```text
153+
TBD
154+
```
155+
156+
Root cause:
157+
158+
```text
159+
TBD
160+
```
161+
162+
Fix:
163+
164+
```text
165+
TBD
166+
```
167+
168+
### Pitfall 2
169+
170+
Symptom:
171+
172+
```text
173+
TBD
174+
```
175+
176+
Root cause:
177+
178+
```text
179+
TBD
180+
```
181+
182+
Fix:
183+
184+
```text
185+
TBD
186+
```

‎document/notes/2026-06-08-uuu-ums-emmc-bringup.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# 2026-06-08 UUU + UMS + eMMC Bring-up Note
2+
3+
## Goal
4+
5+
Bring up the i.MX6ULL AES board through USB SDP, expose eMMC through UMS, burn a full eMMC image, then boot either:
6+
7+
- `run netbootaes`: TFTP kernel/DTB + NFS rootfs.
8+
- `run emmcbootaes`: eMMC boot partition kernel/DTB + eMMC rootfs.
9+
10+
## Conversation Summary
11+
12+
1. Initial plan was to avoid unstable fastboot flashing.
13+
2. UUU should only boot U-Boot into RAM through USB SDP.
14+
3. U-Boot should expose eMMC through UMS.
15+
4. The host should not copy only `zImage`/DTB to a mounted drive letter for production flashing, because that can miss raw U-Boot, partition table, or rootfs.
16+
5. Correct full burn flow: use Rufus/DD/raw-image mode to write `out/release-latest/images/imx6ull-aes-emmc.img` to the UMS-exposed eMMC.
17+
6. First UUU lst failed because it referenced `u-boot-dtb.imx` relative to `tools/uuu/`.
18+
7. Fixed lst to load `../../out/release-latest/uboot/u-boot-dtb.imx`.
19+
8. U-Boot then entered old `bootcmd_mfg`, which fell through to `fastboot 0`.
20+
9. Fixed board default manufacturing environment so USB/mfgtools boot runs UMS instead of fastboot.
21+
10. Updated both U-Boot source and `patches/uboot-imx/charlies_board.patch`.
22+
11. Rebuilt U-Boot at `out/release-latest/uboot/u-boot-dtb.imx`.
23+
12. Verified the new U-Boot image contains:
24+
25+
```text
26+
bootcmd_mfg=echo Run eMMC UMS ...; mmc dev ${emmc_dev}; ums 0 mmc ${emmc_dev};
27+
```
28+
29+
## Files Changed
30+
31+
- `tools/uuu/imx6ull-aes-ums.lst`
32+
- `tools/uuu/README.md`
33+
- `third_party/uboot-imx/include/configs/mx6ull_aes_emmc.h`
34+
- `patches/uboot-imx/charlies_board.patch`
35+
36+
## Current U-Boot Environment Snapshot
37+
38+
The board currently reports:
39+
40+
```text
41+
baudrate=115200
42+
bootcmd=echo Current do not autoboot
43+
bootcmd_mfg=mmc dev 1; ums 0 mmc 1
44+
bootdelay=-1
45+
emmc_dev=1
46+
ethact=ethernet@20b4000
47+
ethprime=eth1
48+
loadaddr=0x80800000
49+
```
50+
51+
The environment is minimal and needs normal boot variables.
52+
53+
## Host-side Assumptions
54+
55+
TFTP directory:
56+
57+
```text
58+
~/tftp
59+
```
60+
61+
Files expected in TFTP:
62+
63+
```text
64+
zImage
65+
imx6ull-aes.dtb
66+
```
67+
68+
NFS rootfs:
69+
70+
```text
71+
/home/charliechen/imx-forge/rootfs/nfs
72+
```
73+
74+
Common tutorial network values:
75+
76+
```text
77+
board ipaddr = 192.168.60.200
78+
serverip = 192.168.60.1
79+
netmask = 255.255.255.0
80+
gatewayip = 192.168.60.1
81+
```
82+
83+
## Host Preparation
84+
85+
Copy TFTP files:
86+
87+
```bash
88+
mkdir -p ~/tftp
89+
cp out/release-latest/images/zImage ~/tftp/
90+
cp out/release-latest/images/imx6ull-aes.dtb ~/tftp/
91+
chmod a+r ~/tftp/zImage ~/tftp/imx6ull-aes.dtb
92+
```
93+
94+
Historical kernel NFS server `/etc/exports` entry:
95+
96+
```text
97+
/home/charliechen/imx-forge/rootfs/nfs 192.168.60.0/24(rw,sync,no_subtree_check,no_root_squash)
98+
```
99+
100+
Reload kernel NFS exports:
101+
102+
```bash
103+
sudo exportfs -ra
104+
sudo systemctl restart nfs-kernel-server
105+
```
106+
107+
Note: on the newer WSL2 setup, kernel `nfs-kernel-server` hung on local NFSv3 mounts. Use NFS-Ganesha instead and pin `mountport=20048`. See:
108+
109+
```text
110+
document/notes/2026-06-08-wsl2-nfsroot-ganesha-troubleshoot.md
111+
```
112+
113+
## U-Boot Environment: Quick Paste Block
114+
115+
Paste this in U-Boot, adjusting IP values if the host network differs:
116+
117+
```text
118+
setenv ipaddr 192.168.60.200
119+
setenv serverip 192.168.60.1
120+
setenv gatewayip 192.168.60.1
121+
setenv netmask 255.255.255.0
122+
setenv hostname imx6ull-aes
123+
setenv nfs_iface eth0
124+
setenv loadaddr 0x80800000
125+
setenv fdt_addr 0x83000000
126+
setenv fdt_addr_r 0x83000000
127+
setenv bootfile zImage
128+
setenv fdt_file imx6ull-aes.dtb
129+
setenv nfsrootdir /home/charliechen/imx-forge/rootfs/nfs
130+
setenv nfsargs 'setenv bootargs console=ttymxc0,115200 root=/dev/nfs rw nfsroot=${serverip}:${nfsrootdir},vers=3,proto=tcp,nolock,port=2049,mountport=20048 ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${nfs_iface}:off'
131+
setenv netbootaes 'run nfsargs; tftp ${loadaddr} ${bootfile}; tftp ${fdt_addr} ${fdt_file}; bootz ${loadaddr} - ${fdt_addr}'
132+
setenv emmcargs 'setenv bootargs console=ttymxc0,115200 root=/dev/mmcblk1p2 rootfstype=ext4 rootwait rw'
133+
setenv emmcdevsetup 'mmc dev ${emmc_dev}'
134+
setenv loademmcimage 'ext4load mmc ${emmc_dev}:1 ${loadaddr} /zImage'
135+
setenv loademmcfdt 'ext4load mmc ${emmc_dev}:1 ${fdt_addr} /imx6ull-aes.dtb'
136+
setenv emmcbootaes 'run emmcargs; run emmcdevsetup; run loademmcimage; run loademmcfdt; bootz ${loadaddr} - ${fdt_addr}'
137+
setenv bootcmd 'run emmcbootaes'
138+
setenv bootdelay 1
139+
saveenv
140+
```
141+
142+
Manual test commands:
143+
144+
```text
145+
run netbootaes
146+
run emmcbootaes
147+
```
148+
149+
If eMMC rootfs fails with `VFS: Cannot open root device`, try:
150+
151+
```text
152+
setenv emmcargs 'setenv bootargs console=ttymxc0,115200 root=/dev/mmcblk0p2 rootfstype=ext4 rootwait rw'
153+
run emmcbootaes
154+
```
155+
156+
## Current Caveat
157+
158+
`out/release-latest/images/imx6ull-aes-emmc.img` must be regenerated after U-Boot changes if the image should contain the latest eMMC-resident U-Boot. The temporary UUU U-Boot only runs from RAM.

0 commit comments

Comments
 (0)