Labs

Android Training

Lab Book

Free Electronshttp://free-electrons.com

December 13, 2012

http://free-electrons.com

Free Electrons Android Training

About this document

This document can be found on http://free-electrons.com/doc/training/android/.

It was generated from LaTeX sources found on http://git.free-electrons.com/training-materials.

More details about our training sessions can be found on http://free-electrons.com/training.

Copying this document

c© 2004-2012, Free Electrons, http://free-electrons.com.

This document is released under the terms of the Creative Commons CC BY-SA3.0 license . This means that you are free to download, distribute and even modifyit, under certain conditions.

Corrections, suggestions, contributions and translations are welcome!

2 c© 2004-2012 Free Electrons, CC BY-SA license

http://free-electrons.com/doc/training/android/

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

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

http://free-electrons.com/training

http://free-electrons.com/training


http://creativecommons.org/licenses/by-sa/3.0/

http://creativecommons.org/licenses/by-sa/3.0/



Training setupDownload files and directories used in practical labs

Install lab data

For the different labs in the training, your instructor has prepared a set of data (kernel images,kernel configurations, root filesystems and more). Download and extract its tarball from aterminal:

cdsudo apt-get install xz-utilswget http://free-electrons.com/labs/labs.tar.xzsudo tar Jxf labs.tar.xzsudo chown -R <user>.<user> felabs

Note that using root permissions are required to extract the character and block device filescontained in this lab archive. This is an exception. For all the other archives that you willhandle during the practical labs, you will never need root permissions to extract them. Ifthere is another exception, we will let you know.

Lab data are now available in an felabs directory in your home directory. For each lab thereis a directory containing various data. This directory will also be used as working space foreach lab, so that the files that you produce during each lab are kept separate.

You are now ready to start the real practical labs!

Install extra packages

Ubuntu comes with a very limited version of the vi editor. Install vim, a improved version ofthis editor.

sudo apt-get install vim

More guidelines

Can be useful throughout any of the labs

• Read instructions and tips carefully. Lots of people make mistakes or waste time becausethey missed an explanation or a guideline.

• Always read error messages carefully, in particular the first one which is issued. Somepeople stumble on very simple errors just because they specified a wrong file path anddidn’t pay enough attention to the corresponding error message.

• Never stay stuck with a strange problem more than 5 minutes. Show your problem toyour colleagues or to the instructor.

• You should only use the root user for operations that require super-user privileges, suchas: mounting a file system, loading a kernel module, changing file ownership, configur-

c© 2004-2012 Free Electrons, CC BY-SA license 3



ing the network. Most regular tasks (such as downloading, extracting sources, compil-ing...) can be done as a regular user.

• If you ran commands from a root shell by mistake, your regular user may no longerbe able to handle the corresponding generated files. In this case, use the chown -Rcommand to give the new files back to your regular user.Example: chown -R myuser.myuser linux-3.4




Android source codeDownload the source code for Android and all its components

During this labs, you will:

• Install all the development packages needed to fetch and compile Android

• Download the repo utility

• Use repo to download the source code for Android and for all its components

Setup

Go to the /home/<user>/felabs/android/aosp directory.

Install needed packages

Install the packages needed to fetch Android’s source code:

sudo apt-get install git-core curl

Fetch the source code

Android sources are made of many separate Git repositories, each containing a piece of soft-ware needed for the whole stack. This organization adds a lot of flexibility, allowing to easilyadd or remove a particular piece from the source tree, but also introduces a lot of overhead tomanage all these repos.

To address this issue, Google created a tool called Repo. As Repo is just a python script, it hasnot made its way in the Ubuntu packages, and we need to download it from Google.

mkdir $HOME/binexport PATH=$HOME/bin:$PATHcurl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > \

$HOME/bin/repochmod a+x $HOME/bin/repo

We can now fetch the Android source code:

mkdir androidcd androidrepo init -u https://android.googlesource.com/platform/manifest \

-b android-2.3.7_r1repo sync

repo sync will synchronize the files for all the source repositories listed in the manifest. Ifyou have a slow connection to the Internet, this could even take a few hours to complete. For-tunately, your instructor will take advantage of this waiting time to continue with the lectures.

