Setting up CPU transparency and sbrsh with your device

Introduction

This document has been reviewed for maemo 3.x.

CPU transparency is a technique where ARMEL binaries are copied from the Linux PC side over the USB cable to the device where the binary is then executed natively by the Internet Tablets own ARM CPU. This is a handy way to test your ARMEL-binaries in a native ARM CPU instead of running them in Linux PC under the QEMU emulator. The QEMU emulator may not be identical with the real ARM device so using CPU transparency with the real device is a convenient way to test drive your ARMEL application.

Text output (console output) of the running program is display inside the scratchbox environment but if the application is using X11 Windowing System then the X11 DISPLAY variable will dictate where the graphical output is transmitted.

Following the instructions in this document you can set up sbrsh (=ScratchBox Remote SHell) CPU transparency for the Scrachbox target named "SDK_ARMEL". Please take into note that the use of sbrsh is insecure. You should only run it on trusted networks.

Prerequisites

Prerequisites to be able to set up CPU transparency are:

1. The Scratchbox Apophis R4 version. CPU transparency is supported also in older scratchbox versions but this document refers to the Scratchbox Apophis R4 version.
2. Scratchbox ARMEL target named "SDK_ARMEL" with sbrsh set as the CPU transparency method (you can set up targets using the sb-menu command inside scratchbox)
3. Device flashed with the maemo developer rootfs
4. Networking set up using static IP addresses 192.168.2.15 on the device and 192.168.2.14 on the host Linux PC computer, as desribed in the Setting up USB networking to your device.

Setting up your host Linux PC environment

To setup your host environment you need to run the following commands with root access.

1. Install NFS kernel server in your Linux PC. In Debian, this is provided by the package nfs-kernel-server. Fetch the required software by running the command:

   $ apt-get install nfs-kernel-server
   	  
   

   If the package is not found you may have to edit your local /etc/apt/sources.list file.

2. Edit the /etc/exports file in your Linux PC. This file lists the NFS file systems that will be exported to the device. Add the following line (replace sbox_username, sbox_user_uid and sbox_user_gid with correct values ie use your own user names and IDs):

       
   /scratchbox/users/<sbox_username>/targets/ 192.168.2.15(rw,all_squash,anonuid=<sbox_user_uid>,anongid=<sbox_user_gid>,sync)
   /scratchbox/users/<sbox_username>/home 192.168.2.15(rw,all_squash,anonuid=<sbox_user_uid>,anongid=<sbox_user_gid>,sync) 
   
   

   Make sure that the user IDs used in the /etc/exports file in Linux Pc side match to those user IDs that are effective inside the Scratchbox.
3. Restart NFS kernel server to apply new exports:

   	    
   root@host:~ # /etc/init.d/nfs-kernel-server restart
   * Stopping NFS kernel daemon...                                                         [ ok ]
   * Unexporting directories for NFS kernel daemon...                                      [ ok ]
   * Exporting directories for NFS kernel daemon...                                        [ ok ]
   * Starting NFS kernel daemon:                                                           [ ok ]
   root@host:~ #
   	  
   

Now your Linux PC host system should be set up.

Setting up your ARMEL target in scratchbox

Now you need to setup your ARMEL target inside scratchbox. To do this, first start scratchbox and change to the ARMEL target if necessary.

user@host:~$ /scratchbox/login

Welcome to Scratchbox, the cross-compilation toolkit!

Use 'sb-menu' to change your compilation target.
See /scratchbox/doc/ for documentation.

[sbox-HOST: ~] > sb-conf select SDK_ARMEL
Restarting Scratchbox shell...
Hangup
Shell restarting...
[sbox-SDK_ARMEL: ~] >
      

Then edit the ~/.sbrsh in Scratchbox user's home directory, adding the following lines (replace "password" with a password used for cpu transparency and replace "username" with the real username using the Scratchbox):

SDK_ARMEL 192.168.2.15 <password>
nfs     192.168.2.14:/scratchbox/users/<username>/targets/SDK_ARMEL  / rw,nolock,noac
nfs     192.168.2.14:/scratchbox/users/<username>/home /home rw,nolock,noac
bind    /dev          /dev
bind    /dev/pts      /dev/pts
bind    /proc         /proc
bind    /tmp          /tmp
	

If you are using the sb-menu command in Scratchbox and set the sbrshd settings with that tool make sure that you do not use the term localhost but instead use the full IP address of your Linux PC.

Note, that if the network connection between the Tablet and Linux PC break and the Scratchbox is trying to push the required configurations to the device it does not give any warning of failure. Check always from the device that the configurations are in place.

With these changes your SDK_ARMEL target should be set up accordingly.

Setting up CPU transparency in the device

