AM335x Android Device Tree Integration

'''  Content is no longer maintained and is being kept for reference only! '''



= Introduction = '''  Content is no longer maintained and is being kept for reference only! '''

This is an effort to integrate the Device Tree(DT) support to am335x android kernel of rowboat open source project.

This work is a based on the latest AM335x Android Devkit release

The DT patches have been validated on BeagleBone(an opensource am335x platform).

Also this wiki assume that the user has followed the Hardware Requirements and the Software Requirements for the same release.

= What is supported =


 * Booting AM335x with Device Tree(DT)
 * DT support for GPIO
 * DT support for LEDS

= Steps to evaluate  =

Downloading Patches

 * Download the DT support patches from HERE

Downloading Android Sources

 * Download latest am335x android sources from gitorious.org/rowboat
 * Follow the guide lines from the Am335x android DevKit DevelopersGuide

For this experiment the user can just download the android kernel and the prebuilt images,


 * Download latest am335x kernel sources from git://gitorious.org/rowboat/kernel.git, checkout branch rowboat-am335x-kernel-3.2
 * Download BeagleBone Prebuilt Images from this Link.

http://software-dl.ti.com/dsps/dsps_public_sw/sdo_tii/TI_Android_DevKit/TI_Android_ICS_4_0_3_DevKit_3_0_1/exports/beaglebone.tar.gz


 * Download RAMDISK file system from this Link.

http://processors.wiki.ti.com/images/5/5a/Ramdisk-pm.gz

Toolchain setup
$ export PATH=&lt;android source path&gt;/prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin:$PATH
 * Setup the toolchain path to point to arm-eabi- tools in prebuilt/linux-x86/toolchain/arm-eabi-4.4.3/bin

Applying DT patches
Extract the downloaded Dt_patches.tar.gz to &lt;android source path&gt;/dt_patches $ tar -xvzf Dt_patches.tar.gz &lt;android source path&gt;/ Apply the DT patches on kernel using "git am" command $ cd &lt;android source path&gt;/kernel