However, a lot of time is used to process the files downloaded by git, wasting a lot of band-width usage time. You can speed up the download using the -jX option for repo sync, X




being the number of parallel downloads. We will use 2 because we all share the same internetconnection, but you can definitely increase this number up to 8 at home.

If this really takes too much time, your instructor may distribute a ready-made archive con-taining what repo sync would have downloaded.

To save time, do not wait for the repo sync command to complete. You can already jump tothe next section.

Install packages needed at compile time

While repo sync runs, download the packages that you will need to compile Android andits components from source:

sudo apt-get install xsltproc gnupg flex bison gperf build-essential \zip zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs \x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev \libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown \libxml2-utils xsltproc openjdk-6-jdk

sudo apt-get clean

Again, if you have a slow connection to the Internet, installing these packages could take sev-eral tens of minutes. Anyway, we are getting back to the lectures.




First compilationGet used to the build mechanism

During this lab, you will:

• Configure which system to build Android for

• Compile your first Android root filesystem

Setup

Stay in the /home/<user>/felabs/android/aosp/android directory.

Build environment

Now that repo sync is over, we will compile an Android system for the emulator. This willinclude building the emulator itself.

First, run source build/envsetup.sh.

This file contains many useful shell functions and aliases, such as croot to go to the rootdirectory of the Android source code or lunch, to select the build options.

Check your PATH environment variable:

echo $PATH

You will see that build/envsetup.sh hasn’t modified your PATH. This will be done duringthe build job.

The target product for the emulator is generic, and we want to have an engineering build. Todo this, run lunch generic-eng

Compile the root filesystem

The build system will use the proper setup to build this target. Before running make, first checkthe number of CPU cores in your workstation, as seen by the operating system (hyperthreadingcould make your OS see 4 cores instead of 2, for example).

cat /proc/cpuinfo

