# [FE training-materials-updates] Misc style improvements

michael.opdenacker at free-electrons.com michael.opdenacker at free-electrons.com
Tue Jun 5 17:20:56 CEST 2012

- Log -----------------------------------------------------------------
http://git.free-electrons.com/training-materials/commit/?id=249074476c73bbe238971d70da98d4597f3c3af9

commit 249074476c73bbe238971d70da98d4597f3c3af9
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Tue Jun 5 17:21:33 2012 +0200

Misc style improvements

index 847968a..9663448 100644
@@ -52,7 +52,7 @@ OHCI\footnote{USB Open Host Controller Interface, supporting only USB 1.1}
support to use the missile launcher.

Once you're done, exit and the configuration tool will save the new
-file as \code{.config}. You can save it to a defconfig file by
+file as \code{.config}. You can save it to a \code{defconfig} file by
running \code{ARCH=arm make savedefconfig}. Then, copy the newly created
\code{defconfig} file to the \code{arch/arm/configs} directory with
the \code{android_devkit8000_defconfig} name.
@@ -97,7 +97,7 @@ Now try to save all logs from Dalvik to a file using only \code{adb}.
\section{Get a shell on the device}

Having a shell on the device can prove pretty useful. ADB provides such a feature,
-even though the Android-embedded shell is quite minimal. To access this shell,
+even though this embedded shell is quite minimal. To access this shell,

You can also run a command directly on the device thanks to \code{adb shell}. To do
@@ -106,6 +106,6 @@ filesystems on the device.

\section{Push/Pull files to a device}

-In the same way, ADB allows you to retrieve files from and send them to the
-connected device, using the \code{push} and \code{pull} commands.
+In the same way, ADB allows you to retrieve files from the connected device and send them
+to it, using the \code{push} and \code{pull} commands.

diff --git a/labs/android-application/android-application.tex b/labs/android-application/android-application.tex
--- a/labs/android-application/android-application.tex
+++ b/labs/android-application/android-application.tex
@@ -1,5 +1,5 @@
\subchapter{Write an application with the SDK}{Learn the basic concepts of
-Android SDK and how to use them}
+the Android SDK and how to use them}

After this lab, you will be able to:
\begin{itemize}
@@ -19,7 +19,7 @@ hooks implement the behavior of every button: move the
launcher, fire, etc.  Every button should be self-explanatory, except
for the USB/Emulation switch, which switches between USB mode (which
uses the USBBackend you developed) and Emulation mode (which uses the
-DummyBackend for debug).
+\code{DummyBackend} class for debugging).

The whole application now uses 3 layers to work, the application itself, which
is a perfectly standard Android application, relying on Java $\rightarrow$ C
diff --git a/labs/android-jni-library/android-jni-library.tex b/labs/android-jni-library/android-jni-library.tex
index ee43f56..035d437 100644
--- a/labs/android-jni-library/android-jni-library.tex
+++ b/labs/android-jni-library/android-jni-library.tex
@@ -50,7 +50,7 @@ will have to provide both the classpath and the class name to make it work.

You will find that the binary we developed in the previous lab and
the bindings share a lot of common code. This is not very convenient
-to solve bugs affecting this area of the code, since we have to make
+to solve bugs impacting this area of the code, since we have to make
the fix at two different places.

If you have some time left at the end of this lab, use it to make this
diff --git a/labs/android-native-app/android-native-app.tex b/labs/android-native-app/android-native-app.tex
index e399413..5a73517 100644
--- a/labs/android-native-app/android-native-app.tex
+++ b/labs/android-native-app/android-native-app.tex
@@ -44,6 +44,6 @@ application. You should see the launcher move.