Next you need to enable CPU-transparency in the device. Go to the device Control-Panel and start the maemo-usbnet-chooser application.

In image below you can see the dialog and you need to check cpu-transparency option as "ON".

If you are using sbrshd version provided by maemo (installed by default to development rootfs), you don't need to do anything else.

When using CPU-transparency first time you will get a pop-up dialog in your device that asks about creating a new user. Click "YES".

If you are using sbrshd version provided by maemo then you can jump to next section. Our version of sbrshd takes care of creating needed users and configuring itself so these steps are not needed. If you use sbrshd coming with scratchbox then you need these steps.

After this you should add a new user to the device that will use the Developer Platform. You can do this with the adduser command by giving the user name you want after it. You need to define also --shell, because default shell is bash and we don't have it installed. See examples below.

	
NokiaN800:~# adduser --shell /bin/sh username
Adding user username...
Adding new group username (1001).
Adding new user username (1001) with group username.
Creating home directory /home/username.
Copying files from /etc/skel
find: !: No such file or directory
Changing password for username
Enter the new password (minimum of 5, maximum of 8 characters)
Please use a combination of upper and lower case letters and numbers.
New password:
Re-enter new password:
Password changed.
Changing the user information for username
Enter the new value, or press ENTER for the default
Full Name []:
Room Number []:
Work Phone []:
Home Phone []:
Other []:
Is the information correct? [y/n] y
NokiaN800:~#

      

Now you need to add a line to ~/.sbrshd. In the addition provide the same password which was added under scratchbox before. The line added there is:.

	
nokiaN800:~# su - username

BusyBox v1.1.3 (Debian 3:1.1.3-3.osso17) Built-in shell (ash)
Enter 'help' for a list of built-in commands.

~ $ echo "192.168.2.14 <passwd>" > .sbrshd
~ $

	

Now you should exit to root shell, and restart sbrshd, as shown below

 
~ $ exit
nokiaN800:~# /etc/init.d/sbrshd restart
Stopping Scratchbox Remote Shell daemon: done.
Starting Scratchbox Remote Shell daemon: done.
nokiaN800:~#

Finally you can log out from the device.

Test the CPU Transparency

Now the CPU transparency should be set up. To test it log into scratchbox and change to the ARMEL target. Run the command

[sbox-ARMEL: ~] > sb-conf select SDK_ARMEL

After this, extract the hello-world.tar.gz package and go the hello-world directory and run autogen.sh and make and after this run ./hello. This should print the text hello world on your console.

	
[sbox-ARMEL: ~] > tar xfz /scratchbox/packages/hello-world.tar.gz
[sbox-ARMEL: ~] > cd hello-world
[sbox-ARMEL: ~/hello-world] > ./autogen.sh
+ aclocal
[... output from aclocal ...]
+ autoconf
+ autoheader
+ automake --add-missing --foreign
[... output from automake ...]
+ ./configure
[... output from ./configure ...]
[sbox-ARMEL: ~/hello-world] > make
make  all-am
make[1]: Entering directory `/home/username/hello-world'
if gcc -DHAVE_CONFIG_H -I. -I/home/username/hello-world -I.     -g -O2 -MT main.o -MD -MP -MF ".deps/main.Tpo" -c -o main.o main.c; \
then mv -f ".deps/main.Tpo" ".deps/main.Po"; else rm -f ".deps/main.Tpo"; exit 1; fi
gcc  -g -O2   -o hello  main.o
make[1]: Leaving directory `/home/username/hello-world'
[sbox-ARMEL: ~/hello-world] > ./hello
Hello World!
[sbox-ARMEL: ~/hello-world] >
      

The program is run transparently on the device though. You can verify that by the log written to /tmp/cputransp_username.log

[sbox-ARMEL: ~/hello-world] > cat /tmp/cputransp_username.log
[2005-10-13 17:37:26 26032] method: "sbrsh"  pwd: "/home/username/hello-world"  cmd: "/home/username/hello-world/a.out"

[2005-10-13 17:37:30 26032] rc: 0  time: 3.944084
[2005-10-13 17:37:30 26272] method: "sbrsh"  pwd: "/home/username/hello-world"  cmd: "/home/username/hello-world/conftest"
[2005-10-13 17:37:31 26272] rc: 0  time: 0.196024
[2005-10-13 17:37:42 26596] method: "sbrsh"  pwd: "/home/username/hello-world"  cmd: "/home/username/hello-world/hello"

[2005-10-13 17:37:42 26596] rc: 0  time: 0.192171
[sbox-ARMEL: ~/hello-world] >
      

As expected, "rc" contains the result of the remote running program, and "time" contains the total running time on the device. Any sbrsh errors are also output to this file.