You can use make -j (j stands for jobs to instruct make to run multiple compile jobs in parallel,taking advantage of the multiple CPU cores, and making sure that I/Os and CPU cores arealways at 100%. This will significantly reduce build time.

For example, if Linux sees 4 cores, you will get good performance by specifying the doublenumber of parallel jobs:

make -j 8

Go grab (several cups of) coffee!




Known issue In rare circumstances, some builds can fail when make is run with multiplejobs in parallel. If this happens, you can run make with no option after the failure, and this islikely to make the issue disappear.

Test your Android build

Now, look at the PATH environment variable again.

You can see that it contains:

• $HOME/felabs/android/aosp/android/out/host/linux-x86/bin/. That’s wherenew utilities have just been compiled.

• Prebuilt executables, in particular the ARM cross-compiling toolchain, which was alreadypresent in the repositories fetched by repo.

Look at the contents of the out/target/product/generic folder. That’s where the systemimages have been built.

Run the emulator command. It will run the emulator with these generated images. Waita few minutes for the emulator to load the system, and then check the build number in theSettings application in Android.

Note The PATH settings automatically added by the build process will be lost if you closeyour terminal. We will see how to restore this environment in the next lab.




Compile and boot an Android Ker-nelLearn how to build an Android Kernel and test it

After this lab, you will be able to:

• Extract the kernel patchset from Android Kernel

• Apply it on a vanilla kernel

• Compile and boot a kernel for the emulator

Setup

Go to the /home/<user>/felabs/android/kernel directory.

Compile a kernel for the Android emulator

The Android emulator uses QEMU to create a virtual ARM9 SoC called Goldfish.

In the standard Android source code we fetched, the kernel source was not included. So thefirst thing to do is download the Android kernel sources.

git clone https://android.googlesource.com/kernel/goldfish.git kernel

Go to the kernel directory. That’s where the kernel source repository was cloned.

Using git branch -a, find the name of the most recent stable kernel version that supportsthe Goldfish platform. At the time of this writing, Linux 3.0 and 3.4 still don’t seem to workwith the emulator, and you will have to choose the 2.6.29 kernel.

Switch to this branch as follows:

git checkout <branch>.

Now that we have kernel sources, we now need a toolchain to compile the kernel. Fortunately,Android provides one. First, add the toolchain from the previous lab to your PATH.

PATH=$HOME/felabs/android/aosp/android/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin:$PATH

Now, configure the kernel for the target platform

ARCH=arm make goldfish_defconfig

Then, configure the kernel using the tool of your choice to add a custom suffix to the kernelversion and compile the kernel!

ARCH=arm CROSS_COMPILE=arm-eabi- make -j 4

A few minutes later, you have a kernel image in arch/arm/boot.




Boot your new kernel

To run the emulator again, this time with your new kernel image, you have to restore theenvironment that you had after building Android from sources. This is needed every time youreboot your workstation, and every time you work with a new terminal.

Go back to $HOME/felabs/android/aosp/android/.

All you need to do is source the environment and run the lunch command to specify whichproduct you’re working with 1:

source build/envsetup.shlunch generic-eng

Now, test that you can still run the emulator as you did in the previous lab.

To run the emulator with your own kernel, you can use the -kernel option:

emulator -kernel $HOME/felabs/android/kernel/kernel/arch/arm/boot/zImage

Once again, check the kernel version in the Android settings. Make sure that the kernel wasbuilt today.

Generate a patchset from the Android Kernel

To compare the Android kernel sources with the official kernel ones, we need to fetch the lattersources too, allowing us to see which commits differ. Git is great for that and offers everythingwe need.

First, add the linux-stable repository from Greg Kroah-Hartmann to our repository:

git remote add stable git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git

Now, we need to fetch the changes from this remote repository:

git fetch stable

A while later, you should have all the changes in your own repository, browsable offline!

Now, open the main Makefile with your favorite editor and get the kernel version that is init. Now that we have it, we can generate the whole set of commits that differ from the linuxkernel by doing:

git log v<kernel-version>..HEAD

Now, extract the corresponding set of patches2:

git format-patch v<kernel-version>..HEAD

In this set of patches, find the one that adds the wakelocks.

Congratuations! You now have all the patches to apply to a vanilla kernel version to obtain afull Android kernel.

In this lab, we showed useful Git commands, but didn’t go into details, as this is not a Gitcourse. Don’t hesitate to ask your instructor for more details about Git.

1Remember that Android sources allow you to work with multiple products2Git generates one patch per commit.




Supporting a new boardLearn how to make Android on new hardware


• Boot Android on a real hardware

• Troubleshoot simple problems on Android

• Generate a working build

Setup

Go to the /home/<user>/felabs/android/linaro directory.

Install the bzr, python-argparse, python-parted and python-yaml packages.

Download the source code

Linaro has been working for some time now on a optimized Android distribution, available onat least one chip of most of the major ARM vendors. At each release, Linaro also maintains anAndroid flavored Linux kernel corresponding to the latest upstream Linux release.

One of the platforms supported by the Linaro’s Android is the BeagleBoard, which is verysimilar to the DevKit8000 we use. In particular, both boards have the same OMAP3530 System-on-Chip. Moreover, in the last kernel versions, the kernel needed for both of these boards havebeen unified, so we can boot the exact same kernel on both boards. For these reasons, we willuse this distribution as a starting point for the rest of the labs.

First, we need to download the source code. We will use the 11.11 release, which is based onAndroid 2.3 Gingerbread and Linux 3.1.1 3.

mkdir srccd srcrepo init -u git://git.free-electrons.com/android/linaro/platform/manifest.git \

-b linaro-android-11.11-release

Take a look at the .repo/manifest.xml file and compare it with the one in $HOME/felabs/android/aosp/android/. You can see that Linaro took full advantage of the capabilities ofthe manifest file, using multiple git servers instead of a unique one, and replacing some of thecomponents (like Dalvik and Bionic, for example) by its own optimized versions.

Now, let’s run the big download job:

repo sync -j4

Once again, even with a fast Internet connection, the repo sync command can take morethan one hour. Your instructor will keep you busy with other things during these downloads.

3At 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 Rowboat project doesn’t seem to be fully stable either. We decided to stick with the most stableversion for our hardware.


http://code.google.com/p/rowboat



In the mean time, you should also download and extract the associated Linaro toolchain: 4

cd ..wget --trust-server-names http://goo.gl/Wn4dMtar jxf android-toolchain-eabi-linaro-4.6-2011.11-4-2011-11-15_12-22-49-linux-x86.tar.bz2

Build Android for the BeagleBoard

Get back to the src directory.

As we said earlier, the DevKit8000 is very similar to the BeagleBoard, so we will first compilea build for the BeagleBoard. The command to run is:

make TARGET_PRODUCT=beagleboard TARGET_TOOLS_PREFIX=˜/felabs/android/linaro/android-toolchain-eabi/bin/arm-eabi- boottarball systemtarball userdatatarball-j8

Once again, you can expect this build job to take at least one hour to run, even on a recent andrather fast laptop.

This job will build three tarballs in out/target/product/beagleboard: boot.tar.bz2,system.tar.bz2, userdata.tar.bz2, plus the images of Xloader, U-Boot, Linux kerneland its initramfs (which are also contained in boot.tar.bz2).

We then need to put these images on an SD card so that we can boot on this system.

First, take the SD card provided by your instructor, and insert it into an SD card reader slotin your workstation, or into a USB card reader provided by your instructor too. Then, usingthe dmesg command, find which device your workstation uses for your SD card. Let’s assumethat this device is /dev/sdc.

Now we can use a linaro-android-media-create script that Linaro developed, whichtakes the three tarballs and aggregates them to produce a ready-to-boot SD card.

You can install this script with the following commands:

bzr branch lp:linaro-image-toolsbzr revert -r2011.11sudo ./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

Once this command is over, you can remove the SD card and insert it into the correspondingslot on the DevKit8000 board.

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 5 for the DevKit8000 board, togetherwith a USB-to-serial adaptor for the connection with your laptop.

4The original URL is 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.

5This should be the same cable as for the Beagle and IGEPv2 boards


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





When you plug in this adaptor, a serial port should appear on your workstation: /dev/ttyUSB0.

You can also see this device appear by looking at the output of the dmesg command.

To communicate with the board through the serial port, install a serial communication pro-gram, such as picocom: 6

sudo apt-get install picocom

Run picocom -b 115200 /dev/ttyUSB0, to start serial communication on /dev/ttyUSB0,with a baudrate of 115200. If you wish to exit picocom, press [Ctrl][a] followed by [Ctrl][x].

Booting the board

Once you inserted the SD card, you can boot the board by holding the boot key while switch-ing 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 goingto fix this.

Fix the blank screen

The first problem we see is that the display remains blank the whole time. This is because ofthe generated U-Boot being targeted for the BeagleBoard and not for the DevKit8000. In theAndroid build system, all the hardware related configuration is set in the file BoardConfig.mk. In the BeagleBoard product definition, find where the U-boot config file to use is set andchange this configuration to use the default configuration for the DevKit8000 (devkit8000_config).

Compile and test your changes. You should now see the display working, while it has a majorglitch: it prints only a portion of the screen.

You can avoid doing a full rebuild by removing the out/target/product/beagleboard/obj/u-boot directory.

Fix the resolution

The actual resolution is set to 640x480 on the screen, while its resolution is only 480x272. Thiskind of adjustment is mostly done through the kernel command line. On the SD card’s bootpartition, you will find a file named boot.txt, which is a U-Boot script setting all the pa-rameters needed to boot the board properly, including the kernel command line. Add theomapdss.def_disp and change the omapfb.mode properties so that it uses the LCD insteadof the DVI output and the correct resolution.

You can find some documentation for these options in the kernel/Documentation/arm/OMAP/DSS file, in the Kernel boot arguments section.

You will then have to generate from this boot.txt file a boot.scr file using the followingcommand:

6picocom is one of the simplest utilities to access a serial console. minicom looks more featureful, but is also morecomplex to configure.




mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n ’Execute uImage.bin’ -d boot.txt boot.scr 7

Once this is done, test your changes by booting the board. You should see the display workingcorrectly now.

Fix the touchscreen

If you test the touchscreen with the previous Android build you made, you should see that itis almost unusable, while the system receives some inputs. This mean that the kernel has thedriver 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.

Bring it all together

These tweaks are not persistent because the boot.scr file is overwritten every time by thelinaro-android-media-create script.

However, the build system can help us here. Use the BOARD_KERNEL_CMDLINE variable toset these new value. It will be processed by the build system and then used when it gener-ates the boot image. Since this variable is related to the hardware, this variable should be inBoardConfig.mk

You can also add no_console_suspend to the bootargs as Android by default suspends theshell on the serial line after a minute or so, making it pretty hard to use it properly.

Add the Buttons

If you happen to launch an application, you will find that you cannot get back to the homescreen, as no button is mapped to the back and home keys.

Button mapping is done in two steps. First, in the kernel, the board should define the availablebuttons. In this case, we will use the small black buttons right next to the screen on the De-vKit8000. These buttons are handled by the gpio-keys driver, and defined in the devkit8000board file in the kernel, in the arch/arm/mach-omap2 folder.

If you look into that file, you will see that only one button is defined, the one corresponding tothe button labeled user key on the board.

We will map this button to the back key in Android. In the gpio_keys_button structure,there is a code field. The value of this field defines the keycode sent to the input subsystemwhen you press that button, and will be later dispatched to the userspace. Replace the keycodeused by KEY_EXIT and look up its value in the include/linux/input.h file.

The Android input system loads keymaps and key layouts for each loaded input driver. Toload these properly, it uses the same name as the input driver, with an extension. In our case,the input driver being gpio-keys, we will need to modify the gpio-keys.kl file.

This file consists of a list of entries, corresponding to what actions every keycode should triggerin the system. Add a new entry to this file for the back button, which should be like: key<keycode> BACK

7This command puts the boot.txt file contents into a special container, allowing U-boot to know that the 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 acontainer.




Once you’re done, rebuild the system, boot it, and you should be able to use the back keynow!




Use ADBLearn to use the Android Debug Bridge

After this lab, you will be able to use ADB to:

• Debug your system and applications

• Get a shell on a device

• Exchange files with a device

• Install new applications

Setup

Stay in the the /home/<user>/felabs/android/linaro directory.

Get ADB

ADB is usually distributed by Google as part of their SDK for Android.

If you were willing to use it, you would first need to go to http://developer.android.com/sdk/ to get the SDK for Linux, and extract the archive that you downloaded.

Then, you would run the tools/android script, and in the Packageswindow, select AndroidSDK Platform-tools under Tools, unselect all the other packages, and click on the Install1 package... button. Once done, you would have adb installed in ./platform-tools/adb.

However, the Android source code also has an embedded SDK, so you already have the adbbinary in the out/host/linux-x86/bin/.

To add this directory to your PATH after the Linaro build during the previous lab, you can gothrough the same environment setup steps as earlier:

source build/envsetup.shlunch

... and choose beagleboard-eng in the lunch menu.

Disable USB suspend

The kernel we have built uses USB suspend to save power. This will be painful during the nextlabs, starting with this one.

To do so, go to the kernel directory. First, use the android_omap3_defconfig file as aninitial configuration. Load it using ARCH=arm make android_omap3_defconfig and thenmodify it using ARCH=arm make menuconfig to disable CONFIG_USB_SUSPEND and en-able CONFIG_USB_OTG_WAKELOCK. We will also need to enable OHCI8 support (USB_OHCI_HCD_OMAP3) to use the missile launcher.

8USB Open Host Controller Interface, supporting only USB 1.1


http://developer.android.com/sdk/

http://developer.android.com/sdk/



Once you’re done, exit and the configuration tool will save the new file as .config. Youcan save it to a defconfig file by running ARCH=arm make savedefconfig. Then, copythe newly created defconfig file to the arch/arm/configs directory with the android_devkit8000_defconfig name.

Once this is done, change the BeagleBoard product definition so that it uses this new file.

Configure USB access on your machine

If you execute any command right now, you are very likely to have a permission denied error.This is because the USB device associated to the DevKit8000 doesn’t have the right permissionsto let you open it.

We need to make sure that udev sets the right permissions so that we can access it as a user.To do so, create the file /etc/udev/rules.d/51-android.rules and copy the followingline:

SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="0001", MODE="0600", OWNER="<username>"

Now, plug and unplug the DevKit8000, and you should now be able to use adb from your user.

Get logs from the device

ADB provides many useful features to work with an existing Android device. The first we willsee is how to get the system logs from the whole system. To do this, just run adb logcat.

You will see the device logs on your terminal. This is a huge amount of information though,and it is difficult to find your way in all these lines.

The first thing we can do is download a little wrapper to adb to provide colored logs. You canfind it here: http://jsharkey.org/downloads/coloredlogcat.pytxt. Once down-loaded, just run it and you will see the logs colored and formatted to be easily readable.

ADB also provides filters to have a clearer output. These are formatted by the Tag:Prioritysyntax. For example, if you want all logs from MyApp, just run adb logcat MyApp:*.

Now try to save all logs from Dalvik to a file using only adb.

Get a shell on the device

Having a shell on the device can prove pretty useful. ADB provides such a feature, even thoughthis embedded shell is quite minimal. To access this shell, just type adb shell.

You can also run a command directly on the device thanks to adb shell. To do this, justappend the command to run at the end. Now, try to get all the mounted filesystems on thedevice.

Push/Pull files to a device

In the same way, ADB allows you to retrieve files from the connected device and send them toit, using the push and pull commands.


http://jsharkey.org/downloads/coloredlogcat.pytxt



System CustomizationLearn how to build a customized Android


• Use the product configuration system

• Change the default wallpaper

• Add extra properties to the system

• Use the product overlays

Setup a new product

Revert the changes you made to the beagleboard product and define a new product namedtraining instead. This product will have all the attributes of 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 kernel doesn’tchange, even though we compiled a different product. Change the name of the product that isused through the command line passed to the kernel to match the name of your product. Youcan pass the product name through the androidboot.hardware kernel parameter.

Now, setup a custom init config file that will be used only by your product and make it createthe file /data/hello_world. As we will need to copy prebuilt files to the image, we willprefer to declare prebuilt modules over the deprecated PRODUCT_COPY_FILES mechanism.

The system should compile and boot flawlessly on the DevKit8000, with all the corrections wemade earlier.

Change the default wallpaper

First, set up an empty overlay in your product directory.

The default wallpaper is located in frameworks/base/core/res/res/drawable/. Usethe overlay mechanism to replace the wallpaper by a custom one without modifying the origi-nal source code.

Add extra properties to the system

As we have seen, properties are extensively used around the Android system. Extend thesystem.prop file of the training product by adding a foo.bar property.

Boot the system and use getprop to check that the property has indeed been added.




Building a libraryAdd a native library to the build system

After this lab, you will be able to

• Add an external library to the Android build system

• Compile it statically and dynamically

• Add a component to a build

Building a static library

To get the libusb source code, go to www.libusb.org and download version 1.0.9. Extract thearchive in the external/libusb folder.

For this library, all the needed .c files are located in the libusb folder and its subfolders. Theheaders are located in the same folders. Make the build system generate a libusb-static.afile.

You will find one missing header that you will need to generate. Indeed, the config.h gener-ated by autoconf is not generated at all, because the Android build system ignores other buildsystems. You will have to generate it by yourself.

If successful, the build system should go through the build process and you should have adirectory generated in the out directory.

Building a shared library

Now, we will need to build a shared library along with the static one, called libusb.so. Usethe same config.h and modify the Android.mk file so that it gets compiled. Then, checkthat the shared object is present in the out folder.

Integrate the library into the Android image

As you can see, your library has been compiled during the build process, but if you boot thegenerated image or look inside the out/target/product/system/lib folder, you can seethat the shared object is not present.

Modify the appropriate files so that in the images, you will have the two variants of the librarywe compiled.


www.libusb.org



Add a native application to the buildLearn how to begin with the Android build system


• Add an external binary to a system

• Express dependencies on other components of the build system

Add the binary to the compiled image

Copy the mlbin.c file from the /home/<user>/felabs/android/native-app directoryand put it into the external/ml folder.

Just as for libusb, you now need to make an Android.mk file giving all the details neededby the build system to compile. But unlike libusb, this binary is an executable and dependson another piece of software.

Make it compile and be integrated in the generated images. Once you have the images, bootthe board, plug a missile launcher and test the application. You should see the launcher move.

Fix the Problems

However, when you start your tests, you will find that libusb cannot open the usb devicesbecause of restricted permissions. This can be fixed through ueventd.rc files. Add a device-specific ueventd configuration file to your build to make the files under /dev/bus/usb/world readable.

Warning The ueventd parser is buggy in Gingerbread and doesn’t read the androidboot.hardware parameter. You will have to name the file ueventd.omap3.rc.

After completing this lab, you can ask your instructor to give you a URL where Free Electrons’solution is available, and compare it with what you implemented.




Develop a JNI libraryLearn how JNI works and how to integrate it in Android

After this lab, you will be able to

• Develop bindings from Java to C

• Integrate these bindings into the build system

• Modify the Android framework

• Use JNI bindings

Write the bindings

The code should be pretty close to the one you wrote in the native application lab, so you willfind a skeleton of the folder to integrate into your product definition in the /home/<user>/felabs/android/jni directory. You will mostly have to modify function prototypes fromyour previous application to make it work with JNI.

As a reminder, JNI requires the function prototype to be like: JNIEXPORT <jni type>JNICALL Java_<package_class>_<function_name>(JNIEnv *env, jobject this).Beware that the function name can’t have any underscore in its name for JNI to function prop-erly.

Aside from the jni folder, there is also a java folder that contains a Java Interface, MissileBackendImpl.In the same folder, write the USBBackend class implementing this interface that uses yourbindings. You have an example of such a class in the DummyBackend.java file.

Integrate it in the build system

Now you can integrate it into the build system, so that it generates a .jar library that is in ourproduct, with the proper dependencies expressed.

You can find documentation about how to integrate device-specific parts of the framework inthe device/sample/frameworks folder.

Testing the bindings

We should now have a system with the files /system/framework/com.fe.android.backend.jar, containing the Java classes, /system/lib/liblauncher_jni.so, containing the JNIbindings and /system/lib/libusb.so.

Test what you did using the Main class present in the Java source code by directly invokingDalvik through the app_process command. You will have to provide both the classpath andthe class name to make it work and should look like CLASSPATH=path/to/java.jar app_process /system/bin com.fe.android.Main

Once you have a solution that works, you can ask your instructor to give you a URL whereFree Electrons’ solution is available, and compare it with what you implemented.




Going further

You will find that the binary we developed in the previous lab and the bindings share a lot ofcommon code. This is not very convenient to solve bugs impacting this area of the code, sincewe 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 common code part of ashared library used by both the bindings and the binary.




Write an application with the SDKLearn the basic concepts of the Android SDK and how to use them


• Write an Android application

• Integrate an application in the Android build system

Write the application

Go to the /home/<user/felabs/android/app directory.

You will find the basics for the MissileControl app. This app is incomplete, parts of someactivities are missing. However the UI part is already done, so create the code to launch theactivity with the given layout and the needed hooks defined in the layout description. Thesehooks implement the behavior of every button: move the launcher, fire, etc. Every buttonshould be self-explanatory, except for the USB/Emulation switch, which switches betweenUSB mode (which uses the USBBackend you developed) and Emulation mode (which uses theDummyBackend class for debugging).

The whole application now uses 3 layers to work, the application itself, which is a perfectlystandard Android application, relying on Java→ C bindings integrated in the Android frame-work, which in turn relies on libusb that we included in the system libraries.

We can’t have a real USB missile launcher for participant, so the DummyBackend class is pro-vided to test that your application and the changes to the framework are functional.

You can still switch back-ends with the switch button in the application.

Integrate the application

Once again, write down the Android.mk file to build the application in the Android image,and set the dependencies on the JNI libs so that the app is compiled and runs properly.

When you test your application, you will find that it crashes because it doesn’t find the .jarfile containing the Java bindings to libusb, while you used them successfully with Dalvik. Thisis because Android’s security model refuses to load untrusted jar files. However, you canmake Android accept a jar file by adding an xml file similar to AndroidManifest.xml intothe /system/etc/permissions/ folder. There are several examples of such a file in thisfolder, so adapt one to our case. After rebuilding, it should work fine.

Once you have completed this lab, you can ask your instructor to give you a URL where FreeElectrons’ solution is available, and compare it with what you implemented.

Going Further

We have used direct bindings and calls to use our library. However, we have seen that withAndroid, we tend to use services in that case, for security reasons, as well as to keep a consistent




state across the system. If you have any time left, implement a new service that will be used byyour application and replace the direct function calls.



Labs

Documents

android source code

repo sync command

kernel command line

beagleboard product denition

free electrons solution

android kernel sources

path environment variable

android build system