However, when you start your tests, you will find that \code{libusb} cannot open
the usb devices because of restricted permissions. This can be fixed
-through \code{ueventd.rc} files. Add a device-specific uevend
+through \code{ueventd.rc} files. Add a device-specific \code{ueventd}
configuration file to your build to make the files under
diff --git a/labs/android-native-library/android-native-library.tex b/labs/android-native-library/android-native-library.tex
index 6e067e4..a8d5ab7 100644
--- a/labs/android-native-library/android-native-library.tex
+++ b/labs/android-native-library/android-native-library.tex
@@ -24,11 +24,11 @@ by yourself.
If successful, the build system should go through the build process and you
should have a directory generated in the \code{out} directory.

-\section{Bulding a shared library}
+\section{Building a shared library}

Now, we will need to build a shared library along with the static one, called
\code{libusb.so}. Use the same \code{config.h} and modify the \code{Android.mk}
-file so that it get compiled. Then, check that the shared object is present in
+file so that it gets compiled. Then, check that the shared object is present in
the \code{out} folder.

\section{Integrate the library into the Android image}
diff --git a/labs/android-system-customization/android-system-customization.tex b/labs/android-system-customization/android-system-customization.tex
index cba50a0..7ace995 100644
--- a/labs/android-system-customization/android-system-customization.tex
+++ b/labs/android-system-customization/android-system-customization.tex
@@ -2,17 +2,17 @@

After this lab, you will be able to:
\begin{itemize}
-  \item Use the products configuration system
+  \item Use the product configuration system
\item Change the default wallpaper
\item Add extra properties to the system
-  \item Use the products overlays
+  \item Use the product overlays
\end{itemize}

\section{Setup a new product}

Revert the changes you made to the beagleboard product and define a new product
named \textit{training} instead. This product will have all the attributes of
-the beagleboard product for now, plus the extra packages we'll add along the
+the beagleboard product for now, plus the extra packages we will add along the
labs.

As we are still using the same platform, the product name returned by the
@@ -41,4 +41,4 @@ As we have seen, properties are extensively used around the Android system.
Extend the \code{system.prop} file of the \textit{training} product by adding a
\code{foo.bar} property.

-Boot the system and use getprop to check if the property has indeed been added.
+Boot the system and use \code{getprop} to check that the property has indeed been added.

http://git.free-electrons.com/training-materials/commit/?id=d37ab4f5a62c361e61c00f39d0c1c003be2bafd5

commit d37ab4f5a62c361e61c00f39d0c1c003be2bafd5
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Tue Jun 5 16:49:17 2012 +0200

index ac8fd5d..847968a 100644
@@ -8,33 +8,48 @@ After this lab, you will be able to use ADB to:
\item Install new applications
\end{itemize}

+\section{Setup}
+
+Stay in the the \code{/home/<user>/felabs/android/linaro} directory.
+

