Disclaimer

The step-by-step guidelines below from ARM contain information about downloading and installing files, licensed by third parties, which are subject to their own licence terms and conditions.  The step-by-step guidelines are delivered to you for your convenience, and 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

google-chromebookThis is a guide for building a bootable SD card to run Linux on the Samsung Chromebook XE303C12 as an alternative operating system to ChromeOS. The guide assumes some Linux experience as a user and programmer. More specifically, one should be familiar with opening and executing commands in a terminal, mounting/unmounting storage devices and navigating the GUI.

The supported windowing systems are fbdev (direct frame buffer access) and X11. The instructions are written for all variants with accompanying notes where there are differences.

2. Prerequisites
  • Samsung Chromebook XE303C12
  • Full size SD Card with at least 1GB Capacity
  • Host PC with a 64-bit distribution of Linux (Guide below is tested with Ubuntu 12.04.3 LTS 64-bit)

Toolchain

Target Root File System

Mali Device Drivers

With the exception of the root file system, it is presumed all tarballs have been extracted, for example to extract the Mali Kernel Driver use:

 3. Preparing the File System

Install the partitioning tool:


Insert the SD card to a SD card reader. Note: if the card is not empty Ubuntu may attempt to automatically mount the partitions which is undesirable. You should unmount all partitions before executing the commands below.

Discover the block device corresponding to the SD card by issuing lsblk:


In this example, /dev/sdc is the SD card of 4 GB in capacity. From now on, the SD card device shall be referred to as /dev/sdX.

Clear the partition table:


Create the boot partition and set it as bootable. The 2nd command sets special metadata understood by the Chromebook. These flags are not standard thus do not have names. If you are interested you can refer to cgpt sources which can be found in vboot_reference repo in the next sections.


Create and format the root partition:


Mount the root partition and extract the target root filesystem:


Finally, change the root password so you can login after booting the device. Remove the single star (*) character on the line beginning with root. With this change, you can login with user name root and an empty password.


Note: Alternatively you can change the root password by executing passwd inside the target root file system. Please refer to section 5.2.1 for details of how to execute commands inside the target file system.

Install Mali binary userspace driver:


Append the following lines using sudo gedit /mnt/root/.bashrc to load the correct Mali drivers depending on the environment:

 3.1 Preparing X11

Create the X initialization script using sudo gedit /mnt/root/.xinitrc with the following content:


Create the X11 configuration directory:


Create the X configuration file using sudo gedit /mnt/etc/X11/xorg.conf with the following content:

 4. Building the Kernel

4.1 Check out Kernel Sources

Install git with:


Clone the kernel sources:


Enter kernel-next directory and check out this branch and commit:

 4.2 Patch the Kernel

We need to modify some parts of the kernel before building. The lines beginning with a minus (-) character should be deleted, the lines beginning with a plus (+) character should be added.

Note: modifications presented in sub-sections 4.2.1 and 4.2.2. are not necessary if you only want to build for X11.

4.2.1 Bug Fix in DRM SG Alloc Table

File drivers/gpu/drm/drm_prime.c near line 217:

 4.2.2 Enable DMA-Buf Support and Tripple-Buffering to Framebuffer Driver

File drivers/gpu/drm/exynos/exynos_drm_fbdev.c near line 197:

File drivers/gpu/drm/exynos/exynos_drm_fbdev.c near line 73:

File drivers/gpu/drm/exynos/exynos_drm_fbdev.c near line 62:

File drivers/gpu/drm/exynos/exynos_drm_fbdev.c near line 28:

 4.2.3 Update Chromebook Platform Sources for latest Mali Driver

File drivers/gpu/arm/t6xx/kbase/src/platform/chromebook/mali_kbase_config_chromebook.c near line 887:

File drivers/gpu/arm/t6xx/kbase/src/platform/chromebook/mali_kbase_config_chromebook.c near line 485:

File drivers/gpu/arm/t6xx/kbase/src/platform/chromebook/mali_kbase_config_chromebook.c near line 312:

 4.3 Building

