[FE training-materials-updates] Update the new board labs with new rowboat instructions

[Maxime Ripard]

Repository : git://git.free-electrons.com/training-materials.git

On branch  : jelly-bean
Link       : http://git.free-electrons.com/training-materials/commit/?id=8c16ab91f885a5a8cdfbb7db9e12df91bbbec8f0

>---------------------------------------------------------------

commit 8c16ab91f885a5a8cdfbb7db9e12df91bbbec8f0
Author: Maxime Ripard <maxime.ripard at free-electrons.com>
Date:   Thu Aug 29 17:55:42 2013 +0200

    Update the new board labs with new rowboat instructions
    
    Signed-off-by: Maxime Ripard <maxime.ripard at free-electrons.com>


>---------------------------------------------------------------

8c16ab91f885a5a8cdfbb7db9e12df91bbbec8f0
 labs/android-new-board/android-new-board.tex |  267 +++++---------------------
 1 file changed, 51 insertions(+), 216 deletions(-)

diff --git a/labs/android-new-board/android-new-board.tex b/labs/android-new-board/android-new-board.tex
index 718431f..c5b45d9 100644
--- a/labs/android-new-board/android-new-board.tex
+++ b/labs/android-new-board/android-new-board.tex
@@ -8,109 +8,70 @@ After this lab, you will be able to:
   \item Generate a working build
 \end{itemize}
 
-\section{Setup}
-
-Go to the \code{$HOME/felabs/android/source} directory.
-
-Install packages needed for this lab:
-
-\begin{verbatim}
-sudo apt-get install bzr python-parted python-yaml \
-     u-boot-tools binfmt-support qemu-user-static debootstrap
-\end{verbatim}
-
-Install the \code{bzr}, \code{python-parted} and \code{python-yaml}
-packages.
-
 \section{Download the source code}
 
-Linaro has been working for some time now on a optimized Android
-distribution, available on at least one chip of most of the major ARM
-vendors. At each release, Linaro also maintains an Android flavored
-Linux kernel corresponding to the latest upstream Linux release.
+Go to the \code{$HOME/felabs/android/source} directory.
 
-One of the platforms supported by the Linaro's Android is the
-BeagleBoard, which is very similar to the DevKit8000 we use. In
-particular, both boards have the same OMAP3530 System-on-Chip.
-Moreover, the exact same kernel can be used to boot both boards.
-For these reasons, we will use this distribution as a
-starting point for the rest of the labs.
+We will use the TI-flavored Android build, named rowboat, for our
+board. This should make most of the port ready to use, and only a few
+fixes here and there will be needed.
 
 \code{repo} allows to download a new Android tree in a smart way,
 downloading only the differences between the new manifest we would
 give him and the current code we have. To do so, we first need to
-revert the patches we applied previously.
+change the manifest we use to the rowboat's one.
 
 \begin{verbatim}
-repo forall build frameworks/base -c "git reset --hard HEAD"
+repo init -u git://gitorious.org/rowboat/manifest.git \
+    -b master -m rowboat-jb-am335x.xml
 \end{verbatim}
 