ADB is distributed by Google as part of their SDK for Android. First,
you need to go to
-\url{http://developer.android.com/sdk/index.html}. Get the SDK for
-Linux, and follow the instructions to install it.
+\url{http://developer.android.com/sdk/}. Get the SDK for

-Once the SDK is installed, launch the \code{android} binary, go to the
-\code{Available Packages} tabs, select \code{Android SDK Platform-tools} and
-click on the \code{Install Selected} button. Once you are done, you have \code{adb} on
+Now, run the \code{tools/android} script, and in the \code{Packages}
+window, select \code{Android SDK Platform-tools} under \code{Tools},
+unselect all the other packages, and click on the \code{Install 1 package...} button.

However, the Android source code also has an embedded SDK, so you
-should also have the \code{adb} binary in \code{out/host/linux-x86/bin/}
+
+during the previous lab, you can go through the same environment setup steps
+as earlier:
+
+\begin{verbatim}
+source build/envsetup.sh
+lunch
+\end{verbatim}
+
+... and choose \code{beagleboard-eng} in the \code{lunch} menu.

\section{Disable USB suspend}

The kernel we have built uses USB suspend to save power. This will
-prove painful during the next labs, beginning with this one.
+be painful during the next labs, starting with this one.

To do so, go to the \code{kernel} directory. First, use the
\code{android_omap3_defconfig} file as an initial configuration. Load it using
\code{ARCH=arm make android_omap3_defconfig} and then modify it using
\code{ARCH=arm make menuconfig} to disable \code{CONFIG_USB_SUSPEND}
and enable \code{CONFIG_USB_OTG_WAKELOCK}. We will also need to enable
-OHCI support to use the missile launcher.
+OHCI\footnote{USB Open Host Controller Interface, supporting only USB 1.1}
+support to use the missile launcher.

Once you're done, exit and the configuration tool will save the new
file as \code{.config}. You can save it to a defconfig file by
diff --git a/labs/android-new-board/android-new-board.tex b/labs/android-new-board/android-new-board.tex
index df2daab..7e44fd1 100644
--- a/labs/android-new-board/android-new-board.tex
+++ b/labs/android-new-board/android-new-board.tex
@@ -194,19 +194,19 @@ 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 documentation of the DSS to find an option that might address
+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 generated at run
-time by the \code{linaro-android-media-create} tool. To automate this, modify it to add
-a devkit8000'' target device with the proper command line for the kernel.
+time by the \code{linaro-android-media-create} script. To automate this, modify this
+script to add a devkit8000'' target device with the right kernel command line.

To do so, you will need to edit the files
\code{linaro_image_tools/media_create/boards.py} and
\code{linaro_image_tools/media_create/android_boards.py} to add \code{class} entries in each
-file to specify the correct boot command for your board. It should not take more than 10 lines to
+file to specify the right boot command for your board. It should not take more than 10 lines to

You can also add \code{no_console_suspend} to the bootargs as Android by
@@ -216,11 +216,11 @@ hard to use it properly.

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 \code{back} or \code{home}
+get back to the home screen, as no button is mapped to the \code{back} and \code{home}
keys.

-The button mapping is done in two steps. First, in the kernel, the
-board should define the buttons available. In this case, we will use
+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.
@@ -229,22 +229,22 @@ 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 back key in Android. In the
+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 keylayouts for each input
-driver loaded. To load it properly, it uses the same name than the
+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 in a list of entries, corresponding to what actions
+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}

Once you're done, rebuild the system, boot it, and you should be able
-to use the back key now!
+to use the \code{back} key now!

http://git.free-electrons.com/training-materials/commit/?id=d9891b60d5776320df529053c412690a5dbf588d

commit d9891b60d5776320df529053c412690a5dbf588d
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Tue Jun 5 15:56:14 2012 +0200

diff --git a/labs/android-new-board/android-new-board.tex b/labs/android-new-board/android-new-board.tex
index f143305..df2daab 100644
--- a/labs/android-new-board/android-new-board.tex
+++ b/labs/android-new-board/android-new-board.tex
@@ -105,7 +105,7 @@ sudo ./linaro-image-tools/linaro-android-media-create --mmc /dev/sdc \
\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 DevKit8000 board.

\section{Setting up serial communication with the board}

@@ -114,7 +114,7 @@ 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
+for the DevKit8000 board, together with a USB-to-serial adaptor for the connection

When you plug in this adaptor, a serial port should appear on your workstation:
@@ -165,21 +165,24 @@ You can avoid doing a full rebuild by removing the
\section{Fix the resolution}

The actual resolution is set to 640x480 on the screen, while its resolution is
-only 480x272. This kind of adjustments are mostly done through the kernel
-command line. On the SD card's boot partition, you will find a file named
-\code{boot.txt} which is a U-Boot's script setting all the needed parameters for the
-board to boot properly, including the kernel command line. Change the
+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{omapdss.def_disp} and \code{omapfb.mode} properties so that it uses the LCD instead of
-the DVI output and at the correct resolution.
+the DVI output and the correct resolution.

-You can find some documentation for these options in the file
-\code{kernel/Documentation/arm/OMAP/DSS}, in the Kernel boot arguments section.
+You can find some documentation for these options 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.

http://git.free-electrons.com/training-materials/commit/?id=161719a215ff5c83029194fd86b22acbd4ea25f7

commit 161719a215ff5c83029194fd86b22acbd4ea25f7
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Tue Jun 5 15:46:45 2012 +0200

diff --git a/labs/android-new-board/android-new-board.tex b/labs/android-new-board/android-new-board.tex
index 9d5070d..f143305 100644
--- a/labs/android-new-board/android-new-board.tex
+++ b/labs/android-new-board/android-new-board.tex
@@ -76,7 +76,10 @@ will first compile a build for the BeagleBoard. The command to run is:

\code{make TARGET_PRODUCT=beagleboard TARGET_TOOLS_PREFIX=~/felabs/android/linaro/android-toolchain-eabi/bin/arm-eabi- boottarball systemtarball userdatatarball -j8}

-This will build three tarballs in \code{out/target/product/beagleboard}:
+Once again, you can expect this build job to take at least one hour to run,
+even on a recent and rather fast laptop.
+
+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}).

