Custom GCW Zero OS Image
------------------------

This page serves to record everything I've learned about building an OS Image for the GCW Zero.

Existing Images
===============
- `The official image <http://gcw-zero.com/flashing>`_
    - This was last updated 2015-07-23
    - This is based on OpenDingux
- `Current OpenDingux development images <https://github.com/OpenDingux/buildroot>`_
    - GCW Zero update packages, odboot binaries, and toolchains are available `here <https://github.com/OpenDingux/buildroot/releases>`_.
    - These are automatically? built by GitHub actions.
    - Work to bring OpenDingux / device support to newer Linux Kernel versions is supposedly happening in this repo
- `Adam Image <https://github.com/eduardofilo/RG350_adam_image>`_
    - This is built on top of the newer OpenDingux releases.
    - Currently this seems to be fixed to a version from `2022-02-13 <https://github.com/eduardofilo/RG350_adam_image/blob/81b3e833640b8f1db69371dae47dabe248690dc9/build.sh#L6>`_.
    - This image opens up the OpenDingux image and creates a modified userspace with a different launcher and newer appliactions.
    - The boot flow seems to be identical to the OpenDingux upstream.
    
Boot Flow
=========
`UBIBoot <https://github.com/pcercuei/UBIBoot>`_
_______
- Bootloader for launching a Linux Kernel off a UBI partition
- Not really sure what a UBI partition is
- None of the images that I've looked at are using an UBI partition for ``/boot``, they have been FAT32
- All the SDCard images have this program written to them via ``dd``
    - The line that writes this to adam image the image is `here <https://github.com/eduardofilo/RG350_adam_image/blob/81b3e833640b8f1db69371dae47dabe248690dc9/build.sh#L208>`_

Kernel
______
- The canonical source repo lives `here <https://github.com/OpenDingux/linux>`_.
- Kernel sources defconfig lives `here <https://github.com/OpenDingux/linux/blob/jz-6.1/arch/mips/configs/gcw0_defconfig>`_.
- Buildroot defconfig lives `here <https://github.com/OpenDingux/buildroot/blob/opendingux/configs/od_gcw0_defconfig>`_.
- It is probably best to use the OpenDingux kernel fork for now.
    - It looks like there is some upstreaming working being done, but the status of that in unknown.
- Building with the OpenDingux defconfig results in a bootable kernel that is in a compatible format for the existing images
- Changing the kernel format would probably require modifying the UBIBoot build
- One known issue with the latest OpenDingux kernel is that the display output doesn't work.
    - This is fixed based on my testing and `this issue <https://github.com/OpenDingux/buildroot/issues/77>`_.

`Mininit <https://github.com/OpenDingux/mininit>`_
_______
- Mininit is a bootloader that allows loading the root filesystem from a squashfs image called ``rootfs.squashfs``.
- It also supports loading kernel modules from a squashfs image called ``modules.squashfs``.
- After it mounts all the required filesystems, control is handed off to the ``/sbin/init`` binary in the mounted rootfs [1]_.


Booting Debian
==============

Creating a boot partition
_________________________
- TODO

Building the OpenDingux Kernel
______________________________
- `Docker based flow to build the OpenDingux kernel <https://git.ohea.xyz/gcwzero/opendingux-kernel-build>`_
- This builds the RC of kernel 6.1 (and also can support older kernel versions)

Creating a mips32le squashfs rootfs
___________________________________
- `Docker based flow to build rootfs <https://git.ohea.xyz/gcwzero/debian-rootfs>`_

Creating a sdcard image
_______________________
- TODO

Packaging the Kernel as a ``.deb``
__________________________________
- TODO

Packaging userspace applications as ``.deb`` files
__________________________________________________
- TODO

Creating package repo for serving updates
_________________________________________
- TODO

Useful Links
============
- `OpenDingux blog post on new kernel and device tree cleanup work <https://opendingux.net/opendingux/2020/06/09/update-on-gcw-zero-20200531.html>`_
- `Dingoonity forum tutorial on building an image from scratch <https://boards.dingoonity.org/gcw-development/(guide)-build-firmware-from-source-and-flash-to-device/>`_
- `Raspberry Pi automatic filesytem resize deep dive <https://gijs-de-jong.nl/posts/raspberry-pi-file-system-resize-on-first-boot/>`_

Citations
=========
.. [1] https://github.com/OpenDingux/mininit#rootfs-image-layout