# SOM Testing - eMMC Boot Configuration

## Purpose
Set eMMC boot configuration during SOM functional testing to enable devices to boot from eMMC after production programming.

## When to Run
During SOM testing phase, when booted from SD card into U-Boot console.

## Prerequisites
- SOM booted from SD card (DIP switches: BOOT2=0, BOOT1=1, BOOT0=0)
- Access to U-Boot console (serial or SSH to running Linux)
- eMMC device (mmc 1) present

---

## Quick Setup (Recommended)

**Boot from SD card**, interrupt U-Boot, and run these **three commands**:

```bash
STM32MP> mmc dev 1
STM32MP> mmc partconf 1 1 2 0
STM32MP> mmc bootbus 1 0 0 0
```

**Done!** This sets boot configuration registers. Mark board as "Boot Config Set" in your test tracking.

---

## Full Setup with Partition Creation (Optional)

If you want to pre-create partitions during SOM testing (not required for recommended workflow):

```bash
# Select eMMC device
mmc dev 1

# Create GPT partition table (OPTIONAL - production will create if needed)
gpt write mmc 1 "name=metadata1,size=1MiB;name=metadata2,size=1MiB;name=fip-a,size=4MiB;name=fip-b,size=4MiB;name=u-boot-env,size=512KiB;name=bootfs,size=64MiB;name=vendorfs,size=16MiB;name=rootfs,size=2GiB;name=userfs,size=-"

# Set eMMC boot configuration (REQUIRED)
mmc partconf 1 1 2 0
mmc bootbus 1 0 0 0

# Verify
mmc part
```

**Note:** For recommended workflow (Option B in PRODUCTION_WORKFLOW.md), partition creation is not needed here - STM32CubeProgrammer will create them on first flash.

---

## What This Does

✅ **Creates GPT partition table** on eMMC user area  
✅ **Sets PARTITION_CONFIG = 0x50** (boot from hardware boot partition 2)  
✅ **Sets BOOT_BUS_CONDITIONS = 0x00** (default, no special bus config)  
✅ **Prepares eMMC** for fast production programming

---

## Important Notes

### PRG-TOOLBOX Writes by Absolute Offset

**Key insight:** PRG-TOOLBOX-FB writes data to **absolute byte offsets** specified in the TSV file, **not** to partition boundaries!

Example from your TSV:
```
P  0x06  metadata1  FWU_MDATA  mmc1  0x00080000  metadata.bin
```

This writes `metadata.bin` to eMMC byte offset `0x00080000` (512KB), regardless of where the GPT partition named "metadata1" starts or ends.

**Therefore:**
- ✅ GPT partition boundaries don't need to be exact
- ✅ Simple `gpt write` with approximate sizes works fine
- ✅ Production programming writes to correct offsets anyway
- ✅ Only boot config registers need to be correct (already done!)

### Boot Partition vs User Partition

The eMMC has two areas:
1. **Hardware boot partitions** (boot0/boot1) - These hold TF-A/FSBL
2. **User area with GPT** - This holds metadata, FIP, filesystems

The `gpt write` command creates partitions in the user area only.  
The boot partitions (boot0/boot1) are separate and will be written during production programming.

### Boot Configuration Registers

- **PARTITION_CONFIG (EXTCSD[179])** = 0x50
  - Tells ROM bootloader to boot from boot partition 2 (boot1)
  
- **BOOT_BUS_CONDITIONS (EXTCSD[177])** = 0x00
  - Default bus settings (no SDR/DDR config)

These settings:
- ✅ Persist across power cycles
- ✅ Survive production programming (if TSV uses P flag only)
- ❌ Get reset if `gpt write` runs again (why production uses P-only TSV)

---

## Verification

To verify eMMC is properly configured, run in U-Boot:

```bash
# Check partitions exist
mmc dev 1
mmc part

# You should see metadata1, metadata2, fip-a, fip-b, bootfs, vendorfs, rootfs, userfs
```

---

## Next Steps

After SOM testing completes:
1. ✅ Mark board as "eMMC initialized"  
2. ✅ Send to production programming station  
3. ✅ Run `production_program_service.py` for fast programming (<2 min)  
4. ✅ Device will boot from eMMC immediately!

---

## Troubleshooting

### "gpt write failed"
- Ensure eMMC is detected: `mmc list`
- Ensure mmc 1 is selected: `mmc dev 1`
- Check eMMC is not write-protected
- If partitions already exist, that's OK - skip to boot config commands

### "mmc partconf failed"
- Ensure eMMC supports boot partitions
- STM32MP257 with 32GB eMMC should support this

### Already ran this once - can I run it again?
**If partitions already exist:** Just run the boot config commands:
```bash
mmc dev 1
mmc partconf 1 1 2 0
mmc bootbus 1 0 0 0
```

**Do NOT try to wipe GPT** - it can crash U-Boot. Existing partitions are fine!

---

## Summary

This one-time setup during SOM testing enables:
- ⚡ **8x faster production programming** (2 min vs 20 min)
- 🚀 **No STM32CubeProgrammer** needed for production
- ✅ **PRG-TOOLBOX-FB** fast partition writes
- ✅ **Automated parallel programming** for multiple boards

**Time investment:** 30 seconds per board during testing  
**Time savings:** 18 minutes per board during production programming  
**Total savings:** 17.5 minutes per board! 🎉