Linux on Chromebook with ARM Mali GPU

Disclaimer

The step-by-step guidelines below provided by Arm for your convenience contain information about downloading and installing files, licensed by third parties, which are subject to their own licence terms and conditions.  Your use of such downloads are expressly subject to those third party terms. You hereby agree to comply with all the terms and conditions imposed on you by the relevant third party terms. You acknowledge that ARM shall have no liability to you in respect of those third party files and that your use of the step-by-step guidelines is at your own risk.

1. Introduction

This guide provides instructions to build and run a GNU/Linux distribution on the Samsung Chromebook devicears as an alternative to the Chrome OS operating system. Some experience with Linux as a programmer is expected in order to use this guide. More specifically, one should be familiar with opening and executing commands in a terminal and mounting storage devices. The supported windowing systems are fbdev (direct frame buffer access), X11 and Weston (Wayland). The instructions are written for several Chromebook variants with accompanying notes to highlight specific things for each of them.

2. Prerequisites

The first prerequisite is to have one of the following devices covered by this guide:

You will then need the following extra items in order to be able to follow this guide:

• SD card (Samsung Chromebook 1) or Micro SD card (other devices) with at least 1GB capacity (approx 800MB required with X11, 900MB with X11 and Weston), Class 10 recommended
• PC with a 64-bit distribution of Linux such as Ubuntu 14.04 LTS or Ubuntu 16.04 LTS
• 3GB of free disk space
• USB-Ethernet adapter to enable network communications

3. Host system preparation

This step is to prepare your host Ubuntu system to compile and install the Chromebook software. You may use an alternative Linux distribution but these instructions have been tested only with Ubuntu 14.04 and 16.04.

3.1 Ubuntu packages

Run the following command to install all the required packages on the host Ubuntu system:

For Ubuntu 14.04:

sudo apt-get install build-essential curl wget git gdisk u-boot-tools
sudo apt-get install device-tree-compiler libssl-dev uuid-dev liblzma-dev libyaml-dev libtspi-dev
sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386 lib32z1-dev lib32bz2-1.0

For Ubuntu 16.04:

sudo apt-get install build-essential curl wget git gdisk u-boot-tools
sudo apt-get install device-tree-compiler libssl-dev uuid-dev liblzma-dev libyaml-dev libtspi-dev
sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386 lib32z1-dev libbz2-1.0:i386

3.2 Git configuration

If this is a new installation of Git, you need to configure your name and email.  Otherwise, cloning the Linux kernel repository will fail.  You can do this with the following commands:

git config --global user.name "Your Name"
git config --global user.email "your email"

3.3 Initial set-up directory

Download the attached mali_chromebook-setup_006.tar.gz set-up archive and extract it in an empty directory:

tar xzf mali_chromebook-setup_006.tar.gz
cd mali_chromebook-setup_006

This archive contains a chromebook-setup.sh script, also referred to as the set-up script, to automate the process of preparing an SD card, as well as some associated data files like Linux kernel patches and configuration files for the Chromebook.

4. Configuration

The set-up script relies on several configuration options. This step is to determine which values you need to use for each of them.

4.1 Determine the Chromebook variant

The ‑‑variant option is to specify the Chromebook variant you want to use. The product code needs to be used, as previously listed in the 2. Prerequisites section.  For example:

--variant=XE303C12 # for Samsung Chromebook 1

4.2 Determine the storage device

You then need to determine the block device associated with your SD card and pass it to the ‑‑storage option. Insert the SD card into as SD card reader on your host computer. There should be a new block device corresponding to the SD card which you can discover by running lsblk:

$ lsblk
NAME  MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
sda    8:0    0  42G  0 disk
├─sda1  8:1    0  38G  0 part /
├─sda2  8:2    0    1K  0 part
└─sda5  8:5    0    4G  0 part [SWAP]
sdc    8:32  1  3.7G  0 disk
├─sdc1  8:33  1  16M  0 part
├─sdc2  8:34  1  16M  0 part
└─sdc3  8:35  1  3.4G  0 part
sr0    11:0    1 1024M  0 rom

In this example, /dev/sdc is the SD card of 4GB in capacity. It’s also possible to look at the kernel messages (only showing relevant lines here):

$ dmesg | tail
sd 8:0:0:1: [sdc] 7744512 512-byte logical blocks: (3.96 GB/3.69 GiB)
sdc: sdc1 sdc2

The option should then look like this:

--storage=/dev/sdX # adjust to match your actual device like /dev/sdc

4.3 Optional: Select Mali driver version

It is highly recommended to use the latest available version of the Mali drivers, in which case this step can be skipped. Otherwise, if you want to use an older driver version, make sure you download the appropriate archives and pass the corresponding version code to the ‑‑mali option. For example, you may use:

--mali=r12p0-04rel0 # to manually specify the Mali driver version

Note: The current version of this guide only supports r12p0 but more driver versions with different features may be made available in the future.

5. Automatic set-up

This step will automatically perform all the necessary actions to install a full Debian system on an SD card which can then be directly used with the Chromebook. Among other things, this means creating partitions, building and installing the Linux kernel as well as copying the Debian operating system files. If you later need to re-run only a subset of this process or if you want to do something different, then please refer to the 8. Manual set-up.

This will automatically download the Debian 9 (Stretch) file system built for the armhf architecture from the Linaro website.

To compile the Linux kernel and bootloader, a Linaro compiler toolchain will be automatically downloaded and extracted in the current directory.

This will also download the source code of the Linux kernel and bootloader for the Chromebook. The exact revisions can be found in the script.

