rpi: improve documentation

Signed-off-by: Mathieu Benoit <mathieu.benoit@savoirfairelinux.com>
[yann.morin.1998@free.fr: further improvements for readability and
    completeness]
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>

1 files changed, 84 insertions, 83 deletions

diff --git a/board/raspberrypi/readme.txt b/board/raspberrypi/readme.txt
index 32877951d..47b48186d 100644
--- a/board/raspberrypi/readme.txt
+++ b/board/raspberrypi/readme.txt
@@ -4,124 +4,125 @@ Intro
 =====
 
 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
+-------------------
+
+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:
+
+  $ make rpi_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
+----------------
 
-You need to use the rpi_defconfig, to do so:
- * make rpi_defconfig
+Note: you will need to have access to the network, since Buildroot will
+download the packages' sources.
 
-Then, you need to select the kind of images you want:
- * make menuconfig
- * Select "Filesystem images"
- * Select "initial RAM filesystem linked into linux kernel"
+You may now build your rootfs with:
 
-What is generated
------------------
+  $ 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
     +-- 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
 
-Note : rootfs.tar will only be there if you kept "tar the root filesystem"
-option selected in "Filesystem images".
-
-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.
+Prepare you SDCard
+==================
 
-At the root of the partition, the RaspberryPi must find the following files:
+For more information, visit
+http://elinux.org/RPi_Advanced_Setup#Advanced_SD_card_setup
 
- * bootcode.bin
- * config.txt
- * fixup_cd.dat
- * fixup.dat
- * start_cd.elf
- * start.elf
- * zImage
+In summary, your SDCard must have first partition in fat32 and marked bootable.
 
-So you should copy the entire content of output/images/rpi-firmware along with
-zImage.
+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 bootable.
+is that the first partition must be using fat32 and be bootable.
 
-Persistent rootfs
-=================
-
-How to build it
----------------
+Mount the partitions (adjust 'sdX' to match your SDcard device):
 
-You only need to use the rpi_defconfig, to do so:
- * make rpi_defconfig
+  $ sudo mount /dev/sdX1 /mnt/mountpointboot
+  $ sudo mount /dev/sdX2 /mnt/mountpointroot    (only for persistent rootfs)
 
-What is generated
------------------
+Install the binaries to the SDCard
+----------------------------------
 
-After building, you should obtain this tree:
+At the root of the boot partition, the RaspberryPi must find the following
+files:
 
-    output/images/
-    +-- rootfs.tar
-    +-- rpi-firmware
-    |   +-- bootcode.bin
-    |   +-- config.txt
-    |   +-- fixup_cd.dat
-    |   +-- fixup.dat
-    |   +-- start_cd.elf
-    |   `-- start.elf
-    `-- zImage
+    * bootcode.bin
+    * config.txt
+    * fixup.dat
+    * start.elf
+    * zImage
 
-Where should the binaries be copied on the SDCard
--------------------------------------------------
+For example:
 
-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.
+ $ cp output/images/rpi-firmware/* /mnt/mountpointboot
+ $ cp output/images/zImage /mnt/mountpointboot/zImage.img
 
-Boot partition
-~~~~~~~~~~~~~~
+Note: The default name is kernel.img.
+Actually, the name is zImage and it's define in the file config.txt like:
+kernel=zImage
 
-The first partition will contain everything used to boot the RaspberryPi.
-You must copy theses files at the root of partition:
+If you use a volatile rootfs, Skip to "Finish", below. For a persistent
+rootfs, there are further steps to do.
 
- * bootcode.bin
- * config.txt
- * fixup_cd.dat
- * fixup.dat
- * start_cd.elf
- * start.elf
- * zImage
+Extract (as root!) the contents of the rootfs.tar archive into the second
+partition you created above:
 
-So you should copy the entire content of output/images/rpi-firmware along with
-zImage.
+  $ 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.