Changes between Initial Version and Version 1 of Android/OSDevelopment


Ignore:
Timestamp:
10/22/2017 05:28:45 AM (5 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Android/OSDevelopment

    v1 v1  
     1[[PageOutline]]
     2
     3= Android OS Development =
     4This page provides details about the Gateworks Android BSP which is used to produce the various components of the Android OS on a Gateworks Ventana board.
     5
     6 * For those interested in Android Application development please see [wiki:Android/AppDevelopment]
     7 * For compiling the actual Android OS, please see here: [wiki:Android/Building]
     8
     9[=#hardware-integration]
     10== Hardware Integration ==
     11
     12[=#gpio]
     13[=#led]
     14=== LEDs and GPIOs ===
     15If you wish to manipulate hardware resources such as LED's and GPIO's you can do so with the Linux sysfs APIs:
     16 * [wiki:gpio#gpiolib_sysfs GPIO class]
     17 * [wiki:gpio#led LED class]
     18
     19
     20=== System voltage and temperature sensors ===
     21The standard Linux hwmon sysfs APIs:
     22 * /sys/class/hwmon for hardware monitor devices such as the [wiki:gsc GSC temperature and voltage monitor]
     23 * /sys/class/thermal for thermal zones
     24
     25
     26
     27[=#button]
     28=== Physical Buttons (including Capacitive) ===
     29Physical buttons are handled by Linux device drivers that generate Linux input events and get mapped to Android key codes via [https://source.android.com/devices/input/key-layout-files.html Key Layout Files].
     30
     31Therefore, you can map (or disable) these to Android Key codes in the various .kl files in use on your device.
     32
     33The Android key codes typically tied to buttons are:
     34 - POWER
     35 - MENU
     36 - BACK
     37 - HOME
     38 - APP_SWITCH
     39 - SEARCH
     40
     41For more information on Key Layout Files see:
     42 - [https://source.android.com/devices/input/key-layout-files.html Key Layout Files]
     43
     44[=#gsc-pushbutton]
     45==== GSC User Pushbutton ====
     46The [wiki:gsc Gateworks System Controller] functions as a pushbutton controller for the front-panel user pushbutton available on most Ventana boards. This particular button is available as gpio-240 on Ventana boards however there is a [wiki:gsc#inputdriver gsc-input driver] that converts GSC related interrupts, such as push-button press-and-release to Linux Input events.
     47
     48By default note that the GSC is configured such that the user pushbutton is a hard reset. To configure it instead to be software controlled you need to set GSC CTRL_0 accordingly depending on the actions you wish to catch. For example:
     49 * Configure the pushbutton controller to just catch quick press-and-release events:
     50{{{#!bash
     51i2cset -f -y 0 0x20 0 0x00  # disable hard reset function
     52i2cset -f -y 0 0x20 11 0x01 # enable pushbutton interrupt
     53}}}
     54
     55The [wiki:gsc#inputdriver gsc-input driver] will catch all enabled GSC interrupts and emit a Linux Input event with a key-code cooresponding to a button (defined in Linux input.h). For example the GSC_IRQ_PB (pushbutton press-and-release) interrupt is mapped to BTN_0 which is defined as 0x100 (decimal 256) in [https://lxr.missinglinkelectronics.com/linux/include/uapi/linux/input.h#L481 input.h].
     56
     57There exists a key layout file that maps the Linux input event keycodes to Android key events in /system/usr/keylayout/gsc_input.kl:
     58{{{#!bash
     59130|root@ventana:/ # cat /system/usr/keylayout/gsc_input.kl                   
     60# quick press-and-release (held <700ms) of front-panel pushbutton
     61key 256   POWER                 WAKE
     62
     63# front panel pushbutton held >700ms (long-press)
     64key 257   HOME                  WAKE
     65
     66# user-eeprom section erased after 3 quick presses
     67key 258   SEARCH                WAKE
     68
     69# tamper event
     70key 259   POWER                 WAKE
     71}}}
     72 * Note that BTN_0 is hex 0x100 which is decimal 256
     73
     74If for some reason you wish to use the pushbutton to capture events that the GSC does not automatically capture and report as interrupts (for example a button 'press' event instead of a quick press-and-release event, a 'button held for x seconds' event, or a 'button pressed-and-released x times in quick succession' event, you can choose to monitor gpio-240 manually with a simple application which uses the poll(2) stdlib function to block waiting for an interrupt.
     75
     76For more information see:
     77 * [wiki:gsc#pushbutton GSC pushbutton]
     78 * [wiki:gsc#inputdriver gsc-input kernel driver]
     79 * [wiki:gsc#gsc_ctrl_0 GSC_CTRL_0 register]
     80 * [wiki:gsc#gsc_interrupt_status GSC_INTERRUPT_STATUS register]
     81 * [wiki:gpio#catchingagpiochangefromuserspacewithoutpolling Catching a GPIO event from userspace w/o polling]
     82
     83
     84[=#gpio-pushbutton]
     85==== GPIO as a Button ====
     86Any GPIO can be used as a pushbutton by using the gpio-keys or gpio-keys-polled driver. This driver will monitor a gpio's interrupt (or poll it if it has none), debounce it, and emit a Linux input event with a keycode of your choosing.
     87
     88In order to use this driver you need to:
     89 1. add a configuration section for it in the appropriate dtsi file for the board you are using.
     90 2. add a keylayout file to map the Linux input device created by the gpio-keys driver to an Android key
     91
     92For example, the [https://github.com/Gateworks/linux-imx6/blob/gateworks_kk4.4.3_2.0.0-ga/arch/arm/boot/dts/imx6qdl-gw51xx.dtsi gw51xx.dtsi] can have the following section added  [https://lxr.missinglinkelectronics.com/linux/include/uapi/linux/input.h input.h])
     93{{{
     94       /* define linux keyboard gpio-keys driver named 'gpio-button' */
     95       gpio: gpio-button {
     96               compatible = "gpio-keys";
     97               #address-cells = <1>;
     98               #size-cells = <0>;
     99               autorepeat;
     100
     101               /* map GW51xx DIO0 IMX6 GPIO1_IO16 to linux keycode 103 (KEY_UP) */
     102               button@1 {
     103                        label = "GPIO Key Up";
     104                        linux,code = <103>;
     105                        debounce-interval = <100>;
     106                        gpios = <&gpio1 16 GPIO_ACTIVE_LOW>;
     107               };
     108
     109               /* map GW51xx DIO1 IMX6 GPIO1__IO19 to linux keycode 109 (KEY_DOWN) */
     110               button@2 {
     111                        label = "GPIO Key Down";
     112                        linux,code = <108>;
     113                        debounce-interval = <100>;
     114                        gpios = <&gpio1 19 GPIO_ACTIVE_LOW>;
     115               };
     116
     117               /* map GW51xx DIO2 IMX6 GPIO1__IO17 to linux keycode 106 (KEY_RIGHT) */
     118               button@3 {
     119                        label = "GPIO Key Right";
     120                        linux,code = <106>;
     121                        debounce-interval = <100>;
     122                        gpios = <&gpio1 17 GPIO_ACTIVE_LOW>;
     123               };
     124
     125               /* map GW51xx DIO3 IMX6 GPIO1__IO18 to linux keycode 105 (KEY_LEFT) */
     126               button@4 {
     127                        label = "GPIO Key Left";
     128                        linux,code = <105>;
     129                        debounce-interval = <100>;
     130                        gpios = <&gpio1 18 GPIO_ACTIVE_LOW>;
     131               };
     132        };
     133
     134}}}
     135 * The gpio node needs to be at the top level and its placement is arbitrary however its customary to put it in alphabetical order (thus between the '''chosen''' node and the '''leds''' node)
     136
     137A keylayout file (.kl) is added to the live Android system. The keylayout files are matched by device name and in this case, the device-name is taken from the device-tree node name ('''gpio-button''' above) with a unique kernel-defined number appended. To determine the device name you can ls /sys/bus/platform/drivers/gpio-keys/gpio-button*:
     138{{{#!bash
     139root@ventana:/ # ls /sys/bus/platform/drivers/gpio-keys/gpio-button*           
     140/sys/bus/platform/drivers/gpio-keys/gpio-button.19
     141}}}
     142
     143Therefore in the example above where the gpio node was named 'gpio-button' the device name is 'gpio-button.19'. This name is used as the input device name and you can see all names of input devices with:
     144{{{#!bash
     145root@ventana:/ # cat /sys/class/input/input*/name                             
     146gsc_input
     147gpio-button.19
     148root@ventana:/ #
     149}}}
     150
     151Now create a keylout file named gpio-button.19.kl with:
     152{{{
     153# map linux keycode 103 (KEY_UP) to Android DPAD_UP
     154key 103   DPAD_UP               WAKE
     155# map linux keycode 108 (KEY_RIGHT) to Android DPAD_RIGHT
     156key 108   DPAD_RIGHT            WAKE
     157# map linux keycode 106 (KEY_LEFT) to Android DPAD_LEFT
     158key 106   DPAD_LEFT             WAKE
     159# map linux keycode 105 (KEY_DOWN) to Android DPAD_DOWN
     160key 105   DPAD_DOWN             WAKE
     161}}}
     162
     163And push it to your system:
     164{{{#!bash
     165adb remount
     166adb push gpio-button.19.kl /system/usr/keylayout/
     167}}}
     168
     169
     170References:
     171 * [https://lxr.missinglinkelectronics.com/linux/include/uapi/linux/input.h Linux keycodes]
     172 * [https://lxr.missinglinkelectronics.com/linux/Documentation/devicetree/bindings/input/gpio-keys.txt Linux gpio-keys device-tree bindings]
     173 * [https://source.android.com/devices/input/key-layout-files.html Android key-layout files]
     174
     175
     176[=#filesystem-permissions]
     177== Filesystem Permissions ==
     178You can read/write files in /sys from your Android app, but only if the Linux filesystem has the correct permissions to do so. Android uses Linux filesystem permissions in the following way:
     179 * root user/group used only by init process (as far as we can tell)
     180 * system user/group used for core Android OS
     181 * user applications get their own unique user/group added at APK install time which will remain constant until uninstalled but will not match the same APK's user/group on another device
     182
     183Therefore, if you want the OS to be able to control something (for instance backlight control) you need to ensure that user/group system has permissions for the resource (for instance /sys/class/backlight/backlight.3/brightness) for the Android Settings app or auto-brightness to adjust LCD brightness.
     184
     185If you want a user application to be able to control something (for instance a GPIO direction/value) you need to ensure that all user/group's have access to the resource (because each Android app has a unique user/group) you need to make sure the resource has the permissions set for 'others' (ie 666 for read/write or 444 for read-only).
     186
     187Permissions and ownership of devices and files are set by the following:
     188 * Android init - when processing *.rc files with the {{{chown}}} and {{{chmod}}} directives
     189 * Android ueventd - when devices appear dynamically based on configuration in {{{/ueventd.rc}}} and {{{/ueventd.freescale.rc}}}
     190 * /system/bin/init.sh (Gateworks Added) via {{{chmod}}} and {{{chown}}} shell commands
     191
     192
     193[=#networking]
     194== Android Networking Support ==
     195
     196
     197[=#netd]
     198=== Network Daemon (netd) ===
     199Most networking operations are performed by the network daemon ([http://androidxref.com/4.4.3_r1.1/xref/system/netd/ netd]) via a socket interface.
     200
     201
     202[=#dhcp]
     203=== DHCP ===
     204When netlink (kernel) shows a device obtaining a link (NETDEV_CHANGE) the EthernetDataTracker detects the change and dhcpcd is launched. There is a single EthernetDataTracker object (frameworks/base/core/java/android/net/EthernetDataTracker.java) that tracks 'Ethernet' device state changes but by design it only tracks a single device which is controlled by the '''config_ethernet_iface_regex''' string property (frameworks/base/core/res/res/values/config.xml). While this is defaulted to 'eth\d' to keep it generic this does not mean it will catch interface up/down events on 'any' ethernet as expected. Instead it only monitors the last interface from /sys/class/net that matches the setting.
     205
     206The interface change triggers a call to dhcp_do_request (libnetutils/dhcp_utils.c) to start the dhcp client daemon which requires a service for that specific interface be configured in init.rc. For example for eth1 you would need:
     207{{{
     208# eth1 dhcp support
     209service dhcpcd_eth1 /system/bin/dhcpcd -ABKL
     210    class main
     211    disabled
     212    oneshot
     213
     214service iprenew_eth1 /system/bin/dhcpcd -n
     215    class main
     216    disabled
     217    oneshot
     218}}}
     219
     220If you want to use eth1 with DHCP instead of eth0 you must change this property at build time (device/gateworks/ventana/overlay/frameworks/base/core/res/res/values/config.xml)
     221
     222References:
     223 * https://community.freescale.com/docs/DOC-93626 - How to Add Ethernet UI Support in ICS
     224
     225
     226[=#wifi]
     227=== !WiFi ===
     228See [wiki:Android/wireless]
     229
     230
     231[=#properties]
     232== Android Properties ==
     233You may want to use Android properties to abstract resources such as GPIO's, backlights, uart devices etc that may vary per board so that you can use a single firmware image that works across multiple boards.
     234
     235You can see examples of this in the [https://github.com/Gateworks/android_device_gateworks/blob/imx_kk4.4.3_2.0.0-beta/ventana/init.sh device/gateworks/ventana/init.sh] script where we create a symlink to /dev/gpsdevice for the various board-specific tty's. Another example may be to set gpio.dio0, gpio.dio1, gpio.dio2, gpio.dio3 properties to represent the numeric gpio for IMX6_DIO0-1 which vary between GW51xx/GW52xx/GW53xx/GW54xx boards.
     236
     237The Gateworks Android BSP init script sets the following properties that can be used in an app:
     238 * gpio.dio0 - the numeric gpio assigned to DIO0 (/sys/class/gpio/gpio<n>)
     239 * gpio.dio1 - the numeric gpio assigned to DIO1 (/sys/class/gpio/gpio<n>)
     240 * gpio.dio2 - the numeric gpio assigned to DIO2 (/sys/class/gpio/gpio<n>)
     241 * gpio.dio3 - the numeric gpio assigned to DIO3 (/sys/class/gpio/gpio<n>)
     242 * gpio.can_stby
     243
     244Your android app can use properties to obtain the actual gpio number used to access that function via sysfs:
     245 * Android Application Java API: [http://developer.android.com/reference/java/lang/System.html#getProperty(java.lang.String) getProperty]
     246 * Native C Code: use property_get from system/core/include/cutils/properties.h
     247
     248Here is a simple example C application showing how to use get_property to find the gpio value for a digital-io (assuming the init script above set this up) and reading the value from /sys/class/gpio:
     249 * external/gpio/Android.mk
     250{{{
     251LOCAL_PATH := $(call my-dir)
     252
     253PRIVATE_LOCAL_CFLAGS := -O2 -g -W -Wall
     254
     255include $(CLEAR_VARS)
     256
     257LOCAL_SRC_FILES := gpio.c
     258LOCAL_MODULE := gpio
     259LOCAL_MODULE_TAGS := optional
     260LOCAL_C_INCLUDES := $(LOCAL_PATH)/include/
     261LOCAL_CFLAGS := $(PRIVATE_LOCAL_CFLAGS)
     262LOCAL_STATIC_LIBRARIES := libcutils libc
     263
     264include $(BUILD_EXECUTABLE)
     265}}}
     266 * external/gpio/gpio.c
     267{{{#!c
     268/*
     269 * gpio.c - Tim Harvey <tharvey@gateworks.com>
     270 *
     271 * Simple example of how to get/set GPIO from a property
     272 *
     273 */
     274
     275#include <stdio.h>
     276#include <stdlib.h>
     277
     278#include <cutils/properties.h>
     279
     280int main(int argc, char **argv)
     281{
     282        char property[PROPERTY_VALUE_MAX];
     283        char buf[256];
     284        FILE *fp;
     285
     286        if (argc < 1) {
     287                fprintf(stderr, "Usage: %s <dionum>\n", argv[0]);
     288                exit(1);
     289        }
     290
     291        sprintf(buf, "gpio.dio%d", atoi(argv[1]));
     292        if (property_get(buf, property, "") == 0) {
     293                fprintf(stderr, "%s property not found\n", buf);
     294                exit(1);
     295        }
     296        printf("%s=gpio%d\n", buf, atoi(property));
     297
     298        sprintf(buf, "/sys/class/gpio/gpio%d/value", atoi(property));
     299        fp = fopen(buf, "r");
     300        if (!fp) {
     301                perror("fopen failed");
     302                fprintf(stderr, "likely a permission issue "
     303                        "or invalid file if gpio was not exported\n");
     304                exit(1);
     305        }
     306
     307        if (fread(buf, 1, sizeof(buf), fp) > 0) {
     308                printf("%d\n", atoi(buf));
     309        } else {
     310                fprintf(stderr, "read %s failed\n", buf);
     311        }
     312
     313        return 0;
     314}
     315}}}
     316
     317
     318[=#boot]
     319== Android Boot Process and Components ==
     320
     321[=#bootscript]
     322=== Android Bootloader Script ===
     323Because the Android kernel needs some additional parameters which are not required by a standard Linux kernel, the default Ventana u-boot scripts are not sufficient for booting Android directly. The default bootscripts however anticipate this requirement and therefore always look for a /boot/6x_bootscript-ventana file on the first partition (ext fs for non-mtd block storage). If this file is present the bootloader will load it and source it (thus executing the script it contains).
     324
     325This file is in device/gateworks/ventana/6x_bootscript.txt and is built by device/gateworks/bootscript.mk which uses the mkimage utility to put a u-boot image header on it.
     326
     327The Android bootscript does the following things in general:
     328 * configure GPU memory allocation kernel params (using mem_mb set dynamically by U-Boot)
     329 * detect display devices and configure kernel params accordingly
     330 * detect boot device and configure kernel params accordingly
     331
     332There are some U-Boot env variables that the bootscript can use for various overrides (mainly because there isn't a foolproof way of detecting display devices and boot devices):
     333 * console - device to use as kernel console (you can unset this to disable kernel console which increases boot time)
     334 * baudrate - baudrate to use for kernel console device
     335 * panel - display (or displays in prioritized order) which can a list of the following:
     336  * '''Hannstar-XGA''' (for 10" 1024x768 Freescale MXC-LVDS1 display with a egalax touch controller at i2c 0x04)
     337  * '''AUO-G070VW01''' (for 7" 800x480 display with a tsc2007 touch controller at i2c 0x49)
     338  * '''HDMI''' (for HDMI display where linux framebuffer mode can be specified in the 'hdmi' env var but defaults to 1080x720M@60. Other options for 'hdmi' var include 1920x1080M@60, 640x480M60 and others your monitor may support from /sys/class/graphics/fb0/modes)
     339  * If not specified, the above displays will attempt to be detected by simply seeing if an i2c device responds on their touchscreens slave address. Note that some HDMI monitors may have slave devices that match these
     340  * Please see [wiki:ventana/bootloader#Displaysupport setting display in bootloader at this link].
     341 * fs - the filesystem used on the storage device (defaults to ext2)
     342 * disk - the device number for the disk type (defaults to 0)
     343 * dtype - the storage type which can be one of usb, mmc,
     344 sata
     345  * this is set by the latest Gateworks U-Boot default scripts to avoid detection
     346  * if not specified will be the first device that has a boot/uImage file
     347 * bootdev - the boot device passed to Android which can be one of: fsl-ehci.0 (USB OTG), fsl-ehci.1 (USB EHCI), sdhci-esdhc-imx.2, ahci.0
     348
     349For the best understanding of how the boot script works you can view [https://github.com/Gateworks/android_device_gateworks/blob/imx_kk4.4.3_2.0.0-beta/ventana/6x_bootscript.txt the source here]
     350
     351Because the kernel, bootscript, device-tree files, and initial ramdisk are stored in the BOOT partition you can update the bootscriptmanually as follows via [#adb adb]:
     352{{{#!bash
     353bootable/bootloader/uboot-imx/tools/mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "boot script" -d \
     354  device/gateworks/ventana/6x_bootscript.txt 6x_bootscript-ventana
     355adb remount
     356adb push 6x_bootscript-ventana /boot/boot/
     357adb reboot
     358}}}
     359
     360
     361
     362[=#init.sh]
     363=== Android Init Script ===
     364Android has its own init system that differs from the init systems used across various Unix and Linux distributions. The Android init.rc script syntax allows some simple primitives for launching applications (either one-shot or persistent), setting ownership and permissions, and setting properties. This is useful for things that are common to all devices your firmware will run on and things that should be setup once (or defaulted) at boot.
     365
     366For example, if you want your application to be able to control LED brightness you can do either of the following:
     367 * init.rc: add the following to device/gateworks/ventana/init.rc 'on boot' section:
     368{{{#!bash
     369# set permissions for user leds (using Android init syntax)
     370chown system system /sys/class/leds/user1/brightness
     371chown system system /sys/class/leds/user2/brightness
     372chown system system /sys/class/leds/user3/brightness
     373chmod 0660 /sys/class/leds/user1/brightness
     374chmod 0660 /sys/class/leds/user2/brightness
     375chmod 0660 /sys/class/leds/user3/brightness
     376}}}
     377
     378The init.rc file for the Gateworks Ventana Android BSP can be found [https://github.com/Gateworks/Android/blob/imx_kk4.4.3_2.0.0-beta/ventana/init.rc here].
     379
     380Because the Android init application runs from a Linux inital ramdisk (initrd), if you modify init.rc you need to do a toplevel 'make' to rebuild the ramdisk.img, apply a U-Boot header to it with 'mkimage' and update it on your BOOT partition.
     381
     382References:
     383 * [https://android.googlesource.com/platform/system/core/+/master/init/readme.txt Android init syntax]
     384
     385
     386[=#init.rc]
     387=== Android Init Shell Script ===
     388Because the Android init system does not allow for complex syntax supporting decision making logic (ie if/then/else clauses) we configured [https://github.com/Gateworks/android_device_gateworks/blob/imx_kk4.4.3_2.0.0-beta/ventana/init.rc init.rc] to run a shell script during late boot to handle more complex board-specific tasks.
     389
     390You can find the init.sh script [https://github.com/Gateworks/Android/blob/imx_kk4.4.3_2.0.0-beta/ventana/init.sh here].
     391
     392Because this script is installed in the SYSTEM partition under /system/bin/init.sh you can update it via [#adb adb] (after making sure to remount /system as read/write):
     393{{{#!bash
     394adb remount
     395adb push device/gateworks/ventana/init.sh /system/bin/init.sh
     396adb shell chmod 0777 /system/bin/init.sh
     397adb reboot
     398}}}
     399
     400Our init script sets some android properties to describe the hardware in a non board-specific way so that you can use properties in your app to allow it to run on a variety of Gateworks boards. See [#properties here] for more details on properties.
     401
     402
     403[=#kernel]
     404=== Android Kernel ===
     405The Android kernel is a Linux kernel with a few additional patches which have not made it into mainline Linux yet.
     406
     407Because there is no userspace daemon such as udev which monitors Linux hotplug events and loads kernel modules on demand typically the kernel has no modules. This is not a hard rule however and if you want to prune down the kernel to reduce boot time you can remove support that is not required for your application and/or load kernel driver modules from [#init.rc init.rc] [#init.sh init.sh] or some other mechanism after the OS is fully booted.
     408
     409Because the kernel, bootscript, device-tree files, and initial ramdisk are stored in the BOOT partition you can update the kernel and dtbs manually as follows via [#adb adb]:
     410{{{#!bash
     411adb remount
     412adb push kernel_imx/arch/arm/boot/uImage /boot/boot/uImage
     413for i in `ls kernel_imx/arch/arm/boot/dts/imx6*gw*.dtb`; do adb push $i /boot/boot; done
     414adb reboot
     415}}}
     416
     417[=#external_storage]
     418== External Storage ==
     419The Gateworks Android BSP supports a number of storage mediums that can be classified as internal or external storage. External storage can be provided by physical media, like an SD card or USB, that is for temporary file storage and data transfer. The physical media may remain with the device for an extended period of time, but is not tied to the device and may be removed.
     420
     421=== Android Storage Framework ===
     422While linux level external storage support comes built into the kernel packaged with the Android OS, there are a combination of services started at boot time that perform staging operations to prepare the media before exposing it to apps. These framework services as they pertain to external storage are described below.
     423
     424* '''Vold''' - Mounting of physical external storage volumes is handled by Vold, which monitors device node paths and mounts when a device has been inserted and/or detected by the kernel.
     425
     426* '''sdcard Daemon''' - Performs permission fixups to make newly mounted external storage available to Android userspace and applications with the {{{READ/WRITE_EXTERNAL_STORAGE}}} permissions.
     427
     428* '''!MediaScanner''' - Crawls through the various filesystems that the Android OS has mounted successfully and makes the media files on them available to Android apps via special request intents (e.g. Gallery, Wallpaperpicker, etc.)
     429
     430=== Adding Support for External Storage ===
     431The steps for adding support for a new external storage device as they pertain to the Gateworks Android BSP are defined below:
     432
     4331. Add Vold device line in {{{fstab_nand}}} and/or {{{fstab_block}}}
     434
     435   Depending on whether your boot device was passed as a flash or block device from the bootloader to the kernel command line, either the {{{fstab_nand}}} or {{{fstab_block}}} file will be parsed by Vold to handle how the external storage will be mounted. Adding a new device will require an additional line of the format:
     436
     437   {{{<src> <mnt_point> <type> <mnt_flags> <fs_mgr_flags>}}}
     438
     439   * {{{src}}} - The kernel sysfs path where the device node exists (usually mounted at /sys). The path must start with {{{/}}}.
     440   * {{{mnt_point}}} - Filesystem path where the volume should be mounted (usually {{{auto}}}).
     441   * {{{type}}} - The type of the filesystem on the volume. For external cards, this is usually {{{vfat}}}.
     442   * {{{mnt_flags}}} - Vold ignores this field and it should be set to {{{defaults}}}
     443   * {{{fs_mgr_flags}}} - Vold ignores any lines in the unified fstab that do not include the {{{voldmanaged=}}} flag in this field. This flag must be followed by a label describing the card, and a partition number or the word {{{auto}}}. Other possible flags are {{{nonremovable}}}, {{{encryptable=sdcard}}}, {{{noemulatedsd}}}, and {{{encryptable=userdata}}}.
     444
     445   An example line for a uSD host controller would be:
     446   {{{/devices/soc0/soc.0/2100000.aips-bus/2198000.usdhc/mmc_host* auto vfat defaults voldmanaged=extsd:auto}}}
     447
     4482. Add storage element to {{{storage_list.xml}}}
     449
     450   The device-specific {{{storage_list.xml}}} configuration file (found under {{{$ANDROID_BUILD_TOP/device/gateworks/ventana/overlay/frameworks/base/core/res/res/xml/}}}), defines the attributes and constraints of storage devices. The {{{<StorageList>}}} element contains one or more {{{<storage>}}} elements, exactly one of which should be marked primary. {{{<storage>}}} attributes include:
     451
     452   * {{{mountPoint}}}: filesystem path of this mount.
     453   * {{{storageDescription}}}: string resource that describes this mount.
     454   * {{{primary}}}: true if this mount is the primary external storage.
     455   * {{{removable}}}: true if this mount has removable media, such as a physical SD card.
     456   * {{{emulated}}}: true if this mount is emulated and is backed by internal storage, possibly using a FUSE daemon.
     457   * {{{mtp-reserve}}}: number of MB of storage that MTP should reserve for free storage. Only used when mount is marked as emulated.
     458   * {{{allowMassStorage}}}: true if this mount can be shared via USB mass storage.
     459   * {{{maxFileSize}}}: maximum file size in MB.
     460
     461   An example {{{<storage>}}} element to accompany the fstab line above would be:
     462   {{{#!xml
     463<storage android:mountPoint="/storage/extsd"
     464         android:storageDescription="@string/storage_sd_card"
     465         android:primary="false"
     466         android:removable="true" />
     467}}}
     468
     4693. Add mkdir calls in {{{init.rc}}}
     470
     471   In the {{{init.rc}}} file found under {{{$ANDROID_BUILD_TOP/device/gateworks/ventana/}}} add the following lines in the {{{on init}}} section:
     472   {{{#!sh
     473mkdir /mnt/media_rw/extsd 0766 media_rw media_rw
     474mkdir /storage/extsd 0766 root root
     475}}}
     476
     4774. Append to the {{{SECONDARY_STORAGE}}} var in {{{init.rc}}}
     478
     479   Defined in the same {{{init.rc}}} is the {{{SECONDARY_STORAGE}}} variable which is a {{{:}}} delimited list of external paths that the Android framework's !MediaStore will parse. Append your storage device to this declaration line:
     480   {{{export SECONDARY_STORAGE /storage/extsd:/storage/extsd1:/storage/udisk:/storage/udisk1:/storage/sata}}}
     481
     4825. Add sdcard fuse service in {{{init.rc}}}
     483
     484   Towards the end of the same {{{init.rc}}} file is a series of service declaration lines. Adding these fuse services will emulate a case-insensitive, permissionless filesystem backed by the storage device regardless of filesystem type, as long as the filesystem is understood by the kernel. Following the same uSD example:
     485   {{{#!bash
     486# virtual sdcard daemon running as media_rw (1023)
     487service fuse_extsd /system/bin/sdcard -u 1023 -g 1023 -w 1023 -d /mnt/media_rw/extsd /storage/extsd
     488    class late_start
     489    disabled
     490}}}
     491
     492[=#selinux]
     493== Security-Enhanced Linux (SELinux) ==
     494SELinux is a mandatory access control (MAC) system for the Linux OS. Sockets, Files, and Processes all have labels in SELinux. A label takes the form of {{{user:role:type:mls_level}}}. Rules are applied to labels and take the form {{{allow domains types:classes permissions}}}. The {{{file_contexts}}} file assigns labels to files via regular expression matches. Filesystems must be built to include SELinux filesystem attributes. The {{{restorecon}}} userspace application applies policies to a running kernel, which is usually done as one of the first things in system init.
     495 
     496Android has been phasing in more robust security measures with each release. [https://en.wikipedia.org/wiki/Security-Enhanced_Linux SELinux] is a Linux kernel security module that provides a mechanism for supporting access control security policies, including the United States Department of Defense-style mandatory access controls (MAC). SELinux started being used for Android 3.x (Jellybean) in a permissive mode, and in enforcing mode for Android 4.x (Kitkat).
     497
     498While troubleshooting it may be useful to disable SELiux which you can do in the following ways:
     499 * add {{{selinux=0}}} to the kernel cmdline (requires CONFIG_SECURITY_SELINUX_BOOTPARAM=y in kernel config)
     500 * {{{setenforce 0}}} on cmdline
     501
     502SELinux policy files are compiled into the {{{sepolicy}}} which exists in the root of the ramdisk on the BOOT partition. This is created from rules defined in files in paths from BOARD_SEPOLICY_DIRS defined in !BoardConfig.mk. The ventana specific policies are located in [https://github.com/Gateworks/android_device_gateworks/tree/imx_kk4.4.3_2.0.0-ga/ventana/sepolicy device/gateworks/ventana/sepolicy].
     503
     504Additionally policies can be found in [https://android.googlesource.com/platform/external/sepolicy/+/android-4.4.3_r1 external/sepolicy] which is a collection of common policy files used by Linux distros.
     505
     506SELinux denials errors output as kernel error messages prefixed with "avc: ". For example:
     507{{{#!bash
     508$ adb shell su -c dmesg | grep "avc: "
     509[   62.658290] type=1400 audit(1443478068.109:5): avc:  denied  { setgid } for  pid=1155 comm="hostapd" capability=6  scontext=u:r:netd:s0 tcontext=u:r:netd:s0 tclass=capability permissive=0
     510[   62.675542] type=1400 audit(1443478068.129:6): avc:  denied  { setgid } for  pid=1155 comm="hostapd" capability=6  scontext=u:r:netd:s0 tcontext=u:r:netd:s0 tclass=capability permissive=0
     511[   62.692514] type=1400 audit(1443478068.149:7): avc:  denied  { add_name } for  pid=1155 comm="hostapd" name="1010" scontext=u:r:netd:s0 tcontext=u:object_r:cgroup:s0 tclass=dir permissive=0
     512[   62.709701] type=1400 audit(1443478068.169:8): avc:  denied  { setuid } for  pid=1155 comm="hostapd" capability=7  scontext=u:r:netd:s0 tcontext=u:r:netd:s0 tclass=capability permissive=0
     513}}}
     514 * above the 'hostapd' process exec'd by netd is trying to setgid/setuid and failed
     515
     516The {{{audit2allow}}} tool from the {{{policycoreutils}}} package can take these denials and converts them into corresponding SELinux policy statements:
     517{{{#!bash
     518sudo apt-get install policycoreutils
     519adb shell su -c dmesg | grep "avc: " | audit2allow # show rules
     520adb shell su -c dmesg | grep "avc: " | audit2allow -p out/target/product/ventana/root/sepolicy # analyze against current policy
     521}}}
     522
     523For example when the above netd/hostapd violations are run through audit2allow this shows the following additions could be made to fix the violations:
     524{{{
     525#============= netd ==============
     526allow netd cgroup:dir add_name;
     527allow netd self:capability { setuid setgid };
     528}}}
     529
     530The {{{ls -Z}}} command will show you file contexts and similarly the {{{ps -Z}}} command will show you process contexts.
     531
     532You can find the processed policies with comments detailing their source in $OUTDIR/obj/ETC/sepolicy_intermediates/policy.conf which is built from the {{{external/sepolicy}}} project.
     533
     534During development you can rebuild the {{{sepolicy}}} (which verifies your rules and configuration) via {{{mmm external/sepolicy}}}. You can rebuild and update your ramdisk with a something like:
     535{{{
     536mmm external/sepolicy && mkbootfs out/target/product/ventana/root | minigzip > out/target/product/ventana/ramdisk.img && \
     537mkimage -A arm -O linux -T ramdisk -n "RAM Disk" -d out/target/product/ventana/ramdisk.img \
     538out/target/product/ventana/boot/boot/uramdisk.img && \
     539adb remount && \
     540adb push out/target/product/ventana/boot/boot/uramdisk.img /boot/boot/uramdisk.img && \
     541adb reboot
     542}}}
     543
     544Be aware, that because this does not rebuild the system filesystem, any rule changes will not take effect without a manual {{{restorecon <file>}}}.
     545
     546=== Adding New Files ===
     547The process for injecting files into a SELinux filesystem includes the following:
     548
     5491. Properly apply security labels (mentioned [#selinux above]) in {{{device/gateworks/ventana/sepolicy/file_contexts}}}
     5502. Create a .te policy file under {{{device/gateworks/ventana/sepolicy/}}}
     5513. Add the .te file to the policy list in {{{device/gateworks/ventana/BoardConfig.mk}}}
     5525. Apply proper user.group ownership in {{{system/core/include/private/android_file_config.h}}}
     553
     554References:
     555 * [https://source.android.com/security/selinux/index.html Security-Enhanced Linux in Android]
     556
     557
     558[=#partitions]
     559== Partitions ==
     560The flash storage space on an Android device typically contains the following partitions.
     561 * BOOT: /boot - contains bootscript/kernel/ramdisk that boots Android init
     562 * RECOVERY: /recovery - contains bootscript/kernel/ramdisk that boots an '''Android recovery image''' who's function is very device/vendor specific
     563 * SYSTEM: /system ro - the system '''ROM'''
     564 * DATA: /data - user data - this is where your apps and app data are stored and where you want the most space
     565 * CACHE: /cache - used for various (unclear) OS caching (including downloading apps from play store)
     566 * MISC: /misc - a tiny partition used by recovery to stash some information away about what its doing in case the device is restarted while the OTA package is being applied
     567 * VENDOR: /device - for vendor specific files
     568
     569The creation of the partitions is controlled by build/core/Makefile.
     570
     571The mounting of the partitions is controlled by Android's init application by the mount_all command in init.rc which is passed a file containing device and mountpoint information. This is all done in the ramdisk and the mount_all is typically called from the 'on fs' hook as the last step in init.
     572
     573The storage device partitioning is taken care of with whatever script you use to image android onto a specific device:
     574 * device/gateworks/ventana/mksdcard.sh - for block storage devices such as USB/mSATA/MMC. The partition sizes are baked into the script
     575 * device/gateworks/ventana/ubi/ubinize.ini - for NAND ubi volume creation of ubi image
     576
     577References:
     578 - [https://source.android.com/devices/tech/ota/index.html#android-device-layout Android device layout]
     579
     580
     581[=#bootpartition]
     582=== BOOT partition ===
     583The BOOT partition is very device specific and typically contains a kernel and ramdisk containing the Android init system (/sbin/init, init.rc and its includes) and processes early init until the mounting of the other filesystems. When filesystems are mounted this may be mounted to /boot
     584
     585The files have on our boot partition use are:
     586 * 6x_bootscript-ventana - bootscript that sets up the kernel cmdline (including android specific parameters) and loads/executes kernel
     587 * uImage - kernel (zImage wrapped in a uboot image header)
     588 * imx6*gw*.dtb - kernel devicetree blobs
     589 * uramdisk.img - initial ramdisk (compressed cpio archive wrapped in a uboot image header)
     590
     591
     592==== ramdisk.img / uramdisk.img ====
     593The boot ramdisk is the initial filesystem loaded by the bootloader into memory and passed to the kernel via a kernel parameter. It is a Linux kernel '''initramfs''' or '''initial ramdisk''' (see Documentation/early-userspace/buffer-format.txt) which is based around the 'newc' or 'crc' CPIO formats and therefore can be created with the cpio utility.
     594
     595It is created by build/core/Makefile using (MKBOOTFS) out/host/linux-x86/bin/mkbootfs (built from system/core/cpio/mkbootfs.c) with the following command:
     596{{{#!bash
     597mkbootfs out/target/product/ventana/root | minigzip > out/target/product/ventana/ramdisk.img
     598}}}
     599
     600It is built from $(OUTPUT_DIR)/boot and deps are setup on all files in that dir other than prebuilt files, copied headers, generated sources, and default installed modules.
     601
     602To install files onto the ramdisk make sure they get copied to the root/ directory of the product output folder:
     603 * from ventana.mk or imx6.mk add a file to PRODUCT_COPY_FILES destined for root/:
     604{{{
     605PRODUCT_COPY_FILES += device/gateworks/ventana/foo:root/foo
     606}}}
     607 * from a module Android.mk you can set LOCAL_MODULE_PATH to TARGET_ROOT_OUT to put it in root/:
     608{{{
     609LOCAL_MODULE_PATH := $(TARGET_ROOT_OUT)
     610}}}
     611
     612If changes are made you may need to remove the images to force dependency checks prior to rebuilding:
     613{{{#!bash
     614rm -rf out/target/product/ventana/boot/boot/uramdisk.img \
     615 out/target/product/ventana/ramdisk.img
     616make
     617}}}
     618
     619A typical list of files on a ramdisk:
     620 * default.prop
     621 * proc - mountpoint
     622 * dev - mountpoint
     623 * init.rc - config for init
     624 * init - android init application
     625 * sys - mountpoint
     626 * init.goldfish.rc
     627 * sbin/adbd - android debug bridge daemon
     628 * system - mountpoint
     629 * data mountpoint
     630
     631Because its loaded by uboot, a uImage header is wrapped around it by 'mkimage' creating uramdisk.img from ramdisk.img. This is not part of the core/build system but instead done vi device/gateworks/ramdisk.mk
     632
     633To extract a ramdisk.img from a uramdisk.img you need to take off the 64-byte U-Boot header:
     634{{{#!bash
     635dd if=uramdisk.img of=ramdisk.img bs=1 skip=64
     636}}}
     637
     638To extract a ramdisk.img (which is a gzipped CPIO archive):
     639{{{#!bash
     640mkdir root; cd root; zcat ../ramdisk.img | cpio -i
     641}}}
     642
     643To list the contents of a ramdisk.img (which is a gzipped CPIO archive):
     644{{{#!bash
     645zcat ramdisk.img | cpio -t
     646}}}
     647
     648To create a ramdisk.img from a directory:
     649{{{#!bash
     650find . | cpio -o -H newc -O ../ramdisk.cpio; gzip -f ../ramdisk.cpio; mv ../ramdisk.cpio.gz ../ramdisk.img
     651}}}
     652
     653To add a U-Boot header to a ramdisk.img:
     654{{{#!bash
     655mkimage -A arm -O linux -T ramdisk -n "RAM Disk" -d ramdisk.img uramdisk.img
     656}}}
     657
     658A nice '''one-liner for re-packaging a uramdisk.img from out/target/product/ventana/root and pushing it to a target over adb''':
     659{{{#!bash
     660mkbootfs out/target/product/ventana/root | minigzip > out/target/product/ventana/ramdisk.img && \
     661mkimage -A arm -O linux -T ramdisk -n "RAM Disk" -d out/target/product/ventana/ramdisk.img \
     662out/target/product/ventana/boot/boot/uramdisk.img && \
     663adb remount
     664adb push out/target/product/ventana/boot/boot/uramdisk.img /boot/boot/uramdisk.img && \
     665adb reboot
     666}}}
     667
     668
     669[=#recoverypartition]
     670=== RECOVERY partition ===
     671The recovery partition is very device specific and works the same way as the BOOT partition in order to boot a system with some sort of recovery tools or mechanism for restoring a system ROM. Typically this works by booting this instead of BOOT if the user is holding a key down (usually home+power on a mobile device) during powerup and typically (in the case of phones at least) presents the user with a very rudimentary text based menu using vol up/down and power button to move and select menu items allowing you to do things like:
     672 * erase cache
     673 * create backups
     674 * install ROM's
     675
     676A recovery.img is a bootable image with the same layout/format as the boot image (see above).
     677
     678Typically the ramdisk will have a few more files such as graphics resources and a different init script/app.
     679
     680
     681[=#systempartition]
     682=== SYSTEM partition ===
     683The SYSTEM partition (ext4 for block devs, ubifs for NAND devs) is mounted to /system read-only and contains the base Android OS minus installed apps and data (which go to the DATA partition mounted read-write to /data). This is what is considered the Android '''ROM'''.
     684
     685This is built from core/build/Makefile by creating a ramdisk image of out/target/product/<product>/system. The permissions of the files in /system is controlled by system/core/include/private/android_filesystem_config.h ('''do not forget to set permissions here for new files or at least check that they are configured properly through wildcards''')
     686
     687The dependencies on rebuilding system.img are the files in $(PRODUCT_OUT)/installed-files.txt
     688
     689To add files use PRODUCT_COPY_FILES with a destination of system/:
     690{{{
     691PRODUCT_COPY_FILES += device/gateworks/ventana/foo:system/foo
     692}}}
     693
     694The system partition uses an ext4 filesystem image system.img, created using a helper script 'out/host/linux-x86/bin/mkuserimg.sh <sourcedir> <output-file> ext4 <mountpoint> <size> <fc>' which does the following:
     695{{{#!bash
     696make_ext4fs  -S out/target/product/ventana/root/file_contexts -l 398458880 -a system out/target/product/ventana/obj/PACKAGING/systemimage_intermediates/system.img out/target/product/ventana/system
     697}}}
     698
     699This in turn uses the out/host/linux-x86/bin/make_ext4fs tool built from system/extras/ext4_utils/make_ext4fs.c
     700{{{#!bash
     701make_ext4fs [ -l <len> ] [ -j <journal size> ] [ -b <block_size> ]
     702    [ -g <blocks per group> ] [ -i <inodes> ] [ -I <inode size> ]
     703    [ -L <label> ] [ -f ] [ -a <android mountpoint> ]
     704    [ -S file_contexts ]
     705    [ -z | -s ] [ -w ] [ -c ] [ -J ] [ -v ]
     706    <filename> [<directory>]
     707}}}
     708
     709
     710
     711[=#datapartition]
     712=== DATA partition ===
     713The DATA partition  (ext4 for block devs, ubifs for NAND devs) is where all user apps/data/settings are stored and is mounted read/write to /data. Initially its empty and formatting it is the equivalent of a 'factory wipe' on an Android device. If you wanted to pre-install apps but allow them to be removable, you would do that here.
     714
     715
     716[=#cachepartition]
     717=== CACHE partition ===
     718The CACHE partition is a read/write partition (ext4 for block devs, or ubifs for NAND devs) and is a general purpose storage area. I'm not clear how usable this is by apps, or if it is only usable by the base OS and Google Apps (I have to think its usable by anything that wants it). I do know that the Play Store uses this area for temporary downloads thus if you severely limit the size you cripple the ability to download large apps. I also am not clear on the size requirements or recomendations for partitioning schemes. We size this to 512MB which I got from other IMX6 Android BSP's.
     719
     720
     721[=#vendorpartition]
     722=== VENDOR partition ===
     723The VENDOR partition (ext4 for block devs, or ubifs for NAND devs) is mounted to /device as readonly and is apparently where vendors should put their add-on apps/drivers(kernel-modules)/etc. I'm not sure I understand the point of this vs the vendors adding them into the SYSTEM partition. This is unused by Freescale but still created with 10MB of space
     724
     725
     726[=#miscpartition]
     727=== MISC partition ===
     728The VENDOR partition (ext4 for block devs, or ubifs for NAND devs) is mounted to /misc as read/write and is used by recovery to stash some information away about what it's doing in case the device is restarted while the OTA package is being applied.
     729
     730
     731[=#androidui]
     732== Android System UI Info ==
     733Some common questions and answers regarding the Android OS UI:
     734 1. how do I disable the 'Navigation Bar'?
     735  * The Navigation bar is the bar at the bottom of the screen reserved for soft buttons for back, home, and recent apps
     736  * You can disable it at build time for the entire OS by setting 'config_showNavigationBar' property to false in device/gateworks/ventana/overlay/frameworks/base/core/res/res/values/config.xml
     737  * You can disable within an application at runtime as well - see [https://developer.android.com/training/system-ui/navigation.html here]
     738 1. Why is the Android Launch showing the dock bar on the right and the Google Search bar on the left instead of a typical top and bottom layout?
     739  * This has to do with the Launcher application layout configuration. By default its configured to use this layout if the smallest width is not at least 720dp (Device Independent Pixels) which is a function of your resolution (which Android obtains from the Linux framebuffer info) and the defined dpi (declared in ro.sf_lcd_density in the init script)
     740
     741
     742[=#touchscreen]
     743== Android Touchscreen calibration ==
     744The Android AOSP code does not have any built-in support for x/y point calibration which is often needed for touchscreen hardware. This means that touchscreen controller drivers must calibrate the points before sending them to the Linux input subsystem.
     745
     746In order to avoid placing similar calibration code in various touchscreen drivers Gateworks added basic 5point calibration support to the Android InputReader class ([https://github.com/Gateworks/android_frameworks_base/commit/51676677e5db2e1d3aba80f6f97e681b3cfe8e9d commit]). If you are using a touchscreen not officially supported by Gateworks you should manually calibrate by doing the following:
     747 * boot to Android with a touchscreen driver providing linux input events (Note that may need an Input Device Configuration (IDC) file)
     748 * build and install the TSCalibration2.apk. For example:
     749{{{#!bash
     750mmm packages/apps/TSCalibration2/
     751adb install out/target/product/ventana/system/priv-app/TSCalibration2.apk
     752adb shell "mkdir /data/misc/tscal; chown system.misc /data/misc/tscal; chmod 771 /data/misc/tscal"
     753}}}
     754  * see [wiki:Android/OSDevelopment#adb-security below] regarding how to enable ADB for a development host without needing touchscreen access
     755 * launch TSCalibration2 and perform the 5 point calibration
     756{{{#!bash
     757adb shell am start -a android.intent.action.MAIN -n org.zeroxlab.util.tscal/.TSCalibration
     758# send an ESCAPE key to escape out of the Launcher's first boot help
     759adb shell input keyevent 82
     760}}}
     761  * to unlock the screen and dismiss any first-boot help dialogs from Launcher you will likely need to temporarily install a USB mouse or use the input shell command to send specific key events
     762 * sync the filesystem and powercycle
     763{{{#!bash
     764sync
     765}}}
     766  * if the /data/misc/tscal/pointercal file existed at bootup it will be re-read on change and you do not need to restart
     767
     768References:
     769 * https://source.android.com/devices/tech/input/input-device-configuration-files.html
     770 * https://source.android.com/devices/tech/input/touch-devices.html (info on calibration etc)
     771 * http://www.ti.com/lit/an/slyt277/slyt277.pdf
     772
     773
     774[=#shell]
     775== Android shell ==
     776Handy commands you can enter via the shell over adb or serial console (Note you can use 'adb shell <command>' to execute shell commands over the Android Debug Bridge):
     777 - input:
     778  - send power button event:
     779{{{#!bash
     780input keyevent 26
     781}}}
     782  - unlock screen
     783{{{#!bash
     784input keyevent 82
     785}}}
     786 - pm (package management):
     787  - display installed packages
     788{{{#!bash
     789pm list packages -f
     790}}}
     791  - clear app data
     792{{{#!bash
     793pm clear <packagename>
     794}}}
     795
     796
     797
     798[=#build-system]
     799== Using the Android build system ==
     800The Android build system consists of a set of makefiles and scripts that can build the entire OS image or build specific directories at a time.
     801
     802See also:
     803 - https://source.android.com/source/building.html
     804 - http://elinux.org/Android_Build_System
     805
     806
     807[=#build-setup]
     808=== Build environment setup ===
     809In order to use the build system you must source the scripts into your shell environment (commonly referred to as 'activating the shell'). This must be done for each and every shell you wish to build with:
     810{{{
     811# activate shell for building Android OS
     812. ./build/env_setup.sh
     813}}}
     814
     815Secondly, you must select a target device and BUILDTYPE (one of eng, user, or userdebug). For the Gateworks ventana you would use 'ventana-eng', or 'ventana-user' for example:
     816{{{
     817# configure for building User build for Ventana
     818lunch ventana-user
     819}}}
     820
     821
     822[=#build-commands]
     823=== Build shell commands ===
     824Once in an activated shell (see [#build-setup above]) you can use the following common aliases to build:
     825
     826Make Targets - Here is a list of different make targets you can use to build different parts of the system:
     827- {{{make}}} - build OS
     828- {{{make clean}}} - clean everything
     829- {{{make dist}}} - build OTA and dist files in DIST_OUT directory (defaults to out/dist)
     830- {{{make modules}}} - show a list of submodules that can be built by themselves
     831- {{{make <local_module>}}} - make a specific module by name (not the directory of the module but the name assigned by LOCAL_MODULE - use 'make modules' to show a list)
     832- {{{make clean-<local_module>}}} - clean a specific module
     833
     834Helper macros and functions - There are some helper macros and functions that are installed when you source envsetup.sh. They are documented at the top of envesetup.sh, but here is information about a few of them:
     835- {{{croot}}} - change directory to the top of the tree
     836- {{{m}}} - execute 'make' from the top of the tree (even if your current directory is somewhere else)
     837- {{{mm}}} - builds all of the modules in the current directory
     838- {{{mmm <dir1> ...}}} - build all of the modules in the supplied directories
     839- {{{cgrep <pattern>}}} - grep on all local C/C++ files
     840- {{{jgrep <pattern>}}} - grep on all local Java files
     841- {{{resgrep <pattern>}}} - grep on all local res/*.xml files
     842- {{{godir <filename>}}} - go to the directory containing a file
     843
     844
     845[=#android.mk]
     846=== Modules and Android.mk ===
     847Android modules are projects in the build tree that contain an Android.mk file. These are scanned by the build system. Each Android.mk file declares one or more '''modules''' by defining a few vars:
     848 * LOCAL_MODULE: module name
     849 * LOCAL_MODULE_TAGS: defines which build variants this module should be installed in. (see [http://www.kandroid.org/online-pdk/guide/build_system.html here]). Use 'user' for final build only, 'eng' for eng build only, 'optional' for all (technically only if the module is listed in the PRODUCT_PACKAGES). You can remove this completely to make it not built at all.
     850 * LOCAL_MODULE_PATH:  the directory where to install compiled objects (TARGET_OUT_SHARED_LIBARIES would be the 'lib' subdir in the system folder)
     851 * LOCAL-SRC_FILES: the *.c files
     852 * LOCAL_C_INCLUDES: additional include dirs (relative to topdir)
     853 * LOCAL_SHARED_LIBARIES: names of libs to include (like liblog, libcutils, libtinyalsa, libdl, etc)
     854 * if building a *.so 'include $(BUILD_SHARED_LIBARY)'
     855
     856see also:
     857 - http://android.mk/
     858
     859
     860==== Conditional builds ====
     861It is common to wrap the modules around ifdefs to conditionally enable it based on defines from BoardConfig.mk. For example the Freescale ALSA module for i.MX in hardware/imx/alsa/Android.mk:
     862{{{
     863ifeq ($(strip $(BOARD_USES_ALSA_AUDIO)),true)
     864
     865LOCAL_PATH := $(call my-dir)
     866
     867include $(CLEAR_VARS)
     868LOCAL_MODULE := audio.primary.$(TARGET_BOARD_PLATFORM)
     869LOCAL_MODULE_PATH := $(TARGET_OUT_SHARED_LIBRARIES)/hw
     870LOCAL_SRC_FILES := tinyalsa_hal.c
     871LOCAL_C_INCLUDES += \
     872        external/tinyalsa/include \
     873        system/media/audio_utils/include \
     874        system/media/audio_effects/include
     875LOCAL_SHARED_LIBRARIES := liblog libcutils libtinyalsa libaudioutils libdl
     876LOCAL_MODULE_TAGS := optional
     877include $(BUILD_SHARED_LIBRARY)
     878
     879endif
     880}}}
     881
     882
     883==== Install data ====
     884If you wish to create a module that copies data files not built from source then you can eliminate the LOCAL_C_INCLUDES and LOCAL_SHARED_LIBRARIES and include $(BUILD_PREBUILT) such as:
     885{{{
     886LOCAL_PATH := $(call my-dir)
     887
     888include $(CLEAR_VARS)
     889LOCAL_MODULE       := wpa_supplicant_overlay.conf
     890LOCAL_MODULE_TAGS  := optional
     891LOCAL_MODULE_CLASS := ETC
     892LOCAL_SRC_FILES    := $(LOCAL_MODULE)
     893LOCAL_MODULE_PATH  := $(TARGET_OUT_ETC)/wifi
     894include $(BUILD_PREBUILT)
     895}}}
     896 * example from device/fsl/common/wifi/Android.mk
     897
     898Reference:
     899 * http://www.kandroid.org/online-pdk/guide/build_system.html
     900
     901
     902==== Install pre-built application (APK) ====
     903An APK (Android application PacKage) is an application file ready for installation in an Android device. It is a compressed ZIP archive in the JAR format and is what is distributed to Android users for installation in their smartphones and tablets.
     904
     905If you have APK's that you wish to pre-install you can do so by creating an Android.mk file that installs the apk to the system partition by including the $(BUILD_PREBUILT) make file.
     906
     907Example Android.mk:
     908{{{
     909LOCAL_PATH := $(call my-dir)
     910
     911include $(CLEAR_VARS)
     912LOCAL_MODULE_TAGS := optional
     913LOCAL_MODULE := MyApp
     914LOCAL_SRC_FILES := myapp.apk
     915LOCAL_MODULE_CLASS := APPS
     916LOCAL_MODULE_SUFFIX := $(COMMON_ANDROID_PACKAGE_SUFFIX)
     917# tell dexopt not to try resigning the apks
     918LOCAL_CERTIFICATE := PRESIGNED
     919include $(BUILD_PREBUILT)
     920}}}
     921
     922
     923[=#buildmodule]
     924=== Building a stand-alone-app within the Android build system ===
     925If you are developing your own Android application, you can built it easily in the android BSP directory and use adb to quickly update it on the target.
     926
     927For example, on your development host in the Gateworks Android BSP directory:
     928{{{#!bash
     929# activate your shell
     930source build/envsetup.sh
     931# configure build type
     932lunch ventana-eng
     933# rebuild your app (replace external/can-test with the directory to your app containing an Android.mk)
     934mmm external/can-test/
     935}}}
     936
     937Note that if your application is fairly self-contained and not tightly coupled with the OS, you may wish to use Android Studio to develop it outside of the Android OS build system. See [wiki:Android/AppDevelopment] for more info.
     938
     939
     940[=#helloworld]
     941=== Android Hello World Executable C File ===
     942As a full example consider a simple 'helloworld' application.
     943
     9441. Create helloworld.c file (create a helloworld directory in the external directory)
     945 * external/helloworld/helloworld.c
     946{{{#!c
     947#include <stdio.h>
     948#include <stdlib.h>
     949
     950
     951int main(int argc, char **argv)
     952{
     953        printf("Hello World \n");
     954        return 0;
     955}
     956
     957}}}
     958
     9592. Create an Android.mk file
     960 * external/helloworld/Android.mk
     961{{{
     962LOCAL_PATH := $(call my-dir)
     963
     964PRIVATE_LOCAL_CFLAGS := -O2 -g -W -Wall
     965
     966include $(CLEAR_VARS)
     967
     968LOCAL_SRC_FILES := helloworld.c
     969LOCAL_MODULE := helloworld
     970LOCAL_MODULE_TAGS := optional
     971LOCAL_C_INCLUDES := $(LOCAL_PATH)/include/
     972LOCAL_CFLAGS := $(PRIVATE_LOCAL_CFLAGS)
     973LOCAL_STATIC_LIBRARIES := libcutils libc
     974
     975include $(BUILD_EXECUTABLE)
     976}}}
     977
     9783. Compile the file (using an activated shell - Note: A full build must have been compiled prior to this...)
     979 * compile by directory (or you could compile by module via 'make helloworld' however this takes longer as it needs to scan the directories for module names)
     980{{{
     981$ mmm external/helloworld
     982============================================
     983PLATFORM_VERSION_CODENAME=REL
     984PLATFORM_VERSION=4.4.3
     985TARGET_PRODUCT=ventana
     986TARGET_BUILD_VARIANT=user
     987TARGET_BUILD_TYPE=release
     988TARGET_BUILD_APPS=
     989TARGET_ARCH=arm
     990TARGET_ARCH_VARIANT=armv7-a-neon
     991TARGET_CPU_VARIANT=cortex-a9
     992HOST_ARCH=x86
     993HOST_OS=linux
     994HOST_OS_EXTRA=Linux-3.13.0-43-generic-x86_64-with-Ubuntu-14.04-trusty
     995HOST_BUILD_TYPE=release
     996BUILD_ID=2.0.0
     997OUT_DIR=out
     998============================================
     999.....
     1000
     1001Import includes file: out/target/product/ventana/obj/EXECUTABLES/helloworld_intermediates/import_includes
     1002target thumb C: helloworld <= external/helloworld/helloworld.c
     1003external/helloworld/helloworld.c: In function 'main':
     1004external/helloworld/helloworld.c:5:14: warning: unused parameter 'argc' [-Wunused-parameter]
     1005external/helloworld/helloworld.c:5:27: warning: unused parameter 'argv' [-Wunused-parameter]
     1006target Executable: helloworld (out/target/product/ventana/obj/EXECUTABLES/helloworld_intermediates/LINKED/helloworld)
     1007target Symbolic: helloworld (out/target/product/ventana/symbols/system/bin/helloworld)
     1008Export includes file: external/helloworld/Android.mk -- out/target/product/ventana/obj/EXECUTABLES/helloworld_intermediates/export_includes
     1009target Strip: helloworld (out/target/product/ventana/obj/EXECUTABLES/helloworld_intermediates/helloworld)
     1010Install: out/target/product/ventana/system/bin/helloworld
     1011}}}
     1012
     10134. Copy exectuable file over to running Android system and run it. For example, the executable was put in the location as defined by the output of the log above: out/target/product/ventana/obj/EXECUTABLES/helloworld_intermediates/LINKED/helloworld.  An example location to put the file on a running Android system on the Gateworks SBC would be /data/system. Use wget or use adb push [wiki:Android/OSDevelopment#adb-push ADB Push Example]
     1014 * use wget on target
     1015{{{#!bash
     1016root@ventana:/data/system # busybox wget http://xxx.xx.xx.11/helloworld             
     1017Connecting to 172.24.10.11 (172.24.10.11:80)
     1018helloworld               100% |*******************************| 87972   0:00:00 ETA
     1019root@ventana:/data/system # chmod 777 helloworld                                     
     1020root@ventana:/data/system # ./helloworld                               
     1021Hello World
     1022}}}
     1023
     1024
     1025[=#overlay]
     1026=== Customizing your target device using overlays ===
     1027The Android build system uses an overlay system that allows files to be replaced on a per-target device basis. This is commonly done to do things like adjust layout specific resources or background wallpapers for a specific device.
     1028
     1029There are two types of overaly directories that affect a product:
     1030 * PRODUCT_PACKAGE_OVERLAYS: used by a particular product
     1031 * DEVICE_PACKAGE_OVERLAYS: used several products that share a common device model The PRODUCT_PACKAGE_OVERLAYS will override the DEVICE_PACKAGE_OVERLAYS if they contain same resources.
     1032
     1033If your product's .mk file defines one of these, any resource file present there will override the resource from the original directory.
     1034
     1035Some examples of where the Gateworks Ventana target uses this:
     1036 * device/gateworks/ventana/overlay/frameworks/base/core/res/res/values/config.xml - override some of the framework base configuration such as to specify eth0 as the ethernet device to monitor link state on for the DHCP service
     1037 * device/gateworks/ventana/overlay/packages/apps/Settings/res/values/config.xml - add additional strings used for Settings application
     1038
     1039
     1040
     1041[=#adb]
     1042== Android Debug Bridge (ADB) ==
     1043Android uses a client/server application for remote debugging referred to as the Android Debug Bridge or adb. This can run over a variety of interconnects including serial, USB, and TCP/IP.
     1044
     1045Common useful adb usages:
     1046 - adb shell - open a shell on target
     1047 - adb reboot bootloader ;# reboot to bootloader
     1048 - adb reboot recovery ;# reboot to recovery
     1049 - adb push <local> <remote> ;# copy file to device (/mnt/sdcard is sdcard)
     1050 - adb pull <remote> <local>
     1051 - adb remount - remote /system r/w
     1052 - adb devices - list devices
     1053 - adb logcat -s <tag>  ;# show log for elements having <tag>
     1054 - adb logcat -s <tag1>:* <tag2>:*  ;# show log for both tag1 and tag2
     1055 - adb shell screencap -p | perl -pe 's/\x0D\x0A/\x0A/g' > screen.png # take a screenshot
     1056
     1057
     1058[=#adb-security]
     1059=== ADB security ===
     1060The ADB Daemon (adbd) typically operates with security in place (ro.adb.secure=1) such that the android target device must grant permissions for devices to operate over ADB.
     1061
     1062Notes:
     1063 - ro.adb.secure=1 # enables security"
     1064 - ~/.android/adbkey.pub is your public key on your Linux development host
     1065 - /data/misc/adb/adb_keys is where they are stored on android target
     1066
     1067Granting access for a specific host:
     1068 * When the Android device is unlocked, any connection to a development host running adbd will throw up a dialog asking if you want to allow access (you can check a box to make it permanent)
     1069 * If you have serial console, you can add access manually:
     1070  1. Get your public key from your development host (***This key is unique for your system - this is only an example***):
     1071{{{#!bash
     1072$ cat ~/.android/adbkey.pub
     1073QAAAAMvdGLUdoLCizqkXt0obRk+pk1ImtXDC2a8HV5s0iY6boxi/0JGRUR0mVlTIRSCA1x8nbbqOdFWEhah+b2kRuvHBLLHUT00IxEjCbkxJsfnxVZ6Aj5AyfLzyl1tq0kdSWw0YFie9iTWCIWZrxbU/ZSIF6EyYx+Nsv7I/gY/KuqTkiMu9f5UVfsEMb5IunBbjsL9/YphSUpOwRpV3kX6bXEjYxog3rUyIC1/EFtAQUrFb59b+EQU7Cop5lEr4v1ZFrIj7sWLRj9JLXHQzaR+Qv1qnQ2AqGsnyfAUSHD9/IanzShrOIs2gtpyzEEY/4geC2ULDZNZbe9GAYINacW3jFtc8dXzEiKEKNb/mUZG21QebU22rqgJ95P44VnIE1OXWyl7qS2/D0snj6HbFCWqEpXqp/eB8o6dAR2ZrqArqc2tKVqdEa7sES7GFJTq5AgK2qjtFmPny3ahT1YYhbIB68vhGN9HoyCyr8rofhHhAHnFR18918iC7B9d+6TSz6KJ0JjpdLgjwo8Xq2WtrZ3VoA1E35ZGv09xMVR7EUIMl46dodEvEmD6Tzy3FhfBqDXhQoCzQCbPLNAZEtZ2vDvyjxo3Do6KG0e0Yl6WKGbX2v7aYWZ4axEDq425M0iGGI486ogvEHyrWSTC00PxVedmYiWpyKkoW2rgb6EE0Y8PPUXU4ncv2SAEAAQA= tharvey@tharvey-gwt.0.0-ga
     1074}}}
     1075  2. append it to /data/misc/adb/adb_keys via shell on target Android device over serial-console
     1076{{{#!bash
     1077root@ventana:/ # echo "QAAAAMvdGLUdoLCizqkXt0obRk+pk1ImtXDC2a8HV5s0iY6boxi/0JGRUR0mVlTIRSCA1x8nbbqOdFWEhah+b2kRuvHBLLHUT00IxEjCbkxJsfnxVZ6Aj5AyfLzyl1tq0kdSWw0YFie9iTWCIWZrxbU/ZSIF6EyYx+Nsv7I/gY/KuqTkiMu9f5UVfsEMb5IunBbjsL9/YphSUpOwRpV3kX6bXEjYxog3rUyIC1/EFtAQUrFb59b+EQU7Cop5lEr4v1ZFrIj7sWLRj9JLXHQzaR+Qv1qnQ2AqGsnyfAUSHD9/IanzShrOIs2gtpyzEEY/4geC2ULDZNZbe9GAYINacW3jFtc8dXzEiKEKNb/mUZG21QebU22rqgJ95P44VnIE1OXWyl7qS2/D0snj6HbFCWqEpXqp/eB8o6dAR2ZrqArqc2tKVqdEa7sES7GFJTq5AgK2qjtFmPny3ahT1YYhbIB68vhGN9HoyCyr8rofhHhAHnFR18918iC7B9d+6TSz6KJ0JjpdLgjwo8Xq2WtrZ3VoA1E35ZGv09xMVR7EUIMl46dodEvEmD6Tzy3FhfBqDXhQoCzQCbPLNAZEtZ2vDvyjxo3Do6KG0e0Yl6WKGbX2v7aYWZ4axEDq425M0iGGI486ogvEHyrWSTC00PxVedmYiWpyKkoW2rgb6EE0Y8PPUXU4ncv2SAEAAQA= tharvey@tharvey-gwtgateworks" >> /data/misc/adb/adb_keys
     1078}}}
     1079
     1080Reference:
     1081 * http://nelenkov.blogspot.com/2013/02/secure-usb-debugging-in-android-422.html
     1082
     1083
     1084[=#adb-install]
     1085=== Installing adb on PC ===
     1086You have several options for installing adb on a Linux / Mac / Windows PC:
     1087 * install from a downloadable package
     1088  * Ubuntu 13.10 and above:
     1089{{{#!bash
     1090sudo apt-get install android-tools-adb
     1091}}}
     1092  * Ubuntu 12.04, 11.10, 11.04 - the latest android tools package is 4.1.1 which has adb v1.0.29 which will does not support the per device authentication mechanism added in Jellybean 4.2+. You can update to the v4.2.2 package containing adb v1.0.31 using a community ppa from https://launchpad.net/~nilarimogard/+archive/webupd8:
     1093{{{#!bash
     1094sudo add-apt-repository ppa:nilarimogard/webupd8
     1095sudo apt-get update
     1096sudo apt-get install android-tools-adb android-tools-fastboot
     1097}}}
     1098   * if you have updated be sure to restart the adb server
     1099 * install the Android SDK
     1100 * build from source
     1101
     1102Common issues:
     1103 * adb devices shows device as 'offline': you have not authenticated the device - go to the target device, unlock it and select 'ok' to the authentication dialog
     1104 * adb devices shows device as 'unauthorized': you need to enable Settings->Developer options->USB debugging
     1105 * adb devices shows device as '???????????? no permissions: this is a usb device permissions issue - restart server as root: adb kill-server; sudo adb start-server
     1106
     1107
     1108[=#adb-otg]
     1109=== adb over USB OTG ===
     1110Probably the most common use of adb is to use it over a USB OTG connection. For example, you can connect a PC Host USB port to the USB OTG (microUSB) connector on a Ventana board.
     1111
     1112Note that to use adb over USB OTG to communicate with an Android Jellybean (4.2+) target device you must:
     1113 * enable USB debugging: Developer options -> USB debugging
     1114 * Authenticate the host device (your PC): When you connect and are not on the lockscreen, you will be presented with a USB Debugging Authentication dialog. You must select 'OK' to allow debugging and you can optionally check the box to remember this device so you don't have to authenticate it every time (in the Developer options -> USB debugging menu you can also revoke prior remembered authentications)
     1115
     1116
     1117[=#adb-net]
     1118=== adb over TCP/IP network ===
     1119To use adb over TCP/IP networking you need to configure the port on the target device either via a serial console, or by using an adb shell from another method such as usb.
     1120
     1121On Android Target Device:
     1122{{{#!bash
     1123setprop service.adb.tcp.port 5555
     1124stop adbd
     1125start adbd
     1126}}}
     1127
     1128On host PC:
     1129{{{#!bash
     1130adb connect <ip>
     1131# authenticate the request on the target device
     1132adb logcat ...
     1133}}}
     1134
     1135Note that an authentication dialog will appear on the Android target device (as long as it not on the lockscreen) after the {{{adb connect}}} - be sure to authenticate or the device will be offline.
     1136
     1137References:
     1138 - http://stackoverflow.com/questions/2604727/how-can-i-connect-to-android-with-adb-over-tcp
     1139
     1140
     1141=== Target device filesystem manipulation via adb ===
     1142If you wish to manipulate files on the target device you must make sure that the filesystem is mounted with read/write permissions.
     1143
     1144For the 'system' partition you can do this using the 'adb remount' command, however note that this only works for 'eng' builds
     1145
     1146
     1147[=#adb-push]
     1148=== Using adb to push your code to your target ===
     1149To push a newly built file to target (ie the cantest app):
     1150{{{#!bash
     1151# push the newly built exe to the target (make sure you push it somewhere you have write permissions for)
     1152adb push out/target/product/ventana/system/bin/cantest /data
     1153adb reboot
     1154}}}
     1155 * Note that adb push pushes the file contents AND '''the file permissions''' from the development host to the target. Therefore, bue sure to check the file permissions once onto the target.
     1156
     1157Note that filesystem permissions apply, so you need to make sure you are pushing to a filesystem that is writable. The /data partition for example is writable, but by default /system is not. If you wish to remount /system read/write you can use adb remount before pushing:
     1158{{{#!bash
     1159adb remount
     1160}}}
     1161
     1162Note that adb can also sync your development output directory with your target which is very handy if you want to push all changes (providing your using the android build system to properly build and install files into the output directory):
     1163{{{#!bash
     1164adb remount
     1165adb sync
     1166adb reboot
     1167}}}
     1168
     1169Note that {{adb sync}}} only works for the system and data partition. If you wish to sync udpdates to the boot partition (kernel, bootscript, dtbs, ramdisk) you can do that with the following command:
     1170{{{#!bash
     1171adb remount
     1172for i in `ls out/target/product/ventana/boot/boot`; do \
     1173  adb push out/target/product/ventana/boot/boot/$i /boot/boot; \
     1174done
     1175adb reboot
     1176}}}