With the SD card still present with the same device name, you now only need to run the do_everything command with options as determined in the previous section:

./chromebook-setup.sh --storage=/dev/sdX --variant=VARIANT do_everything

This typically takes about 20 minutes but will vary greatly depending on the network and SD card speed to download and install files as well as the host PC performance to build the Linux kernel.

After successful completion, you should see these final messages which indicate that the SD card is ready to be inserted into the Chromebook:

Ejecting storage device...
All done.

6. Enable Chromebook developer mode

You now need to enable Developer Mode on the Chromebook to allow booting with an alternative operating system from USB/SD card with the procedure below.

Warning: Enabling Developer Mode will erase all user data. Make a back-up first.

1. Eject the SD card from the host PC and insert it into the Chromebook while it’s powered off.
2. Enter Recovery Mode by holding the ESC and REFRESH (↻ or F3) buttons, and pressing the POWER button.
3. In Recovery Mode press Ctrl+D and ENTER to confirm and enable Developer Mode.
4. After the system reboots, when a warning about ‘OS Verification’ is displayed, press Ctrl+D to boot into Chrome OS. The system will offer to cancel the transitioning to Developer Mode for 30 seconds. With no further action, it will erase all user data. This process may take up to 20 minutes.
5. Once this process is complete the system will reboot; press Ctrl+D to boot into Chrome OS.
6. Press Ctrl+Alt+→ (or F2) to switch to a virtual terminal.
7. Login with username root and an empty password.
8. Enable booting from USB/SD card with:

crossystem dev_boot_usb=1
crossystem dev_boot_signed_only=0

You will now be able to boot from SD card after powering on the Chromebook when the ‘OS Verification’ message is displayed by pressing Ctrl+U. To boot in normal Chrome OS mode, press Ctrl+D. The Chromebook should now be able to boot in fbdev mode, i.e. without any windowing system. Log in as root with an empty password.

7. Extra Chromebook set-up

This step explains how to do just a few extra things on the Chromebook while it’s running. For example, the Debian distribution contains a large repository of packages from which you can install many more programs using the apt-get utility.

7.1 Network

The network should automatically be started at boot time; this can be verified by running ifconfig.

If this does not work, the following commands can be run to bring up the network manually:

ifconfig -a # to find out the name of the usb ethernet interface - usually beginning with enx
dhcpcd enx??? # replace as appropriate

7.2 X11 windowing system

To enable hardware-accelerated graphics rendering with X11, you will need the armsoc DDX driver and compatible Mali user-space driver. As armsoc is not available in the Debian repositories, you need to build it from source. You can run the install-x11.sh script to do this automatically, which gets installed automatically during the setup_rootfs command. Boot the Chromebook, log in as root and run:

./install-x11.sh
. ~/.bashrc # reload the .bashrc to provide the runX alias
runX # to actually start X11

The runX command is being used as a workaround in place of the usual startx command due to an incompatibility between the current versions of the armsoc driver and systemd-logind package. It starts the X server on virtual terminal 12 instead of the current one. This should be removed when a future version of armsoc becomes available.

Note: The graphical performance is currently suboptimal with the X11 windowing system.  Please see section 7.3. Weston windowing system to enable the Weston windowing system.

Note: X11 is currently not supported on the ASUS C201 Chromebook, this should also get resolved with a future armsoc version.

7.3 Weston windowing system

To enable hardware-accelerated graphics rendering with Wayland, you will need to install the relevant Weston/Wayland packages and compatible Mali user-space driver. The install-wayland.sh script can be used to automate this; it should have already been installed as part of the automatic set-up. Boot the Chromebook, log in as root and run:

./install-wayland.sh
runweston-drm # to start weston with DRM backend
runweston-fbdev # to start weston with fbdev backend

The Samsung Chromebook devices support Wayland with Weston and DRM back-end; this provides the best performance.

Note: The ASUS C201 Chromebook only supports Wayland with fbdev backend due to a kernel display driver issue when starting Weston with DRM back-end.

8. Manual set-up

As an alternative to the guidelines described in section 5. Automatic Set-up, it is also possible to run each step of the set-up process manually. This is especially useful if you want to build with a different toolchain, partition the SD card differently, use a different version of Debian or modify the Linux kernel.

To get a detailed description of all the available commands in the set-up script, run:

./chromebook-setup.sh help

Here’s a summary of the syntax:

Usage:

  ./chromebook-setup.sh COMMAND [ARGS] OPTIONS

  Only COMMAND and ARGS are positional arguments; the OPTIONS can be

  placed anywhere and in any order.  The definition of ARGS varies

  with each COMMAND.

Options are detailed in 4. Configuration.  Here’s a short summary of each command:

• format_storage

Create partitions and format the storage device.

• setup_rootfs [ARCHIVE]

Extract Debian archive on the root file system and adjust system configuration.

• get_mali
  

Download the relevant Mali user-side driver archives.

• install_mali

Extract the Mali user-side driver archive into the root file system.

• get_toolchain

Download and extract the default cross-compiler toolchain.

• get_kernel [URL]

Create a shallow clone of the Chromebook Linux kernel Git repository and apply any extra patches.

• build_kernel

Build the Linux kernel and install modules on the root file system.

• get_vboot [URL]

Create a shallow clone of the Chromebook bootloader Git repository.

• build_vboot [ROOT]

Build the bootloader, package it with the Linux kernel image and install it on the boot partition.

Once you’ve completed the manual process, you can run this to safely remove your storage device:

sync
sudo eject /dev/sdX # adjust to match your storage device