rpi: improve documentation

=====

To be able to use your RaspberryPi board with the images generated by

Buildroot, you have a prior choice to make, will you use:

    - Volatile rootfs in RAM (The rootfs is an initramfs) or

    - Persistent rootfs on the SDCard

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

Volatile rootfs

How to build it

===============

How to build it

---------------

Configure Buildroot

-------------------

You need to use the rpi_defconfig, to do so:

 * make rpi_defconfig

The rpi_defconfig configuration is a minimal configuration with all that

is required to bring the Raspberry Pi. You should base your work on this

defconfig:

Then, you need to select the kind of images you want:

 * make menuconfig

 * Select "Filesystem images"

 * Select "initial RAM filesystem linked into linux kernel"

  $ make rpi_defconfig

What is generated

-----------------

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

After building, you should obtain this tree:

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

    output/images/

    +-- rootfs.tar

    +-- rpi-firmware

    |   +-- bootcode.bin

    |   +-- config.txt

    |   +-- fixup_cd.dat

    |   +-- fixup.dat

    |   +-- start_cd.elf

    |   `-- start.elf

    `-- zImage

  $ make menuconfig

    * Select "Filesystem images"

    * Select "initial RAM filesystem linked into linux kernel"

Note : rootfs.tar will only be there if you kept "tar the root filesystem"

option selected in "Filesystem images".

You may also deselect "tar the root filesystem".

Where should the binaries be copied on the SDCard

-------------------------------------------------

Build the rootfs

----------------

Your SDCard must have its first partition using fat32 and marked bootable.

Note: you will need to have access to the network, since Buildroot will

download the packages' sources.

At the root of the partition, the RaspberryPi must find the following files:

You may now build your rootfs with:

 * bootcode.bin

 * config.txt

 * fixup_cd.dat

 * fixup.dat

 * start_cd.elf

 * start.elf

 * zImage

  $ make

So you should copy the entire content of output/images/rpi-firmware along with

zImage.

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

Note: You can create any number of partitions you desire, the only requirement

is that the first partition must be using fat32 and bootable.

Persistent rootfs

=================

How to build it

---------------

You only need to use the rpi_defconfig, to do so:

 * make rpi_defconfig

What is generated

-----------------

Result of the build

-------------------

After building, you should obtain this tree:

    output/images/

    +-- rootfs.tar

    +-- rpi-firmware

    |   +-- bootcode.bin

    |   +-- config.txt

    |   +-- fixup_cd.dat

    |   +-- fixup.dat

    |   +-- start_cd.elf

    |   `-- start.elf

    |   +-- bootcode.bin

    |   +-- config.txt

    |   +-- fixup_cd.dat

    |   +-- fixup.dat

    |   +-- start_cd.elf

    |   `-- start.elf

    `-- zImage

Where should the binaries be copied on the SDCard

-------------------------------------------------

Note for Volatile: rootfs.tar will only be there if you kept

"tar the root filesystem" option selected in "Filesystem images".

Your SDCard must have its first partition using fat32 and marked bootable.

It should also have another partition which will contain your rootfs, it should

be partitioned as ext4.

Prepare you SDCard

==================

Boot partition

~~~~~~~~~~~~~~

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.

The first partition will contain everything used to boot the RaspberryPi.

You must copy theses files at the root of partition:

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 RaspberryPi must find the following

files:

    * bootcode.bin

    * config.txt

 * fixup_cd.dat

    * fixup.dat

 * start_cd.elf

    * start.elf

    * zImage

So you should copy the entire content of output/images/rpi-firmware along with

zImage.

For example:

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

 $ cp output/images/zImage /mnt/mountpointboot/zImage.img

Note: The default name is kernel.img.

Actually, the name is zImage and it's define in the file config.txt like:

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 rootfs.tar -C /mnt/mountpointroot

Rootfs partition

~~~~~~~~~~~~~~~~

Finish

======

The second partition will contain your rootfs.

Simply extract (as root!) the contents of the rootfs.tar archive

into this partition.

Unmount all the partitions:

For example: (Assuming mountpoint is a directory and exist)

  $ sudo umount /mnt/mountpointboot

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

 $ sudo mount /dev/sdXY /mnt/mountpoint

 $ sudo tar xf rootfs.tar -C /mnt/mountpoint

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.