board/raspberrypi/readme.txt

Raspberry Pi

Intro
=====

These instructions apply to all models of the Raspberry Pi:
  - the original models A and B,
  - the "enhanced" models A+ and B+,
  - the model B2 (aka Raspberry Pi 2).

To be able to use your Raspberry Pi board with the images generated by
Buildroot, you have to choose whether you will use:

    * Volatile rootfs in RAM (the rootfs is an initramfs) or
    * Persistent rootfs on the SDCard

Also, a good source of information is http://elinux.org/R-Pi_Hub

How to build it
===============

Configure Buildroot
-------------------

There are two RaspberryPi defconfig files in Buildroot, one for each
major variant, which you should base your work on:

For models A, B, A+ or B+:

  $ make raspberrypi_defconfig

And for model 2 B:

  $ make raspberrypi2_defconfig

If you want to use a persistent rootfs, skip to "Build the rootfs", below.

For a volatile rootfs, you have to slightly adjust the configuration:

  $ make menuconfig
    * Select "Filesystem images"
    * Select "initial RAM filesystem linked into linux kernel"

You may also deselect "tar the root filesystem".

Build the rootfs
----------------

Note: you will need to have access to the network, since Buildroot will
download the packages' sources.

You may now build your rootfs with:

  $ make

(This may take a while; consider getting yourself a coffee ;-) )

Result of the build
-------------------

After building, you should obtain this tree:

    output/images/
    +-- rootfs.tar                  [0]
    +-- rpi-firmware/
    |   +-- bootcode.bin
    |   +-- config.txt
    |   +-- fixup.dat
    |   `-- start.elf
    +-- bcm2708-rpi-b.dtb           [1]
    +-- bcm2708-rpi-b-plus.dtb      [1]
    +-- bcm2709-rpi-2-b.dtb         [1]
    `-- zImage

[0] Note for Volatile: rootfs.tar will only be there if you kept
    "tar the root filesystem" option selected in "Filesystem images".

[1] Not all of them will be present, depending on the RaspberryPi
    model you are using.

Prepare you SDCard
==================

For more information, visit
http://elinux.org/RPi_Advanced_Setup#Advanced_SD_card_setup

In summary, your SDCard must have first partition in fat32 and marked bootable.

Create the required partitions:
  - for a persistent rootfs, 10MiB is enough memory for the boot fat32
    partition, and a second partition is required for the root filesystem
  - for a volatile rootfs, 50MiB is required for the boot fat32 partition

Note: You can create any number of partitions you desire, the only requirement
is that the first partition must be using fat32 and be bootable.

Mount the partitions (adjust 'sdX' to match your SDcard device):

  $ sudo mount /dev/sdX1 /mnt/mountpointboot
  $ sudo mount /dev/sdX2 /mnt/mountpointroot    (only for persistent rootfs)

Install the binaries to the SDCard
----------------------------------

At the root of the boot partition, the Raspberry Pi must find the following
files:

    * bcm2708-rpi-b.dtb         [2]
    * bcm2708-rpi-b-plus.dtb    [3]
    * bcm2709-rpi-2-b.dtb       [4]
    * bootcode.bin
    * config.txt
    * fixup.dat
    * start.elf
    * zImage

[2] For models A and B
[3] For models A+ and B+
[4] For model 2

For example:

  $ cp output/images/rpi-firmware/* /mnt/mountpointboot
  $ cp output/images/*.dtb /mnt/mountpointboot

The kernel image must be marked with a special header so that the
bootloader of the RaspberryPi knows it supports Device Tree:

  $ ./output/host/usr/bin/mkknlimg output/images/zImage /mnt/mountpointboot/zImage

Note: The kernel image file name is defined in config.txt like this:
kernel=zImage

If you use a volatile rootfs, Skip to "Finish", below. For a persistent
rootfs, there are further steps to do.

Extract (as root!) the contents of the rootfs.tar archive into the second
partition you created above:

  $ sudo tar xf ./output/images/rootfs.tar -C /mnt/mountpointroot

Finish
======

Unmount all the partitions:

  $ sudo umount /mnt/mountpointboot
  $ sudo umount /mnt/mountpointroot     (only for persistent rootfs)

And eject your SDcard from your computer SDcard reader.

Insert the SDcard into your Raspberry Pi, and power it up. Your new system
should come up, now.