wiki:Device Porting Guide

Introduction

If you have a device that is not supported yet by SHR and that you still want to run SHR on it, this guide is for you.

Exploration phase

The first steps are to boot an existing SHR image to find the kernel interfaces (often the machine specific kernels have some non-standard interfaces) and to tweak the existing image.

# cat /proc/cpuinfo 
Processor       : ARMv7 Processor rev 2 (v7l)
BogoMIPS        : 535.01
Features        : swp half thumb fastmult vfp edsp thumbee neon 
CPU implementer : 0x51
CPU architecture: 7
CPU variant     : 0x0
CPU part        : 0x00f
CPU revision    : 2

Hardware        : mahimahi
Revision        : 00aa
Serial          : 0000000000000000

Here we can see several things:

  • the machine name is mahimahi (that information will be used in many places)
  • the CPU is an armv7 (that information will be used later in the machine configuration file in openembedded)

Then go in /etc/freesmartphone/conf/ and add a directory with the name of your machine (mahimahi in our case) and copy inside the configurations from a similar machine, and tweak the configurations.

Initial (upstreaming) steps

SHR uses extensively the following project:

  • The Freesmartphone middleware
  • The Openembedded build system

We will add the freesmartphone configurations first, in order to make openembedded pick them once they are upstream.

Add the freesmartphone configurations

  • add frameworkd.conf (with most of the things disabled but opimd and opreferenced) and  rules.yaml in  the frameworkd repository
  • clone  cornucopia and add the configurations in /conf/yourmachine/ inside each daemon. In our case we add:
    • fsodeviced/conf/nexusone/fsodeviced.conf
    • fsogsmd/conf/nexusone/fsogsmd.conf
    • fsousaged/conf/nexusone/fsousage.conf
    • fsotdld/conf/nexusone/fsotdld.conf

After that we need to activate these configurations:

For each daemon:

  • verify that you have the correct configuration, in our case it will be in fsodeviced/conf/nexusone/fsodeviced.conf
  • Add a Makefile.am in the machine configuration directory, for instance fsodeviced/conf/nexusone/Makefile.am
  • Add your machine configuration in the daemon's config Makefile.am like that:
    --- a/fsodeviced/conf/Makefile.am
    +++ b/fsodeviced/conf/Makefile.am
    @@ -8,6 +8,7 @@ SUBDIRS = \
            htc_qualcomm_msm \
            htcleo \
            motorola_ezx \
    +       nexusone \
            nokia_n900 \
            openmoko_gta \
            palm_pre \
    
  • add the Makefile in configure.ac like that:
    --- a/fsodeviced/configure.ac
    +++ b/fsodeviced/configure.ac
    @@ -167,6 +167,7 @@ AC_CONFIG_FILES([
       conf/htc_qualcomm_msm/Makefile
       conf/htcleo/Makefile
       conf/motorola_ezx/Makefile
    +  conf/nexusone/Makefile
       conf/nokia_n900/Makefile
       conf/nokia_n900/alsa-default/Makefile
       conf/openmoko_gta/Makefile
    

Note that the symlinks are made inside fsodeviced/conf/nexusone/Makefile.am in our case (nexusone → mahimahi)

Bare minimum in Openembedded

  • create a machine configuration for your machine in conf/machine/
  • create a kernel recipe (recipes/linux/ for your machine and point to in your machine configuration (conf/machine/):
    • if your device is an android one:
      • add g_ether (so you can ssh into your phone) compiled in the kernel (easier debugging)
      • remove paranoid network
      • remove the initramfs/initrd
  • add  /etc/network/interfaces and bump PR of the netbase recipe

devtmpfs vs udev

Add devtmpfs or udev or mdev for your device (devtmpfs is better but require a 2.6.32 kernel):

devtmpfs

  • add devtmpfs in your kernel if possible (if not possible add udev) and also add the option for mounting it:
  • add a line like that one in recipes/images/shr-image.inc if you have devtmpfs (replace nexusone with the name of your machine in openembnedded):
    IMAGE_DEV_MANAGER_nexusone = ""
    

udev

If you have an older kernel than 2.6.32 your only options are udev and mdev, udev won't work out of the box since recent udevs require recent kernels. Fortunately there is a way to have a compatibility udev for older kernels:

  • add that in your machine config:
    PREFERRED_PROVIDER_udev-compat = "udev-compat141"
    
  • Add the following in the most recent udev recipe, replacing yourmachine by the machine name you chose (the name of the .conf in conf/machine):
    RDEPENDS_udev_yourmachine += "udev-compat"
    do_unpack_append_yourmachine() {
    	bb.build.exec_func('do_apply_compat_wrapper', d)
    }
    

if you have an older kernel and you don't do that, the device will block during the boot. Mdev can also work as a temporary solution.

More openembedded tweaks

  • Add  Xorg.conf and bump PR of the xserver-xorg-conf recipe
  • If your device has a touchscreen that is not calibrated, you need to add  /etc/pointercal.xinput (and bump PR). To add /etc/pointercal.xinput do that:
    • install evtest:
      opkg install evtest
      
    • run evtest and look at the minimum and maximum x and y coordinates, write them down (let's call them min_x, max_x,min_y and max_y)
    • start Xorg with a valid xorg.conf and be sure it's started:
      Xorg -retro
      
    • run xinput_calibrator --list and find out your touchscreen(s) name. Here's an example of output:
      xinput_calibrator --list
      Device "ts4" id=6
      
    • run xinput_calibrator, replace 3602 4062 258 3869 with min_x, max_x,min_y, max_y and replace ts4 with your touchscreen name
      xinput_calibrator -v --device ts4 --precalib 3602 4062 258 3869 --output-type xinput
      
    • copy the output of the previous command  in openembedded and  bump PR
  •  Change the DPI, look at the DPI list  on Wikipedia page for a list of known DPI
  • if you don't have a  trackball on your phone you need to disable the X11 cursor in /etc/X11/xserver-common like this (where machine id is the name of the hardware you from /proc/cpuinfo)
    [...]
    "<machine-id>")
       DPI="<your-dpi>"
       ARGS="$ARGS -dpi ${DPI} -nocursor"
       ;;	
    [...]
    

Nand installation

JFFS2

jffs2 ERASEBLOCKSIZE can be found by that command:

root@om-gta04:~# cat /proc/mtd 
dev:    size   erasesize  name
mtd0: 00080000 00020000 "X-Loader"
mtd1: 001e0000 00020000 "U-Boot"
mtd2: 00020000 00020000 "U-Boot Env"
mtd3: 00400000 00020000 "Kernel"
mtd4: 1f980000 00020000 "File System"

Here the erase block size is 0x20000

Ubifs

Look at the comments in om-gta02.conf machine config for more information.