http://git.free-electrons.com/training-materials/commit/?id=2ea4738c3ed2344a3e6a558534d7cbe89c4de791

commit 2ea4738c3ed2344a3e6a558534d7cbe89c4de791
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Tue Jun 5 15:43:56 2012 +0200

Add a look at Linaro's manifest file

diff --git a/labs/android-new-board/android-new-board.tex b/labs/android-new-board/android-new-board.tex
index 5ce7237..9d5070d 100644
--- a/labs/android-new-board/android-new-board.tex
+++ b/labs/android-new-board/android-new-board.tex
@@ -40,10 +40,24 @@ mkdir src
cd src
repo init -u git://android.git.linaro.org/platform/manifest.git \
-b linaro-android-11.11-release
+\end{verbatim}
+
+Take a look at the \code{.repo/manifest.xml} file and compare it with
+the one in \code{~/felabs/android/aosp/android/}. 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.
+
+\begin{verbatim}
repo sync -j4
\end{verbatim}

-You will also need to download and extract the associated Linaro toolchain:
+Once again, even with a fast Internet connection, the \code{repo sync} command can
+take more than one hour. Your instructor will keep you busy with other things
+
+In the mean time, you should also download and extract the associated Linaro toolchain:
\footnote{The original URL is
\url{http://android-build.linaro.org/builds/~linaro-android/toolchain-4.6-2011.11/4/android-toolchain-eabi-linaro-4.6-2011.11-4-2011-11-15_12-22-49-linux-x86.tar.bz2}. We wanted to give you something much shorter
to type.}

http://git.free-electrons.com/training-materials/commit/?id=0db51fe39fc04d1252612daccd027a508f85d5e7

commit 0db51fe39fc04d1252612daccd027a508f85d5e7
Author: Michael Opdenacker <michael.opdenacker at free-electrons.com>
Date:   Tue Jun 5 15:31:40 2012 +0200

Explain how to identify the SD card device

diff --git a/labs/android-new-board/android-new-board.tex b/labs/android-new-board/android-new-board.tex
index 6766d14..5ce7237 100644
--- a/labs/android-new-board/android-new-board.tex
+++ b/labs/android-new-board/android-new-board.tex
@@ -68,9 +68,16 @@ U-Boot, Linux kernel and its initramfs (which are also contained in
\code{boot.tar.bz2}).

We then need to put these images on an SD card so that we can boot on this system.
-Linaro developed a script that takes the three tarballs and aggregates
-them to produce a ready-to-boot SD card. You can install it with the following
-commands:
+
+First, take the SD card provided by your instructor, and insert it into an SD card reader slot
+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.
+
+You can install this script with the following commands:

\begin{verbatim}
bzr branch lp:linaro-image-tools

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

Summary of changes: