diff --git a/README.md b/README.md index 1cd05f92..c5ef74bd 100644 --- a/README.md +++ b/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) diff --git a/en/install-goke.md b/en/install-goke.md index 1fb61a47..97ba71e5 100644 --- a/en/install-goke.md +++ b/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--nor.bin` bootloader. + ### Supported sensors Please look up your sensor in [the list of supported devices][1]. diff --git a/en/nor-split-layout.md b/en/nor-split-layout.md new file mode 100644 index 00000000..8444eeda --- /dev/null +++ b/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--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--universal.bin` boots fixed slots only. + +**The split firmware package** for your SoC, +`openipc.-nor--split.tgz` from the same release, holding +`firmware.bin.`. The plain `openipc.-nor-.tgz` beside it is +the fixed-slot package: `uImage.` and `rootfs.squashfs.`. + +### 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.` at `0x50000` and `rootfs.squashfs.` 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. + diff --git a/en/sysupgrade.md b/en/sysupgrade.md index 951ef0a4..95476a27 100644 --- a/en/sysupgrade.md +++ b/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--nor.bin` bootloader, `sysupgrade -k -r` installs the +[NOR split layout](nor-split-layout.md) from `openipc.-nor--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.