Replace the pre-integrated Mali kernel driver with the latest driver:

Generate the default kernel config:

Note: Before building the kernel, you might also want to disable CONFIG_SECURITY_CHROMIUMOS if you need to use drivers which are built as modules by default (e.g., Apple USB Ethernet dongle). You can use xconfig to configure the kernel as follows:

<toolchain prefix> is the path to the toolchain executables without the executables’ canonical names (e.g., gcc, g++, ld). For example, the toolchain prefix to a Linaro toolchain might look like: <path to extracted toolchain directory>/bin/arm-linux-gnueabihf- . Please note that there are no gcc/g++/ld in the prefix as the kernel’s build system will automatically append the correct names during build time.

Build the kernel with:

Once the building process finishes, you can install the kernel modules. The following command is not required for Mali as it is built into the kernel by default. It assumes the root filesystem has been mounted to /mnt as instructed in section 3.

 4.4 Generating Kernel Image

Once the kernel is built, we need to generate a kernel image compatible with the Chromebook’s boot loader. Create a file named kernel.its (or any name of choice) in the kernel’s root directory with the following content:

Install required tools:

Generate the new kernel image. It is assumed that kernel.its file has been created:

4.5  Flashing the Kernel

We need to generate the boot partition using a tool called vbutil_kernel. It is not available in the repo thus we will need to build it from sources.

4.5.1 Building vboot_reference

Install the dependant libraries:

Check out the sources:

Enter vboot_reference directory, check out a specific commit and build:

Once the building process finishes, vbutil_kernel should be available in ./build/utility/ .

4.5.2 Flashing the Kernel

Create a file named boot_params (or any name of choice) containing the boot parameters for the kernel:

Execute the following command inside vboot_reference, it is assumed that boot_params file has been created in this directory:

5. Preparing the Chromebook

We need to enable Developer Mode on the Chromebook to allow booting of an alternative operating system from USB/SD card with the following procedure:

Warning: Enabling Developer Mode will erase all user data.

  1. Enter Recovery Mode by holding the ESC and REFRESH (F3) buttons, and pressing the POWER button
  2. In Recovery Mode press Ctrl+D and ENTER to confirm and enable Developer Mode
  3. After the system reboots, press Ctrl+D to boot into Chrome OS when a warning about ‘OS Verification’ is displayed. 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.
  4. Once this process is completed the system will reboot, press Ctrl+D to boot into Chrome OS.
  5. Press Ctrl+Alt+ => (F2) to switch to a virtual terminal
  6. Login with username root and an empty password
  7. Enable booting from USB/SD card with:

    You will now be able to boot from USB/SD card by pressing Ctrl+U after powering on the Chromebook when the ‘OS Verification’ message is displayed.

Note: You might want to install Network Manager or a DHCP client to more easily setup Internet access after booting the device. To do so please refer to section 5.2.1 and execute the following command in the target root file system:

5.1 Preparing for fbdev

If you follow all steps from the beginning of the guide, you will have a bootable SD card with fully functional Mali driver for direct rendering to the frame buffer.

5.2 Preparing for X11

To enable hardware-accelerated 3D rendering in X11, you will need the armsoc DDX driver and compatible Mali userspace driver. As armsoc is not available in the repo, we need to build it from sources. We will use chroot and qemu ARM emulator to build it inside the root file system. This section assumes the root filesystem has been mounted to /mnt as instructed in section 3.

5.2.1 Chroot-ing the Target Root Filesystem

Install the emulator and copy it into the target root file system:

Setup mount points and chroot into the target:

 5.2.2 Building the DDX Driver

Enable the universe repository with:

Install the required dependencies:

Clone the driver’s sources:

Enter xf86-video-armsoc directory, check out a revision and build:

Install the driver:

5.2.3 Testing

Exit the chroot and teardown the mount points. You may ignore the errors as some services may have been automatically started which prevent unmounting the root file system:

Boot the Chromebook from the SD card, login and test that X11 works by running xinit.