-Then, we need to download the source code. We will use the Linaro
-Android 11.11 release, which is based on Android 2.3 Gingerbread and
-Linux 3.1.1
-\footnote{At the time of this writing, Linaro doesn't support Android
-  4.0 Ice Cream Sandwich or later on the Beagle board, and the port
-  from \href{http://code.google.com/p/rowboat} {Rowboat project}
-  doesn't seem to be fully stable either. We decided to stick with the
-  most stable version for our hardware.}.
-
+Now, let's run the big download job:
 \begin{verbatim}
-repo init \
- -u git://git.free-electrons.com/android/linaro/platform/manifest.git \
- -b linaro-android-11.11-release
+repo sync -c -j4
 \end{verbatim}
 
-Note that we're using a Free Electrons mirror of Linaro Android. This
-was needed as some git repositories that the Linaro Android 11.11 manifest
-specified disappeared or were moved. 
+\section{Build Android for the BeagleBone Black}
 
-Take a look at the \code{.repo/manifest.xml} file. You can see that
-Linaro took full advantage of the capabilities of the manifest file,
-using multiple git servers instead of a unique one, and replacing some
-of the components (like Dalvik and Bionic, for example) by its own
-optimized versions.
+As we said earlier, rowboat already includes support for the
+BeagleBone Black we're using. To compile it, we have to use lunch, in
+the same way we did previously:
 
-Now, let's run the big download job:
 \begin{verbatim}
-repo sync -c -j4
+source build/envsetup.sh
+lunch beagleboneblack-eng
 \end{verbatim}
 
-In the mean time, you should also download and extract the associated
-Linaro toolchain: \footnote{The real URL is
-  \url{http://free-electrons.com/labs/tools/android-toolchain-eabi-linaro-4.6-2011.11-4-2011-11-15_12-22-49-linux-x86.tar.xz},
-  corresponding to a toolchain no longer available on the Linaro
-  website. We wanted to give you something much shorter to type.}
+And finally, we can start the compilation:
+
 \begin{verbatim}
-cd ../linaro
-wget --trust-server-names http://j.mp/SJOCH8
-tar axf android-toolchain-*
+make OMAPES=4.x -jX
 \end{verbatim}
 
-In case this toolchain is removed from the Linaro website, you can also
-fetch it from \url{http://free-electrons.com/labs/tools/}.
-
-\section{Build Android for the BeagleBoard}
+Once again, you can expect this build job to take quite a long time (a
+few hours) to run, even on a recent and rather fast laptop.
 
-Get back to the \code{source} directory.
+This job will build four images in
+\code{out/target/product/beagleboneblack}: \code{cache.img},
+\code{ramdisk.img}, \code{system.img} and \code{userdata.img}.
 
-As we said earlier, the DevKit8000 is very similar to the BeagleBoard,
-so we will first compile a build for the BeagleBoard. The command to
-run is, after you have selected the beagleboard product using
-\code{lunch}:
+These images are the one usually generated by the Android build
+system. However, rowboat provides all the tools needed to flash an
+image to an SD card, but they do use a tarball containing the whole
+Android system.
 
-\code{make TARGET_TOOLS_PREFIX=~/felabs/android/linaro/android-toolchain-eabi/bin/arm-eabi- boottarball systemtarball userdatatarball -j8}
+To create such a tarball, you can use the following make target:
 
-Once again, you can expect this build job to take at least one hour to
-run, even on a recent and rather fast laptop.
+\begin{verbatim}
+make OMAPES=4.x fs_tarball
+\end{verbatim}
 
-This job will build three tarballs in
-\code{out/target/product/beagleboard}: \code{boot.tar.bz2},
-\code{system.tar.bz2}, \code{userdata.tar.bz2}, plus the images of
-Xloader, U-Boot, Linux kernel and its initramfs (which are also
-contained in \code{boot.tar.bz2}).
+It will generate in \code{out/target/product/beagleboneblack} a
+rootfs.tar.bz2 tarball holding all the files needed for Android to
+boot.
 
-We then need to put these images on an SD card so that we can boot on
-this system.
+We then need to put this image on an SD card so that we can boot on
+the system we just generated.
 
 First, take the SD card provided by your instructor, and insert it
 into an SD card reader slot in your workstation, or into a USB card
@@ -118,35 +79,31 @@ reader provided by your instructor too. Then, using the \code{dmesg}
 command, find which device your workstation uses for your SD card.
 Let's assume that this device is \code{/dev/sdc}.
 
-Now we can use a \code{linaro-android-media-create} script that Linaro
-developed, which takes the three tarballs and aggregates them to
-produce a ready-to-boot SD card.
+Rowboat comes with a script that will format the SD card with the
+geometry expected by the SoC to be able to boot it, with the correct
+partitions, and copy everything we compiled so that we end up with a
+ready-to-use SD card.
 
-You can install this script with the following commands:
+You can use this script with the following commands:
 
 \begin{verbatim}
-bzr branch lp:linaro-image-tools
-cd linaro-image-tools
-bzr revert -r2011.11
-cd ..
-sudo ./linaro-image-tools/linaro-android-media-create --mmc /dev/sdc \
-     --dev beagle --system out/target/product/beagleboard/system.tar.bz2 \
-     --userdata out/target/product/beagleboard/userdata.tar.bz2 \
-     --boot out/target/product/beagleboard/boot.tar.bz2
+sudo external/ti_android_utilities/am335x/mk-mmc/mkmmc-android.sh \
+    /dev/sdc u-boot/MLO u-boot/u-boot.img kernel/arch/arm/boot/uImage \
+    external/ti_android_utilities/am335x/u-boot-env/uEnv_beagleboneblack.txt \
+    out/target/product/beagleboneblack/rootfs.tar.bz2
 \end{verbatim}
 
 Once this command is over, you can remove the SD card and insert it
-into the corresponding slot on the DevKit8000 board.
+into the corresponding slot on the BeagleBone board.
 
 \section{Setting up serial communication with the board}
 
 To see the board boot, we need to read the first boot messages issued
 on the board's serial port.
 
-Your instructor will provide you with a special serial cable
-\footnote{This should be the same cable as for the Beagle and IGEPv2
-  boards} for the DevKit8000 board, together with a USB-to-serial
-adaptor for the connection with your laptop.
+Your instructor will provide you with a special serial cable for the
+Beaglebone, that is basically a USB-to-serial adapter for the
+connection with your laptop.
 
 When you plug in this adaptor, a serial port should appear on your
 workstation: \code{/dev/ttyUSB0}.
@@ -183,128 +140,6 @@ you wish to exit \code{picocom}, press \code{[Ctrl][a]} followed by
 Once you inserted the SD card, you can boot the board by holding the
 \code{boot} key while switching the board on. On the serial port, you
 should see Android going through its boot process, until you finally
-have a shell on the serial link.
-
-However, as you may have seen, the system boots, but you have no
-display at all. We are going to fix this.
-
-\section{Fix the blank screen}
-
-The first problem we see is that the display remains blank the whole
-time. This is because of the generated U-Boot being targeted for the
-BeagleBoard and not for the DevKit8000. In the Android build system,
-all the hardware related configuration is set in the file
-\code{BoardConfig.mk}. In the BeagleBoard product definition, find
-where the U-boot config file to use is set.
-
-Modify the \code{BoardConfig.mk} file to use the default U-boot
-configuration for the DevKit8000 board (\code{devkit8000_config}).
-
-To avoid rebuild errors, you should remove the directory where U-boot
-was built:
-
-\begin{verbatim}
-rm -r out/target/product/beagleboard/obj/u-boot
-\end{verbatim}
-
-Now, compile and test your changes.
-
-Don't be surprised if Android takes several minutes to boot. Android
-has some work to do the first time it's booted.
-
-You should now see the display working, while it has a major glitch:
-it prints only a portion of the screen.
-
-\section{Fix the resolution}
-
-The actual resolution is bigger than the screen size, which 
-is only 480x272. This kind of adjustment is mostly done
-through the kernel command line. On the SD card's \code{boot}
-partition, you will find a file named \code{boot.txt}, which is a
-U-Boot script setting all the parameters needed to boot the board
-properly, including the kernel command line.
-
-Change the \code{omapfb.mode} properties so that the board uses
-the LCD instead of the DVI output and configures the LCD with the 
-correct resolution.
-
-You can find some documentation for this option in the
-\code{kernel/Documentation/arm/OMAP/DSS} file, in the
-\code{Kernel boot arguments} section.
-
-You will then have to generate from this \code{boot.txt} file a
-\code{boot.scr} file using the following command:
-
-\code{mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n 'Execute uImage.bin' -d boot.txt boot.scr}
-\footnote{This command puts the \code{boot.txt} file contents into a
-  special container, allowing U-boot to know that the \code{boot.scr}
-  file is a script, and telling it how to handle this file. All the
-  files handled by U-boot should be put in such a container.}
- 
-Once this is done, test your changes by booting the board. You should
-see the display working correctly now.
-
-\section{Fix the touchscreen}
-
-If you test the touchscreen with the previous Android build you made,
-you should see that it is almost unusable, while the system receives
-some inputs. This mean that the kernel has the driver for the
-touchscreen controller, but it returns bogus values. If you pay
-attention however, you will find that the touchscreen doesn't have the
-same orientation as the display.
-
-Get back to the OMAP DSS documentation to find an option that might
-address this problem.
-
-\section{Bring it all together}
-
-These tweaks are not persistent because the \code{boot.scr} file is
-overwritten every time by the \code{linaro-android-media-create}
-script.
-
-However, the build system can help us here. Use the
-\code{BOARD_KERNEL_CMDLINE} variable to set these new values. It will
-be processed by the build system and then used when it generates the
-boot image. Since this variable is related to the hardware, this
-variable should be in \code{BoardConfig.mk}
-
-You can also add \code{no_console_suspend} to the bootargs as Android
-by default suspends the shell on the serial line after a minute or so,
-making it pretty hard to use it properly.
-
-\section{Add the Buttons}
-
-If you happen to launch an application, you will find that you cannot
-get back to the home screen, as no button is mapped to the \code{back}
-and \code{home} keys.
-
-Button mapping is done in two steps. First, in the kernel, the board
-should define the available buttons. In this case, we will use the
-small black buttons right next to the screen on the DevKit8000. These
-buttons are handled by the \code{gpio-keys} driver, and defined in the
-devkit8000 board file in the kernel, in the \code{arch/arm/mach-omap2}
-folder.
-
-If you look into that file, you will see that only one button is
-defined, the one corresponding to the button labeled \code{user key}
-on the board.
-
-We will map this button to the \code{back} key in Android. In the
-\code{gpio_keys_button} structure, there is a \code{code} field. The
-value of this field defines the keycode sent to the input subsystem
-when you press that button, and will be later dispatched to the
-userspace. Replace the keycode used by \code{KEY_EXIT} and look up its
-value in the \code{include/linux/input.h} file.
-
-The Android input system loads keymaps and key layouts for each loaded
-input driver. To load these properly, it uses the same name as the
-input driver, with an extension. In our case, the input driver being
-\code{gpio-keys}, we will need to modify the \code{gpio-keys.kl} file.
-
-This file consists of a list of entries, corresponding to what actions
-every keycode should trigger in the system. Add a new entry to this
-file for the back button, which should be like:
-\code{key <keycode> BACK}
+have a shell on the serial link and the screen working properly.
 
-Once you're done, rebuild the system, boot it, and you should be able
-to use the \code{back} key now!
+\section{TODO: Fix the screen resolution}
\ No newline at end of file