nor-split-layout: kernel and rootfs in one partition on the GK7205V200 family

README.md

@@ -75,6 +75,7 @@ OpenIPC Wiki
 - [Upgrade firmware](en/sysupgrade.md)
 - [Moving between lite and ultimate without a UART](en/lite-ultimate-migration.md)
 - [NAND flash layouts](en/nand-rootfs-layouts.md)
+- [NOR split layout (GK7205V200 family)](en/nor-split-layout.md)
 - [Failsafe mode and recovery](en/failsafe-recovery.md)
 - [Nightly builds, dated releases, and bisect](en/nightly-builds-and-bisect.md)
 - [Automatic image tuning](en/automatic-image-tuning.md)

en/install-goke.md

@@ -4,6 +4,10 @@
 For XM boards with SoC GK7202V300, GK7205V200, GK7205V300 ONLY!!!
 -----------------------------------------------------------------
 
+These SoCs can also run the [NOR split layout](nor-split-layout.md): kernel and
+root filesystem in one partition, with no 2 MiB kernel slot to outgrow. It needs
+the OpenIPC `u-boot-<soc>-nor.bin` bootloader.
+
 ### Supported sensors
 
 Please look up your sensor in [the list of supported devices][1].

en/nor-split-layout.md

@@ -0,0 +1,163 @@
+# OpenIPC Wiki
+[Table of Content](../README.md)
+
+NOR split layout (GK7205V200 family)
+====================================
+
+A NOR camera normally keeps the kernel and the root filesystem in fixed slots:
+2 MiB for the kernel at `0x50000`, then 5 MiB (8 MB flash) or 10 MiB (16 MB
+flash) for the root filesystem, then the overlay with your settings. Each image
+has to fit its own slot. A kernel that grows past 2 MiB cannot borrow the room
+the root filesystem leaves free, and the other way round.
+
+On GK7205V200, GK7205V300, GK7202V300 and GK7605V100 there is a second layout.
+Kernel and root filesystem sit back to back in one partition, and only their sum
+has to fit the chip:
+
+```
+0x000000  u-boot    256K  U-Boot
+0x040000  env        64K  U-Boot environment
+0x050000  firmware  rest  one image, divided by the kernel at boot:
+            kernel       a FIT: the kernel and its device tree, each with
+                         a CRC32 and a SHA-1 hash
+            rootfs       the squashfs, from the next 64 KiB block
+            rootfs_data  your settings (the overlay), from the end of the
+                         squashfs to the end of the chip
+```
+
+The image is `firmware.bin`. The kernel's `mtdsplit` finds where the FIT ends and
+the squashfs begins, and adds the `kernel`, `rootfs` and `rootfs_data`
+partitions itself. A bigger or smaller image simply moves where `rootfs_data`
+starts.
+
+U-Boot checks both hashes before it starts the kernel, so a kernel the flash has
+corrupted is refused instead of crashing:
+
+```
+   Verifying Hash Integrity ... crc32+ sha1+ OK
+```
+
+### What it needs
+
+**The OpenIPC U-Boot for your SoC**, `u-boot-<soc>-nor.bin` from the
+[firmware release](https://github.com/OpenIPC/firmware/releases/tag/latest).
+Only this bootloader boots the layout. It still boots the fixed slots too. It
+looks at what is at `0x50000` on every boot and sets the partitions to match.
+The older `u-boot-<soc>-universal.bin` boots fixed slots only.
+
+**The split firmware package** for your SoC,
+`openipc.<soc>-nor-<variant>-split.tgz` from the same release, holding
+`firmware.bin.<soc>`. The plain `openipc.<soc>-nor-<variant>.tgz` beside it is
+the fixed-slot package: `uImage.<soc>` and `rootfs.squashfs.<soc>`.
+
+### Which layout is my camera using?
+
+```sh
+cat /proc/cmdline
+cat /proc/mtd
+```
+
+On the split layout the command line has `mtdparts=sfc:256k(u-boot),64k(env),-(firmware)`,
+and `/proc/mtd` shows `firmware` with the three partitions the kernel added:
+
+```
+dev:    size   erasesize  name
+mtd0: 00040000 00010000 "u-boot"
+mtd1: 00010000 00010000 "env"
+mtd2: 00fb0000 00010000 "firmware"
+mtd3: 001e0000 00010000 "kernel"
+mtd4: 00dd0000 00010000 "rootfs"
+mtd5: 00730000 00010000 "rootfs_data"
+```
+
+`openipc_nor_fit=1` on the command line means the bootloader can boot the split
+layout, whichever layout the camera is on now. That's what `sysupgrade` looks
+for before it installs a `firmware.bin`.
+
+### Moving a camera to the split layout
+
+1. **Install the OpenIPC U-Boot.** Run this from the U-Boot console with a TFTP
+   server, using the file for your SoC. It erases the boot partition only
+   (`0x40000`), and leaves the environment where it is:
+
+   ```
+   tftp ${baseaddr} u-boot-gk7205v300-nor.bin
+   sf probe 0
+   sf erase 0x0 0x40000
+   sf write ${baseaddr} 0x0 ${filesize}
+   reset
+   ```
+
+   The camera boots its fixed slots as before. `cat /proc/cmdline` now shows
+   `openipc_nor_fit=1`.
+
+2. **Upgrade with `sysupgrade -k -r`.** On a bootloader that boots the layout,
+   `sysupgrade` downloads the `-split` package and writes `firmware.bin` at
+   `0x50000`. Your settings move with it (see below).
+
+   A camera whose firmware predates the split layout installs the plain package
+   on the first run. Run `sysupgrade -k -r` once more to move to the split
+   layout.
+
+[defib](https://github.com/OpenIPC/defib) can also set a camera up on the split
+layout from scratch over UART: `defib install` with the `-split` package. That
+erases the settings.
+
+### Upgrades and your settings
+
+`sysupgrade -k -r`, `--url`, `--channel` and `--archive` work as on any other
+camera. Because the overlay starts wherever the new image ends, `sysupgrade`
+does more than write the image:
+
+1. It packs the overlay into RAM.
+2. It writes `firmware.bin`.
+3. It stages the settings where the new `rootfs_data` will start:
+
+   ```
+   Writing /tmp/firmware.bin.gk7205v300 at 0x50000
+   Settings staged at 0x8d0000 for the first boot
+   ```
+
+On the first boot, before the overlay is mounted, the camera restores them:
+
+```
+Restoring settings carried over by an upgrade...
+Settings restored.
+```
+
+`sysupgrade -n` stages nothing to restore. The first boot then starts from
+defaults:
+
+```
+Clearing settings after an upgrade...
+```
+
+`sysupgrade` reads every write back from the flash before it reboots. It refuses
+the following before writing anything, and the camera keeps running:
+
+- a `firmware.bin` for another SoC;
+- an image that leaves no room for the settings;
+- the plain package on a camera already on the split layout;
+- a split image on a bootloader without `openipc_nor_fit=1`.
+
+### Writing the image from U-Boot
+
+This replaces everything after the environment and erases the settings. The
+erase size is the chip size minus `0x50000`: `0x7b0000` on 8 MB flash, `0xfb0000`
+on 16 MB.
+
+```
+tftp ${baseaddr} firmware.bin.gk7205v300
+sf probe 0
+sf erase 0x50000 0xfb0000
+sf write ${baseaddr} 0x50000 ${filesize}
+reset
+```
+
+### Going back to fixed slots
+
+Write `uImage.<soc>` at `0x50000` and `rootfs.squashfs.<soc>` at the fixed
+rootfs slot, as in [Upgrade firmware](sysupgrade.md) (*From U-Boot*). On a
+U-Boot environment from this bootloader, `run ur; run uk` does the same. The
+bootloader sees the uImage at `0x50000` and boots the fixed slots again.
+

en/sysupgrade.md

@@ -20,6 +20,12 @@ There are other options available so you can use a local copy of the Linux kerne
 
 __ATTENTION! Upgrading firmware can lead to "bricking" your camera. Make sure you are prepared both morally and skill wise. Have your rescue SD card and/or UART adapter ready. Be prepared to de-solder and reprogram flash chip as the last resort. Do not upgrade production cameras unless you really have to!__
 
+On GK7205V200, GK7205V300, GK7202V300 and GK7605V100 with the OpenIPC
+`u-boot-<soc>-nor.bin` bootloader, `sysupgrade -k -r` installs the
+[NOR split layout](nor-split-layout.md) from `openipc.<soc>-nor-<variant>-split.tgz`
+and carries your settings across. The offsets in *From U-Boot* below are for the
+fixed-slot layout.
+
 ### Using sysupgrade
 `sysupgrade -k -r` gives you the latest release for your camera, as described above; if you wish to revert to a previous image, or load your own updates, then use any of the options described below.