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.


Chromebook-Seemore-450px.jpeg

1. Introduction

This guide provides instructions to build and run a GNU/Linux distribution on the Samsung Chromebook devices 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) and X11. 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:

  • Samsung Chromebook 1 XE303C12
  • Samsung Chromebook 2 11.6″ XE503C12
  • Samsung Chromebook 2 13.3″ XE503C32

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

  • SD card (Chromebook 1) or Micro SD card (Chromebook 2) with at least 1GB capacity (approx 800MB required with X11), Class 10 recommended
  • PC with a 64-bit distribution of Linux such as Ubuntu 12.04.3 LTS or Ubuntu 14.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 12.04 and 14.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 12.04:

 

sudo apt-get install build-essential curl wget git gdisk uboot-mkimage
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




















 

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_004.tar.gz set-up archive and extract it in an empty directory:

 

tar xzf mali_chromebook-setup_004.tar.gz
cd mali_chromebook-setup_004




















 

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.

 

3.4 ARM® Mali™ user-side drivers

It is necessary to manually download into the current set-up directory the Mali user-side binary driver archives for the GPU that matches your device from the ARM Mali user-side drivers download page after accepting the terms of the accompanying End-User Licensing Agreement (EULA).

Each Mali GPU user-side driver is compiled for a specific combination of driver version, GPU type, windowing system, operating system and CPU architecture. In the case of this guide, we need drivers built for 32-bit ARM v7 to run on GNU/Linux. Please download the archives for both fbdev and X11 windowing systems. By default, this guide will assume that the latest and recommended version of the drivers is being used: r5p0-06rel0. It is also possible to use previous versions if required: r4p1-00rel0, r4p0-02rel0.

The list below shows you which Mali GPU is present in each Chromebook variant:

  • Samsung Chromebook 1 XE303C12: Mali-T60x
  • Samsung Chromebook 2 11.6″ XE503C12: Mali-T62x
  • Samsung Chromebook 2 13.3″ XE503C32: Mali-T62x

It is not required to manually extract the archives now, the set-up script will do this automatically when installing the drivers directly onto the SD card.

Note:The name of each binary driver archive follows a convention which is used by the set-up script to automatically select the correct one for a given Chromebook variant. If the required archive is missing, a clear error will be reported with the name of the archive to download.

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





















Warning: If you pick the wrong device you may erase all the data on your computer. You need to be absolutely sure which device the SD card is.


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=r4p0-02rel0 # to use an older driver version

 

 

5. Automatic set-up

This step will automatically perform all the necessary actions to install a full Ubuntu 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 Ubuntu 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 set-up.

This will automatically download the Ubuntu Core 14.04 file system built for the armhf architecture from the Ubuntu 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.

Note: The graphical performance is currently suboptimal in fbdev mode.  Please see section 7.2. X11 windowing system to enable X11.

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 Ubuntu Core distribution contains a large repository of packages from which you can install many more programs using the apt-get utility.


7.1 Network

After connecting to a network with a USB-Ethernet adapter, run the following command to use DHCP:

 

ifconfig -a # to find out the name of the interface - usually eth0
dhclient eth0 # adjust if it's eth1 for example, if several interfaces are enabled
sudo apt-get install network-manager # to not have to run dhclient manually in the future





















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 Ubuntu repository, you need to build it from source. The install-x11.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:

 

dhclient eth0 # adjust as required
./install-x11.sh
startx # to actually start X11




















 

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 Ubuntu 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:

 

  $0 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.

 

And here’s a short summary of each command:

 

  • format_storage

Create partitions and format the storage device.

  • setup_rootfs [ARCHIVE]

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

  • install_mali

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

  • get_toolchain [URL]

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