$ git am &lt;android source path&gt;/dt_patches/* To Build Android Linux Kernel

$ cd &lt;android source path&gt;/kernel $ make ARCH=arm CROSS_COMPILE=arm-eabi- distclean $ make ARCH=arm CROSS_COMPILE=arm-eabi- am335x_evm_android_defconfig $ make ARCH=arm CROSS_COMPILE=arm-eabi- uImage uImage-dtb.am335x-evm This will generate dtb(device tree blob) appended uImage-dtb.am335x-evm (kernel image) in kernel/arch/arm/boot folder
 * Change directory to kernel
 * Execute following commands

Preparing Bootable MMC Card
Here we prepare the MMC card with the prebuilt images and replace the kernel image for DT demostration

Procedure to populate MMC/SD Card

$ tar -xvzf beaglebone.tar.gz
 * Get an SD Card of minimum size 2GBytes (Class4 minimum) and a USB Card reader
 * Insert the USB SD Card reader (with SD Card) in your host Linux PC
 * Prepare the MMC/SD card with pre-built images beaglebone.tar.gz downloaded from TI release page

$ cd beaglebone

$ sudo ./mkmmc-android.sh /dev/sd&lt;device&gt; $ cp &lt;android source path&gt;/kernel/arch/arm/boot/uImage-dtb.am335x-evm /media/boot/ $ cp ramdisk-pm.gz /media/boot/
 * Above step will create a bootable MMC/SD card with three partitions namely boot, rootfs and data.
 * Copy the dtb(device tree blob) to the boot partition
 * Copy the RAMDISK image ramdisk-pm.gz to the boot partition
 * Now this MMC/SD card can be unmounted and used for booting the platform

Evaluating DT support
The target platform can either be booted with a RAMDISK or Android File System.

Booting the test platform
U-Boot# U-Boot# setenv bootcmd 'mmc rescan 0; fatload mmc 0 81000000 uImage-dtb.am335x-evm; fatload mmc 0 82000000 ramdisk-pm.gz; bootm 81000000' U-Boot# setenv bootargs 'console=ttyO0,115200n8 mem=128M root=/dev/ram rw initrd=0x82000000,16MB ramdisk_size=65536 earlyprintk=serial debug' U-Boot# boot U-Boot# setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off' U-Boot# setenv bootcmd 'mmc rescan ; fatload mmc 0 82000000 uImage; bootm 82000000' U-Boot# boot
 * Connect USB cable to the mini-USB port(P3) on BeagleBone to the Host PC and have a Terminal software like TeraTerm, Minicom or Hyperterminal.
 * Please refer BeagleBone-Android-DevKit Guide for detailed instructions for serial port setup.
 * Insert Micro SD card into MMC/SD slot on the BeagleBone.
 * Power ON the BeagleBone by connecting power cable to (P5).
 * Press any key at the boot-loader prompt
 * Type the follwing on the U-boot prompt for booting with RAMDISK File System
 * Type the follwing on the U-boot prompt for booting Android File System

How to check Device Tree Support
[ 0.000000] Machine: Generic AM33XX (Flattened Device Tree), model: TI AM335x EVM This indicate that the machine init happened in the device tree model
 * On Boot Log check the line

[ 1.872619] DEBUG*** gpio-leds device tree data
 * On Boot Log check the lines

[ 1.877349] DEBUG*** led.gpio 56

[ 1.881713] DEBUG*** led.active_low 0

[ 1.885986] DEBUG*** led.name beaglebone::status1

[ 1.891876] DEBUG*** led.default_trigger heartbeat

[ 1.896881] DEBUG*** led.default_state 0 This indicate that the leds-gpio driver has parsed the information from the device tree and used it for creating the leds.

export gpiochip0 gpiochip32 gpiochip64 gpiochip96 unexport The gpiochip entries are essentially populated from DT
 * The user LED left to the reset button starts blinking as soon as the boot is finished to indicate that the heartbeat led started functioning.
 * After booting check the directory /sys/class/gpio
 * 1) ls /sys/class/gpio

Boot Loader Loading seperate DTB files along with Kernel Image
In the earlier section,we followed an approach of appending the dtb(device tree blob) to the kernel image.

Here are the steps to get u-boot(boot loader) loading the seperate dtb files along with the uImage. For this the u-boot and the uImage has to be modified further.

Follow the instructions below to add this support to boot loader and kernel

Modifying and Re-building the Boot Loader
$ cd &lt;android source path&gt;/u-boot $ git am Dt_uboot_patch/* $ make CROSS_COMPILE=arm-eabi- distclean $ make CROSS_COMPILE=arm-eabi- am335x_evm_config $ make CROSS_COMPILE=arm-eabi- $ cp u-boot.img /media/boot/
 * Change directory to u-boot in android source path
 * Apply this patch from http://processors.wiki.ti.com/images/1/1b/Dt_uboot_patch.tar.gz
 * Build u-boot
 * Copy the new u-boot image to the boot partition

Modifying and Re-building Kernel
Change to kernel directory $ cd &lt;android source path&gt;/kernel Apply these patches from http://processors.wiki.ti.com/images/4/47/Dt_addtional_patches.tar.gz $ git am Dt_addtional_patches/* Build kernel and two device tree blobs. $ make ARCH=arm CROSS_COMPILE=arm-eabi- distclean $ make ARCH=arm CROSS_COMPILE=arm-eabi- am335x_evm_android_defconfig $ make ARCH=arm CROSS_COMPILE=arm-eabi- uImage am335x-evm.dtb beaglebone.dtb The two dtb files am335x-evm.dtb and beaglebone.dtb will boot on same beaglebone but with different GPIOs for heartbeat LED.

Copy the images to the boot partition $ cp arch/arm/boot/uImage arch/arm/boot/beaglebone.dtb arch/arm/boot/am335x-evm.dtb /media/boot/

Booting uImage with seperate device tree blob
Follow the steps in Booting the test platform to start booting the Beaglebone.

Press any key at the boot-loader prompt U-Boot# Type the follwing on the U-boot prompt for booting with am335x-evm.dtb blob U-Boot# mmc rescan ; fatload mmc 0 82000000 uImage;fatload mmc 0 80000000 am335x-evm.dtb U-Boot# setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off' U-Boot# fdt addr 80000000; fdt resize; bootm 82000000 - 80000000 Observe that user LED 4 is blinking as heartbeat.

Type the follwing on the U-boot prompt for booting with beaglebone.dtb blob U-Boot# mmc rescan ; fatload mmc 0 82000000 uImage;fatload mmc 0 80000000 beaglebone.dtb U-Boot# setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off' U-Boot# fdt addr 80000000; fdt resize; bootm 82000000 - 80000000 Observe that user LED 3 is blinking as heartbeat.

= Pin Ctrl driver support =

In this section we explain how we add/evaluate a simple pinctrl driver which can


 * Fetch a set of padconf/pinmux settings from the device tree
 * Setup the board pins with these settings upon boot

This way, we can specify a different set of padconf/pinmux in each device tree and the pinctrl driver will set them accordingly on boot.

Here are the steps to demonstrate the use of this new pinctrl driver. We follow the same approach of boot Loader loading seperate DTB files along with Kernel Image.

Steps to add pinctrl driver support
$ cd &lt;android source path&gt;/kernel $ git am Dt_pinctrl_patches/* NOTE: These set of patches include Basic DT as well as Pin Ctrl support. Explicit pin muxing for GPIO1_23 and GPIO1_24 in board file has been removed as they were present in the earlier set of patches. Here we do the pinmuxing GPIOs seperately from the device tree data.
 * Follow the section on http://processors.wiki.ti.com/index.php/AM335x_Android_Device_Tree_Integration#Modifying_and_Re-building_the_Boot_Loader to update the boot loader with device tree support
 * Next update the kernel with the new set of DT+PinCtrl patches
 * Change to fresh kernel directory
 * Apply these patches from http://processors.wiki.ti.com/images/f/f8/Dt_pinctrl_patches.tar.gz

$ make ARCH=arm CROSS_COMPILE=arm-eabi- distclean $ make ARCH=arm CROSS_COMPILE=arm-eabi- am335x_evm_android_defconfig $ make ARCH=arm CROSS_COMPILE=arm-eabi- uImage $ make ARCH=arm CROSS_COMPILE=arm-eabi- am335x-evm.dtb beaglebone.dtb $ cp arch/arm/boot/uImage arch/arm/boot/beaglebone.dtb arch/arm/boot/am335x-evm.dtb /media/boot/
 * Build kernel and two device tree blobs.
 * The two dtb files am335x-evm.dtb and beaglebone.dtb will boot on same beaglebone with the following differences
 * am335x-evm device tree include pinmux data for board pin GPMC_A8(GPIO1_24) whereas beaglebone device tree include pinmux data for board pin GPMC_A7(GPIO1_23)
 * They have different GPIOs for heartbeat LED.
 * Copy the images to the boot partition

Booting uImage with seperate device tree blos
Follow the steps in "Booting the test platform" to start booting the Beaglebone.

U-Boot#
 * Press any key at the boot-loader prompt

Booting with am335x-evm.dtb
U-Boot# mmc rescan ; fatload mmc 0 82000000 uImage;fatload mmc 0 80000000 am335x-evm.dtb U-Boot# setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off' U-Boot# fdt addr 80000000; fdt resize; bootm 82000000 - 80000000 root@android:/ # dmesg .... &lt;7&gt;[ 0.275665] pinctrl-simple 44e10800.pinmux: request pin 24 (44e10860) for 44e10800.pinmux
 * Type the follwing on the U-boot prompt for booting with am335x-evm.dtb blob
 * Observe that user LED 4 is blinking as heartbeat.
 * After console comes up type the command "dmesg" to see that the pinctrl-simple driver configure the pinmux for GPIO1_24 padconf

Booting with beaglebone.dtb
U-Boot# mmc rescan ; fatload mmc 0 82000000 uImage;fatload mmc 0 80000000 beaglebone.dtb U-Boot# setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off' U-Boot# fdt addr 80000000; fdt resize; bootm 82000000 - 80000000 root@android:/ # dmesg .... &lt;7&gt;[   0.275604] pinctrl-simple 44e10800.pinmux: request pin 23 (44e1085c) for 44e10800.pinmux
 * Type the follwing on the U-boot prompt for booting with beaglebone.dtb blob
 * Observe that user LED 3 is blinking as heartbeat.
 * After console comes up type the command "dmesg" to see that the pinctrl-simple driver configure the pinmux for GPIO1_23 padconf

= FrameBuffer driver with Device tree and Pinctrl =

In this section we explain how we integrate device tree support to da8xx_lcdc(am335x) framebuffer driver

We add support for the framebuffer driver to


 * Fetch a set of panel settings from the device tree blob
 * Settings specific to the display panel being used, like width, heght, timing etc
 * Fetch a set of lcd config settings from device tree blob
 * Settings specific to the lcd panel to board connection, bits per pixel(bpp), ac_bias, dma burst size etc
 * Fetch the LCD pinmux details from the device tree blob and configure on probe

This way all panel, board pinmux specifics of framebuffer driver are moved to device tree.

Here are the steps to integrate. We follow the approach of boot Loader loading device tree blob along with Kernel Image. We evaluate this on AM335X evm instead of beaglebone.

Steps to Integrate
$ cd &lt;android source path&gt;/kernel $ git am Dt_lcdc_patches/* NOTE: These set of patches include Basic DT, Pin Ctrl and LCDC support.
 * Follow the section on http://processors.wiki.ti.com/index.php/AM335x_Android_Device_Tree_Integration#Modifying_and_Re-building_the_Boot_Loader to update the boot loader with device tree support
 * Next update the kernel with the new set of DT+PinCtrl patches
 * Change to fresh kernel directory(freshly cloned from gitorious.org/rowboat)
 * Apply these patches from http://processors.wiki.ti.com/images/5/50/Dt_lcdc_patches.tar.gz

$ make ARCH=arm CROSS_COMPILE=arm-eabi- distclean $ make ARCH=arm CROSS_COMPILE=arm-eabi- am335x_evm_android_defconfig $ make ARCH=arm CROSS_COMPILE=arm-eabi- uImage $ make ARCH=arm CROSS_COMPILE=arm-eabi- am335x-evm.dtb $ cp arch/arm/boot/uImage arch/arm/boot/beaglebone.dtb arch/arm/boot/am335x-evm.dtb /media/boot/
 * Build kernel and create kernel image and a device tree blob for am335xevm.
 * The dtb file am335x-evm.dtb is created to boot on am335xevm with the lcdc dt support.
 * Copy the images to the boot partition of the SD card

Booting AM335x EVM with uImage and device tree blob
U-Boot# U-Boot# mmc rescan ; fatload mmc 0 82000000 uImage;fatload mmc 0 80000000 am335x-evm.dtb U-Boot# setenv bootargs 'console=ttyO0,115200n8 androidboot.console=ttyO0 mem=256M root=/dev/mmcblk0p2 rw rootfstype=ext4 rootwait init=/init ip=off' U-Boot# fdt addr 80000000; fdt resize; bootm 82000000 - 80000000 root@android:/ # dmesg .... &lt;7&gt;[ 0.300140] pinctrl core: add 1 pinmux maps &lt;7&gt;[ 0.300170] pinctrl-simple 44e10800.pinmux: found group selector 1 for lcdc_pins &lt;7&gt;[ 0.300170] pinctrl-simple 44e10800.pinmux: request pin 41 (44e108a4) for display.4 &lt;7&gt;[ 0.300201] pinctrl-simple 44e10800.pinmux: request pin 42 (44e108a8) for display.4 &lt;7&gt;[ 0.300201] pinctrl-simple 44e10800.pinmux: request pin 43 (44e108ac) for display.4 &lt;7&gt;[ 0.300231] pinctrl-simple 44e10800.pinmux: request pin 44 (44e108b0) for display.4 &lt;7&gt;[ 0.300231] pinctrl-simple 44e10800.pinmux: request pin 45 (44e108b4) for display.4
 * Connect the Serial cable and the Power Cable on AM335X EVM
 * Connect to the board through a terminal software like TeraTerm, Minicom or Hyperterminal to see the console messages.
 * Insert SD card into MMC/SD slot on the AM335X EVM.
 * Power ON the AM335X EVM
 * Press any key at the boot-loader prompt
 * Type the follwing on the U-boot prompt for booting with am335x-evm.dtb blob
 * Observe that the LCDC is coming up with Android Home screen.
 * After console comes up type the command "dmesg" to see that
 * LCDC pinumx configuration is being done

...............

&lt;7&gt;[ 0.300567] pinctrl-simple 44e10800.pinmux: enabling function1 lcdc_pins &lt;6&gt;[ 0.299957] da8xx_lcdc display.4: GLCD: Found TFC_S9700RTWV35TR_01B panel &lt;4&gt;[ 0.299957] PANEL INFO lcdc_info-&gt;width 800 &lt;4&gt;[ 0.299987] PANEL INFO lcdc_info-&gt;height 480 &lt;4&gt;[ 0.299987] PANEL INFO lcdc_info-&gt;hfp 39 &lt;4&gt;[ 0.299987] PANEL INFO lcdc_info-&gt;hbp 39
 * LCDC Panel Data being fetched from DT and printed

&lt;7&gt;[ 0.275665] pinctrl-simple 44e10800.pinmux: request pin 24 (44e10860) for 44e10800.pinmux

................ &lt;4&gt;[ 0.300659] LCD CFG lcd_cfg-&gt;ac_bias 255 &lt;4&gt;[ 0.300659] LCD CFG lcd_cfg-&gt;ac_bias_intrpt 0 &lt;4&gt;[ 0.300689] LCD CFG lcd_cfg-&gt;dma_burst_sz 16 &lt;4&gt;[ 0.300689] LCD CFG lcd_cfg-&gt;bpp 32
 * LCDC Controller data being fetched from DT and printed

............

= Limitations =

In framebuffer support, the patches are not reviewed to put the proper error checks.

= References =

Different DT efforts from linux-omap-pm branches

http://gitorious.org/omap-pm/linux/trees/for_3.2/5_omap_dt_i2c_twl

and

http://gitorious.org/omap-pm/linux/trees/for_3.4/dt_gpio

TI-Android-ICS-4.0.3-DevKit-3.0.1 Links

http://processors.wiki.ti.com/index.php/TI-Android-ICS-4.0.3-DevKit-3.0.1_UserGuide

http://processors.wiki.ti.com/index.php/TI-Android-ICS-4.0.3-DevKit-3.0.1_DevelopersGuide

Pinctrl Support

pinctrl-simple driver https://lkml.org/lkml/2012/5/2/275

Mainline kernel

http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=tag;h=refs/tags/v3.4

= Future Work =

Will update soon