Skip to content

Instantly share code, notes, and snippets.

@kapilhp
Last active January 1, 2023 04:33
Show Gist options
  • Save kapilhp/01c3e8fc24d938eeaa45c1c2ab02eaaa to your computer and use it in GitHub Desktop.
Save kapilhp/01c3e8fc24d938eeaa45c1c2ab02eaaa to your computer and use it in GitHub Desktop.

An account of how to create a USB disk that will boot a Linux 4.19 kernel (based off Chrome OS' most recent working kernel) on an Asus C100PA with a Debian ("buster") root file system. This may also work on other veyron-* devices.

Setup USB Disk

In this first step we will create a Chrome OS GPT partition table on USB drive that looks like this:

      start        size    part  contents
           0           1          PMBR
           1           1          Pri GPT header
           2          32          Pri GPT table
          34       65536       1  Label: "kernel"
                                  Type: ChromeOS kernel
                                  UUID: NNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN
                                  Attr: priority=0 tries=0 successful=0 
       65570       65536       2  Label: "alt-kernel"
                                  Type: ChromeOS kernel
                                  UUID: NNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN
                                  Attr: priority=0 tries=0 successful=0 
      131106     7690173       3  Label: "root"
                                  Type: Linux data
                                  UUID: NNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN
     7821279          32          Sec GPT table
     7821311           1          Sec GPT header

If you already know how to do this, then skip the steps given below. (The numbers in the first column are for a specific USB drive. Some of them could be different for you.) Basically, partition 1 will hold the Chrome OS "style" kernel image, partition 3 will have the root file system for Debian. Partition 2 will be useful if one wants to test alternative kernels.

  1. Go to file manager and eject the USB drive if it is mounted.

Note: The commands below need to run as root on Chrome OS. This means that you need to be in developer mode (it is complicated to explain how to do this here). I also prefer to work within crouton in developer mode since it is a familiar Debian environment; in the latter case you need to install fdisk and cgpt with apt-get install fdisk cgpt.

  1. From /proc/partitions figure out the drive name. We will assume that it is /dev/sda.

  2. Run fdisk /dev/sda and type g followed by w to create a new GPT partition table. Or, if you prefer a complete command-line approach run echo label: gpt | sfdisk /dev/sda; alternatively, parted --script /dev/sda mklabel gpt.

  3. Run cgpt create /dev/sda to setup the Chrome OS extensions to the GPT partition table.

  4. Now we create partitions in succession:

    a. cgpt add -b 34 -s 65536 -t kernel -l "kernel" /dev/sda will create partition 1 of size 32M.

    b. cgpt add -b 65570 -s 65536 -t kernel -l alt-kernel /dev/sda will create partition 2. Note that 65570 = 34 + 65536!

    c. Use cgpt show /dev/sda to get the available size for partition 3. If n is the first number in the second last row of the output, then the size is m=n-131106. Note that 131106=65570+65536!

    d. cgpt add -b 131106 -s <m> -t data -l root /dev/sda will create the root partition.

Note: At this point (and various other points!) the Chrome OS utility cros-disks may mount your partitions, you will need to unmount them from the file manager to avoid silly errors.

Create the Debian root file system

This step will create a Debian (buster) root file system on /dev/sda3 (the chosen partition for this) using debootstrap. If you already know how to do this, then you can skip the following steps.

We assume that you want to create a Debian root file system on /dev/sda3, and that this file system is not mounted, and that you have root access.

  1. Create a blank ext4 file system on the partition with mkfs.ext4 /dev/sda3.

  2. Mount it in some empty directory. In Debian (and Crouton) /mnt is usually available for such temporary mounts, so you do mount /dev/sda3 /mnt.

  3. Get a copy of the debootstrap package and install it somewhere. In Debian (and Crouton) this is as easy as apt-get install debootstrap.

  4. Run debootstrap --arch=armhf --foreign buster /mnt to create the Debian buster root file system on the partition mounted at /mnt.

  5. If the above steps were not run on your Chromebook, then you need to eject your drive and get it to your Chromebook. As usual you need to have root on your Chromebook at the partition needs to be mounted somewhere. Since I worked with Crouton, I didn't have to do anything, the partition continued to be mounted at /mnt.

  6. Run the second stage of the installation process with chroot /mnt /debootstrap/debootstrap --second-stage.

  7. At this stage, it is probably a good idea to "expand" /mnt/etc/apt/sources.list to include security and other updates. (Why not?!) So it should look like:

deb http://deb.debian.org/debian/ buster main non-free contrib
deb http://deb.debian.org/debian/ buster-updates main non-free contrib
deb http://deb.debian.org/debian-security buster/updates main non-free contrib
  1. Run chroot /mnt apt-get update and chroot /mnt apt-get upgrade just to get your (minimal) Debian root up-to-date. This also checks that you can connect to the Debian repositories within the chroot. (If you get a name lookup error, you may need to copy /etc/resolv.conf into /mnt/etc/resolv.conf.)

Install Linux Build dependencies

We assume that your Debian root file system is mounted at /mnt and install things required to build the Linux kernel.

  1. Probably a good idea to mount some of the utility filesystems at this point with mount --bind /dev /mnt/dev, chroot /mnt mount -t proc proc /proc and chroot /mnt mount -t sysfs sysfs /sys.

  2. You need to run chroot /mnt apt-get install <pkg> for the packages build-essential, libncurses5-dev, libssl-dev, bc, bison, flex, git, initramfs-tools.

Getting Chrome OS kernel sources, config and firmware

The build process is based on the current stable channel version of Chrome OS. The following steps need to be carried out in the Chrome OS root.

  1. Run modprobe configs to get the running configuration of the Chrome OS kernel in /proc/config.gz. Copy this file to some location accessible to your Crouton.

  2. Run tar -czf /tmp/extras.tar.gz /lib/firmware /opt/google/touch and copy this file to some location accessible to your Crouton.

  3. grep CHROMEOS_RELEASE_BUILDER_PATH /etc/lsb-release should give you something like veyron_minnie-release/R83-13020.87.0. The relevant portion of that is R83-13020

  4. uname -r should give you something like 4.19.113-08544-ge67503bc40df. The relevant parts of that are 4.19 and e67503bc40df (which is the tail following the g --- for Google?).

  5. Browse the Google Chromium Source tree at https://chromium.googlesource.com/chromiumos/third_party/kernel/+/refs/heads/release-R83-13020.B-chromeos-4.19. Note how we used the R83-13020 and 4.19. At the top of the page against commit you will see a hexadecimal number which starts with e67503bc40df (our last relevant part!). This shows that you have the correct source for the kernel that is running on your Chromebook!

  6. Click on the tgz link, or copy the link and download it using curl or wget. It should give you a file called release-R83-13020.B-chromeos-4.19.tar.gz

  7. Make this file accessible to your Crouton if necessary. Now assume that you are in the same situation as the previous step and have your Debian root file system mounted at /mnt.

  8. Make a directory to unpack this archive mkdir -p /mnt/usr/src/linux-chromeos-4.19/.

  9. Unpack the archive with tar -xf release-R83-13020.B-chromeos-4.19.tar.gz -C /mnt/usr/src/linux-chromeos-4.19/

  10. Copy the config.gz from (1) above to /mnt/root/chromeos.config.gz and unzip it with gunzip /mnt/root/chromeos.config.gz.

  11. Unpack extras.tar.gz from (2) above using tar -xf extras.tar.gz -C /mnt so that the files are in /lib/firmware and /opt within the Debian file system.

Building the Chrome OS kernel

Assume that the root of the Debian file system is mounted at /mnt and this has the /dev, /proc and /sys mounts as above as well.

Enter this with chroot /mnt before running the next steps.

  1. Run cd /usr/src/linux-chromeos-4.19/ to enter the kernel sources.

  2. Copy the running (Chrome OS) kernel configuration with cp /root/chromeos.config .config

  3. Enable a few flags in this configuration file.

    • ./scripts/config --enable CONFIG_VT
    • ./scripts/config --enable CONFIG_FRAMEBUFFER_CONSOLE
    • ./scripts/config --enable CONFIG_DRM_FBDEV_EMULATION

The above three are probably essential as a replacement for Chrome OS' use of frecon. The next ones are not very clear. Some experimentation is required to see if they are all required!

  • ./scripts/config --enable CONFIG_DRM_MALI_DISPLAY
  • ./scripts/config --enable CONFIG_ROCKCHIP_LVDS
  • ./scripts/config --enable CONFIG_ROCKCHIP_RGB
  • ./scripts/config --enable CONFIG_DRM_PANEL_LVDS

The following is a way to reduce the size of the kernel and also its debug-ability! You may or may not want to do this!

  • ./scripts/config --disable CONFIG_DEBUG_INFO
  1. Finally, make this into a proper .config with make ARCH=arm -j6 olddefconfig.

  2. Now run make ARCH=arm -j6 <target> for the targets zImage, modules, dtbs, modules_install and dtbs_install.

  3. Before installing the kernel one needs to run ln -s /dev/sda3 /dev/root so that Debian's update-initramfs is able to guess the root file system to build the initrd.img. After this you can run make ARCH=arm -j6 zinstall. Then you can remove the /dev/root link. Don't worry too much about the failure to build the initrd.img as we will not use it to boot the system at this point.

Installing the kernel

At this point you are in the Debian chroot where, in /boot you have your vmlinuz-4.19.113, System.map-4.19.113 and initrd.img-4.19.113 and in /boot/dtbs/4.19.113 you will have the file rk3288-veyron-minnie.dtb.

  1. Install the tools needed to install the kernel with apt-get install vim vboot-utils vboot-kernel-utils u-boot-tools

  2. Create the file /boot/kernel.its with the following contents.

/dts-v1/;

/ {
    description = "Kernel image with one or more FDT blobs";
    images {
        kernel@1{
            description = "kernel";
            data = /incbin/("vmlinuz-4.19.113");
            type = "kernel_noload";
            arch = "arm";
            os = "linux";
            compression = "none";
            hash@1{
                algo = "sha1";
            };
        };
        fdt@1{
            description = "device_tree";
            data = /incbin/("dtbs/4.19.113/rk3288-veyron-minnie.dtb");
            type = "flat_dt";
            arch = "arm";
            compression = "none";
            hash@1{
                algo = "sha1";
            };
        };
    };
    configurations {
        default = "conf@1";
        conf@1{
            kernel = "kernel@1";
            fdt = "fdt@1";
        };
    };
};

  1. Use this to create the FIT image that can be loadedby u-boot with the command mkimage -f /boot/kernel.its /boot/kernel.itb

  2. Create a file /boot/cmdline with the contents

cros_secure console=tty1 noinitrd nosplash root=/dev/sda3 rootfstype=ext4 rw rootwait lsm.module_locking=0 vt.global_cursor_default=1

It is not clear that all these options are required. Some experimentation is needed! Note that /dev/sda3 should probably be replaced with a "UUID" or a label or something.

  1. Create an empty /boot/bootloader.bin file. (Why? No idea!) The command is dd if=/dev/zero of=/boot/bootloader.bin bs=512 count=1

  2. Create the image for the kernel partition with the command

vbutil_kernel --pack /boot/image.kpart --version 1 --arch arm \
    --vmlinuz /boot/kernel.itb --bootloader /boot/bootloader.bin --config /boot/cmdline \
    --keyblock /usr/share/vboot/devkeys/kernel.keyblock \
    --signprivate /usr/share/vboot/devkeys/kernel_data_key.vbprivk 
  1. Install this kernel in /dev/sda1 with dd if=/boot/image.kpart of=/dev/sda1

  2. Activate this for booting with cgpt add -i 1 -P 1 -T 1 -S 1 /dev/sda

At this point your system should be ready! Unmount /dev, /proc and /sys and exit from the "chroot". Then unmount the partition umount /dev/sda3.

Booting your new system

Before rebooting ensure that you have enabled USB booting and disabled verified boot with crossystem dev_boot_usb=1 and crossystem dev_boot_signed_only=0. It should be possible to make sure that only certain signatures are accepted even with these settings according to some docs, but, for now, your system is "wide open" for anyone to install anything! Security has been over-ridden!

After this you can shut down your system and hit Ctrl+U at the usual developer splash screen. If all went well then your Debian system should boot up!

A way to go

This is still not a self-hosting system! One needs to install software to get the network going etc. One can look at links like http://galexander.org/chromebook for this.

@peterg10
Copy link

Followed the above instructions to install on a C100PA on an SD card (mmcblk0 in my case). When I reboot and hold down CTRL-U it fails to boot with "The device you inserted does not contain Chrome OS". I was able to boot ArchLinux on the same device earlier but it has too many problems with the OS installation side that I decided to search for a Debian Howto.

The /boot/ directory contains:

bootloader.bin
cmdline
config-4.19.122
dtbs/
image.kpart
initrd.img-4.19.122
kernel.itb
kernel.its
vmlinuz-4.19.122

I flashed image.kpart to /dev/mmcblk0p1 and the dtbs directory has ./4.19.122/rk3288-veyron-minnie.dtb

Any pointers where I might start troubleshooting?

@kapilhp
Copy link
Author

kapilhp commented Dec 29, 2020

I am working on some updated instructions (when I have the time!).

In brief, a kernel built (using a suitable config file) from the linux-source package in "buster" (version 4.19.160 recently) was able to boot the system. I am now running the device from the internal drive!

  1. You need to make sure that your cgpt show /dev/mmcblk0 command shows that the correct kernel partition is booting.
  2. You need to ensure that "verified boot" is off. Running crossystem | grep dev on Chrome OS will show you values.
  3. Make sure that the kernel command line gives the correct root device.

@peterg10
Copy link

I think the problem may be in step 1. If I check the built in disk, cgpt show mmcblk2 has an GUID entry for PMBR that points to an EFI-SYSTEM partition.
The same for mmcblk0 (SD card) shows nothing after PMBR. Have I missed a step to set that to point to the mmcblkp1 UUID?

(BTW is there a way to ssh into system while it's running ChromeOS so I can post the output of commands?)

@peterg10
Copy link

Using Google Keep extension I can cut and paste now. Here the cgpt output for the SD card:

       start        size    part  contents
           0           1          PMBR
           1           1          Pri GPT header
           2          32          Pri GPT table
        8192       32768       1  Label: "kernel"
                                  Type: ChromeOS kernel
                                  UUID: E636A9FE-929A-6649-88DB-47F0C39EF9C1
                                  Attr: priority=12 tries=5 successful=1 
       40960   124694495       2  Label: "root"
                                  Type: ChromeOS kernel
                                  UUID: AEC5D8F7-3FF0-A94F-9ECD-F999A5A81C23
                                  Attr: priority=0 tries=0 successful=0 
   124735455          32          Sec GPT table
   124735487           1          Sec GPT header

@kapilhp
Copy link
Author

kapilhp commented Dec 30, 2020

Your mistake is with partition 2. It should be of type "ChromeOs rootfs". I assume that it contains your root file system created with debootstrap.

@peterg10
Copy link

I changed partition 2 (you were correct it's the Debian root FS) to ChromeOs rootfs but it did not fix the boot problem. Here is the output now:

           0           1          PMBR
           1           1          Pri GPT header
           2          32          Pri GPT table
        8192       32768       1  Label: "kernel"
                                  Type: ChromeOS kernel
                                  UUID: E636A9FE-929A-6649-88DB-47F0C39EF9C1
                                  Attr: priority=12 tries=5 successful=1 
       40960   124694495       2  Label: "root"
                                  Type: ChromeOS rootfs
                                  UUID: AEC5D8F7-3FF0-A94F-9ECD-F999A5A81C23
   124735455          32          Sec GPT table
   124735487           1          Sec GPT header

Still reports the same "The device you inserted does not contain Chrome OS" message when I press Ctrl-U.

Thanks very much for your help, I feel it's really close to working, I'm just missing something (probably obvious).

@kapilhp
Copy link
Author

kapilhp commented Dec 31, 2020

One way to check that the correct kernel partition is installed is to use futility show /dev/mmcblk0p1 where /dev/mmcblk0p1 is your kernel partition. It should at least show the correct command line at the end.

@peterg10
Copy link

peterg10 commented Jan 5, 2021

I have two environments now, a Micro SD card and a USB stick, neither of which are recognised as bootable Linux partition.

Here's the futility showoutput for the USB stick:

localhost / # futility show /dev/sda1 
Kernel partition:        /dev/sda1
Keyblock:
  Signature:             ignored
  Size:                  0x4b8
  Flags:                 7  !DEV DEV !REC
  Data key algorithm:    4 RSA2048 SHA256
  Data key version:      1
  Data key sha1sum:      d6170aa480136f1f29cf339a5ab1b960585fa444
Kernel Preamble:
  Size:                  0xfb48
  Header version:        2.2
  Kernel version:        1
  Body load address:     0x100000
  Body size:             0x590000
  Bootloader address:    0x68f000
  Bootloader size:       0x1000
  Flags:                 0
Body verification succeeded.
Config:
cros_secure console=tty1 noinitrd nosplash root=/dev/sda3 rootfstype=ext4 rw rootwait lsm.module_locking=0 vt.global_cursor_default=1 

and the same for the Micro SD card:

localhost / # futility show /dev/mmcblk0p1 
Kernel partition:        /dev/mmcblk0p1
Keyblock:
  Signature:             ignored
  Size:                  0x4b8
  Flags:                 7  !DEV DEV !REC
  Data key algorithm:    4 RSA2048 SHA256
  Data key version:      1
  Data key sha1sum:      d6170aa480136f1f29cf339a5ab1b960585fa444
Kernel Preamble:
  Size:                  0xfb48
  Header version:        2.2
  Kernel version:        1
  Body load address:     0x100000
  Body size:             0x590000
  Bootloader address:    0x68f000
  Bootloader size:       0x1000
  Flags:                 0
Body verification succeeded.
Config:
cros_secure console=tty1 noinitrd nosplash root=/dev/mmcblk0p2 rootfstype=ext4 rw rootwait lsm.module_locking=0 vt.global_cursor_default=1

Both look ok to me, they show the command line I would expect to see. Does anything look wrong to you?

Also, checked the crossystem settings:

localhost / # crossystem | grep dev_boot
dev_boot_legacy         = 0                              # [RW/int] Enable developer mode boot Legacy OSes
dev_boot_signed_only    = 0                              # [RW/int] Enable developer mode boot only from official kernels
dev_boot_usb            = 1                              # [RW/int] Enable developer mode boot from USB/SD

@kapilhp
Copy link
Author

kapilhp commented Jan 5, 2021

  • I can't see anything wrong.
  • I suppose it is still booting ChromeOS from the internal drive.
  • Have you ejected all external drives before trying to boot from the stick?
  • If you still have the Arch stick you were able to boot with perhaps you can compare the output of cgpt on both sticks and see if something stands out.

@kapilhp
Copy link
Author

kapilhp commented Jan 16, 2021

@peterg10, in one of your comments your output shows that the partition type for partition 2 is "ChromeOS rootfs".

However, it is (presumably) a Debian filesystem. (I don't know what the precise difference is!).

In any case, it looks like, in the gist, I have suggested that the partition type be "data" (which means "Linux data") according to cgpt add -h. That is what I have on the USB drive I use to boot. I have another drive where this partition has type "basicdata" which also appears to work.

It is possible that this is causing the Chromebook firmware to object. It should be easy to change the type using cgpt and check.

As far as I can see, the kernel itself does not seem to care about the type as long as the correct filesystem (ext4) is on it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment