Using the Simulator ^TOP^

Command-Line Options for Starting the Simulator ^TOP^

There are a number of command-line options that can be used when launching the Simulator. Use the --help option to display a complete list of options.

alp-simulator --help

Other options are:

--factory-reset

Boot in "factory reset" mode, deleting all data.

--rescue-mode

Boot in minimal "rescue mode", for fixing system problems.

--nat

Configure iptables for NAT forwarding to UML and copy DNS info (the host's resolv.conf) into the rootfs.

See "Networking" for more information on this option.

--net

Create host network bridge (br0) and connect to eth1 in UML. Like --nat, this option also configures iptables for NAT forwarding to UML and copies DNS info (the host's resolv.conf) into the rootfs.

The UML_NET_IFACE environment variable overrides the host physical connection default (eth0 in most cases). The UML_NET_IP environment variable assigns a static IP to br0 instead of using DHCP.

See "Networking" for more information on this option.

--net-nonat

Same as --net but without the effects of --nat.

--keep

Leave the host network bridge up after UML exits. This option is for use with the --net or --net-nonat options.

--noninteractive

Boot UML with no sudo commands or prompts. This option is intended primarily for Eclipse or automation.

--serial

Configure serial ports ttyS0 and ttyS1 for UML. If a USB serial device is connected as /dev/ttyUSB0, it replaces the ttyS0 serial port in UML.

The UML_TTYS0_SPEED environment variable overrides the default port ttyS0 speed of 115200. The UML_TTYS1_SPEED environment variable overrides the port ttyS1 default speed of 19200.

--skin [name]

Enable a Simulator device skin. Use the default skin unless name is specified or the UML_DEVICE_SKIN variable is set (in which case it is not necessary to use the --skin option).

--no-skin

Disable any Simulator device skin that may have been specified using the UML_DEVICE_SKIN environment variable.

--list-skins

Display the list of available device skins.

--ROM-image file

Boot using the specified ROM image file (ext2 on /dev/ubda).

--var-image file

Mount the specified read/write /var image file (ext2 on /dev/ubdc).

--var

Automatically create and use the default read/write /var image. The UML_VAR_SIZE environment variable overrides the default size (in MB) of 64. A target-specific var image will be created and used. Use "--var" or "--var-image file" but not both. To reset (clear) the var image, use
"--factory-reset".

The --var option is enabled by default; to disable it, use --novar.

--novar

Do not create and use a default target-specific /var image. Instead, use /var from the root filesystem.

--append-cmdline str

Append the specified string to the UML kernel command line. For example, str could be "ubdd=/path/to/image.ext2".

--kernel-config

Displays the configuration file from which the UML kernel was built.

--kernel-version

Displays the UML Linux kernel version information.

-v | --version

Display version information (using "alp-versions").

Environment Variables ^TOP^

There are a couple of environment variables that can be set to alter the default behavior of the ACCESS Linux Platform Simulator:

UML_TARGET, UML_ROOT

By default the Simulator boots the Scratchbox target named "alp-simulator" unless the UML_TARGET or UML_ROOT variables are defined. Use UML_TARGET to specify the Scratchbox target to boot. Use UML_ROOT to specify a path to the UML root filesystem. For example:

export UML_TARGET=my-simulator

or

export UML_ROOT=/path/to/uml/rootfs

UML_DIR

This variable allows you to specify an alternate path to the UML binary. By default, the command alp-simulator runs /opt/alp-dev/lib/alp-simulator.

UML_MEM

Specifies the amount of physical memory the Simulator is launched with. By default, it is launched with 64 MB of physical memory. To change it, for instance to 256 MB:

export UML_MEM=256M

UML_NET_IP

When the --net option is used the bridge is configured using DHCP unless the environment variable UML_NET_IP is set, in which case the bridge is statically configured using the value of UML_NET_IP.

UML_NET_IFACE

When the --net option is used, during configuration of the bridge if the environment variable UML_NET_IFACE is set its value is taken as the bridge endpoint on a LAN (i.e., if you have several Ethernet cards).

DISPLAY

The DISPLAY variable specifies the X display server. For example:

DISPLAY=192.168.108.123:0.0 alp-simulator

UML_XSCREEN

The screen number to be used by the UML internal Xephyr is :0. An alternate may be provided by defining UML_XSCREEN, like this:

UML_XSCREEN=:1 alp-simulator

PALMSOURCE_COMPORT_VP

By default, the UML environment expects to contact the Virtual Phone program at 192.168.3.100. An alternate address can be provided by defining PALMSOURCE_COMPORT_VP:

PALMSOURCE_COMPORT_VP=192.168.108.123

PALMTRACE_TARGET

If the trace facility is configured to output to "tcp:", with no host specified, the trace facility looks to the PALMTRACE_TARGET variable for the host and optional port number of the trace target (Palm OS Reporter).

Networking ^TOP^

The first time you run the Simulator with the --nat option, it is configured so that subsequent runs of the Simulator should support networking without you having to again specify the --nat option.

Use the --nat option for:

• Virtual Phone (running on a different machine)
• Palm Reporter
• Cygwin/X
• gaining access to your local network or the Internet from inside UML without using the Connection Manager (or applications that use it).

The --nat option turns your Ubuntu computer into a gateway for your UML. DNS servers are copied inside the UML rootfs.

Use the --net option for:

• gaining access to your local network or the Internet from inside UML through the Connection Manager (or applications that use it).

The --net (as opposed to --nat) option enables an Ethernet connection with the Connection Manager (or applications that use it). This option has the following effects:

• Sets your Ethernet connection down on your Ubuntu computer.
• Creates a bridge between your Ethernet card and a virtual interface.
• Configures the bridge. This is done using DHCP unless the environment variable UML_NET_IP is set, in which case the bridge is statically configured using the value of UML_NET_IP. If the environment variable UML_NET_IFACE is set, its value is taken as the bridge endpoint on a LAN (i.e. if you have several Ethernet cards).
• Launches a virtual switch (which is connected to the virtual connection) in a new xterm. The window appears when you start the Simulator.
• Starts UML with an additional Ethernet interface (eth1) which is connected to the virtual switch. The --net-keep option skips this step but performs the others, allowing for faster starts the next time you start the Simulator with either --net or --net-keep.

When you halt UML, the virtual switch is killed, the bridge is destroyed, and your Ethernet is restored.

The --net option automatically includes --nat. To get the --net option without the effects of --nat, use the --net-nonat option instead.

Debugging Drawing ^TOP^

From the Xephyr ReadMe file:

Send a SIGUSR1 to the server (e.g. "kill -USR1 `pidof Xephyr`" from a target shell) to toggle the debugging mode. In this mode red rectangles are painted to screen areas getting painted before painting the actual content. The delay between this can be altered by setting a XEPHYR_PAUSE environment variable to a value in microseconds.

Operating the Simulator ^TOP^

Table 11.1 identifies how some of your computer's keyboard keys are mapped to special functions in the Simulator.

Table 11.1  Simulator feature to keyboard mapping 

Entering Unicode Characters

To enter a Unicode character, hold down the Control and Shift keys while entering the Unicode code point. For example:

• While holding Ctrl+Shift, press 2, 0, A, C to enter the Euro character.
• While holding Ctrl+Shift, press 6, 7, 0, 8 to enter the Chinese moon/month character.

Restricting the Cursor to the Simulator Window

The Control and Shift keys, when held while entering hexadecimal values, allow you to "type" Unicode characters. If you press the Control and Shift keys and then release them without entering a hexadecimal value, however, the cursor will be "locked" to the Simulator window; you will be unable to move it beyond the bounds of the window.

Press the Control and Shift keys and then release them to "unlock" the cursor, allowing it once again to escape the bounds of the Simulator window.

Exiting an Application

Return to the home screen by pressing the Home key on your computer's keyboard.

Connecting to the Simulator ^TOP^

To connect to the Simulator from a separate host shell prompt, enable network connectivity (see "Networking") and type:

telnet 192.168.3.101

Using the Debugger ^TOP^

These instructions are intended for use with the Scratchbox build environment provided with the ACCESS Linux Platform SDK. These instructions can be used with either the UML ("Simulator") target environment or an ARM target device.

There are three types of binaries that we care about debugging: Linux executables (e.g., servers or daemons), Linux shared libraries, and ACCESS Linux Platform applications. ACCESS Linux Platform applications are really Linux shared libraries, although they are usually built and packaged (along with resources, an icon, and an XML manifest file) into a single .bar file. For this reason ACCESS Linux Platform applications are more than just a Linux shared library.

These instructions focus on debugging ACCESS Linux Platform applications. With minor modifications (where noted), the information here should also be useful for debugging servers.

The Scratchbox environment is for building native target executables and ACCESS Linux Platform applications. Scratchbox is not for executing any built executables except for those required to run as part of the build process. Because the building and running of ACCESS Linux Platform applications is not supported on the Ubuntu host, all debugging is effectively "remote" debugging.

The Simulator is a remote target, with its own (private) IP address of 192.168.3.101. The target hardware is a remote target as well, with its own (private) IP address of 192.168.1.101.

GDB ^TOP^

Each Scratchbox toolchain is delivered along with a GDB (6.1) executable configured and built for the specific target architecture. This "scratchbox-gdb" is somewhat dated, but it does run in Scratchbox. This is important since any fully-specified paths that it gets from the target or symbol information for sources can easily be located within Scratchbox.

Note that there is, of course, a generic host-provided GDB, but it only works for x86 binaries and is not necessarily configured to work with the same gcc and glibc that ACCESS Linux Platform uses. Accordingly, it isn't used in ACCESS Linux Platform application development.

gdbserver ^TOP^

gdbserver is a control program which allows you to connect your program with a remote GDB connection. gdbserver runs on your remote target, while GDB runs on your host and talks to the remote gdbserver. For complete information on remote debugging using GDB and gdbserver, see http://sources.redhat.com/gdb/current/onlinedocs/gdb_18.html#SEC162.

On ACCESS Linux Platform all debugging is remote debugging. That means that you'll be running gdbserver against a Linux executable (or attaching to an already-running process) on the target device (or Simulator or Emulator), and then connecting to that gdbserver via TCP/IP from GDB running in Scratchbox.

Debugging ACCESS Linux Platform Applications ^TOP^

Because ACCESS Linux Platform applications are Linux shared libraries, they cannot be launched in a process from a shell or by gdbserver.Instead, they must be launched by the Application Manager. Fortunately, the Application Manager knows how to launch an ACCESS Linux Platform application as well as how to hold it for debugging. Note that before you can launch or debug an application, the package must be installed into the target file system (/opt/alp/packages) and registered with the Package Manager. By using a makefile similar to those employed by the sample applications (see "Writing the Makefile" for a detailed examination of one of these makefiles), all of the details of communicating with your remote target are handled for you. Simply issue the following commands in a Scratchbox shell to build and begin debugging your application:

sbox$ make install 
sbox$ make debug 

The first command, make install, builds, copies, and registers the application with the Package Manager. The make debug command then launches the application for debugging, attaches to gdbserver, and runs GDB.

TUI Mode

GDB is a command-line debugger. For a somewhat more graphical experience, you can enable "Text User Interface" (TUI) mode. TUI is a terminal interface which uses the curses library to show the source file, the assembly output, the program registers, and GDB commands in separate text windows. From within GDB, you can enter TUI mode by pressing CTRL+X and then pressing the "A" key. (There are a number of ways to enter TUI mode; see TUI Key Bindings at http://sources.redhat.com/gdb/current/onlinedocs/gdb_23.html#SEC235.)

Documentation on TUI mode can be found at http://sources.redhat.com/gdb/current/onlinedocs/gdb_23.html#SEC233.

Debugging Executables ^TOP^

When debugging, you usually will be debugging an ACCESS Linux Platform application as described above. However, there are times when you need to debug a Linux executable or attach to an existing process. This section describes how to do that.

Starting gdbserver on the Remote Target

There are two ways to start a gdbserver session on your remote target: you can either launch a process, or you can attach to a running process. Either way, you will need some sort of target shell to do this.

Launch a Process

To use the server, you must tell it how to communicate with GDB, the name of your program, and the arguments for your program. The usual syntax is:

gdbserver :portNo program [ args ... ]

portNo is the port number on which to passively wait, waiting for a host GDB to communicate with it. Use a port such as 5050 if you are doing this manually.

Attach to a Running Process

This is accomplished via the --attach argument. The syntax is:

gdbserver :portNo --attach pid

where pid is the process ID of a currently running process and portNo is the port number on which to passively wait, waiting for a host GDB to communicate with it. Note that when attaching to a running process, you needn't indicate a binary for the running process.

Starting GDB

In Scratchbox, launch GDB. You must provide the name of the executable that you are debugging. If you are debugging an ACCESS Linux Platform executable (that is, a server; not an ACCESS Linux Platform application), the executable is probably located in /opt/alp/bin.

sbox$ gdb /opt/alp/bin/my_server 

Once in GDB, you may need to type the following to tell GDB how to locate any libraries that aren't in the standard (target) LD_LIBRARY_PATH:

(gdb) set solib-search-path /home/user.name/path/to/my_libraries 

Note that when running GDB inside Scratchbox, you will get the correct GDB for the currently selected Scratchbox target configuration (x86 or ARM, as per your sb-conf current target setting).

Creating a .gdbinit file

If you find yourself typing a lot of the same text over and over again each time you launch GDB, you may wish to create a .gdbinit (for example, uml.gdbinit) setup file and specify it when launching GDB:

host$ alp-gdb /opt/alp/bin/my_server --command=my_server.gdbinit 

Connecting GDB to gdbserver

From within GDB, connect to a particular gdbserver by supplying its IP address and port to the target remote command, like this:

(gdb) target remote 192.168.3.101:5050 

Set a breakpoint on your entry point (or wherever you wish to stop), and tell the target to continue:

(gdb) b file.c:main 
(gdb) cont 

Following this, the target should hit the specified breakpoint and you should be able to use GDB to debug the target.

Tracing ^TOP^

Traces are widely used by developers as an aid to developing and debugging their code. Although traces could be used to inform the end-user, this is not their primary objective.

Trace Manager is not a debugger tool and is not a postmortem debugger. It is only a "generator" of alphanumeric messages, not a tool that follows process life and behavior. Traces contain a ClassID parameter that allow you to filter the traces that are output. By default traces are sent to a file in the device's file system, but they can be redirected to various transports, including stderr, TCP, and file.

Trace Manager can produce traces for any components, for purposes of testing and debugging. Traces can be enabled or disabled either globally or on a per-application basis, through the use of a configuration file (/etc/traces/traces.conf). Traces can be enabled or disabled either at compile time or at runtime.

Trace Manager is a Linux library. Thus, native Linux components (like daemons) can use the trace mechanism.

Using Traces ^TOP^

To use Traces in your code, you need at least two files: libalp_traces.so (the main library) and traces.h (located in include/alp).

The following should be included at the beginning of your header or source file:

... 
/*-----------------------------------------------------------
*/ 
/* file needed to get the ALP_TRACE define                   
*/ 
#include <alp/config_defines.h> 
 
/*-----------------------------------------------------------
*/ 
/* Uncomment the next line to disable traces AT COMPILE TIME 
*/ 
// #define ALP_TRACE ALP_TRACE_OFF   //Enable/disable 
 
/*-----------------------------------------------------------
*/ 
/* Required header file to use the traces                    
*/ 
#include <alp/traces.h> 
... 

You can define a specific class for your component. Having a specific class allows easy output filtering, as described in "Filtering." The following is an example of a trace class definition:

... 
/*  Define Application Trace Class. */ 
#define testTraceClass ALP_TRACE_DEFINE(ALP_CLASS_UNDEFINED, 7) 
... 

This code defines a macro that can invoked to generate a trace at the beginning of any function. Note how it is designed to only generate the trace output if the application is built for debugging.

... 
#if BUILD_TYPE == BUILD_TYPE_DEBUG 
#define testtracesDbgBeginProc(func) 
ALP_TM(TL(testTraceClass, "%s: Processing...", #func)); 
#else 
#define testtracesDbgBeginProc(func) 
#endif 
... 

Tracing APIs ^TOP^

In your C source files, the call to output traces is:

ALP_TM(tracesType(class, fmtString,...))

For example,

ALP_TM(TL(testTraceClass, "This is a test."));

Use the following patterns for tracesType:

ALP_TM(T (AppClassId? , "format", ...))

Display a trace "printf-like".

ALP_TM(TL (AppClassId? , "format", ...))

Display a trace "printf-like," with a CRLF at the end of the output.

ALP_TM(B (AppClassId? , addr, count))

Display a binary (non-printable ASCII) buffer.

ALP_TM(VT (AppClassId? , "format", va_list))

Display a trace "printf-like," using a va_list as the third argument.

ALP_TM(VTL(AppClassId? , "format", va_list))

Display a trace "printf-like," using a va_list as the third argument, with a CRLF at the end of the output.

The format string (fmtString) should be structured as follows:

% flags width type

Supported flags:

Supported types:

AppClassId should define which class your component belongs to. All classes are defined in alp/sysclass.h. Currently, the following classes are defined:

• ALP_CLASS_UNDEFINED
• ALP_CLASS_APPSERVER
• ALP_CLASS_BLUETOOTH
• ALP_CLASS_EXCHANGE
• ALP_CLASS_NOTIFY
• ALP_CLASS_PACKAGE
• ALP_CLASS_PDIUDA
• ALP_CLASS_SAL
• ALP_CLASS_TELEPHONY
• ALP_CLASS_MUX
• ALP_CLASS_MOBILE

A Bluetooth component (like the Bluetooth Panel) could be defined as follows, for example:

#define MyBTPanelClass	
ALP_TRACE_DEFINE(ALP_CLASS_BLUETOOTH, 3)

This definition specifies that traces for the Bluetooth Panel be generated with a class of 0x03000003. Filtering can be done on ALP_CLASS_BLUETOOTH.

Classes are grouped into defined ranges, Within a given range, however, there's no way to avoid "collisions" (the same value used by more than one component). The ranges are defined as follows:

Setup ^TOP^

All settings regarding traces are stored in /etc/traces/traces.conf in the device's file system. Accordingly, if you are running the Simulator, edit /etc/traces/traces.conf from within Scratchbox (not from a "normal" shell that sees the main Linux file system).

Sections and keys are case sensitive. Comments are automatically removed. The traces.conf file is automatically created if it does not exist.

By default, trace output is sent to stderr. To redirect the output, update the OUTPUT key:

[SETTINGS] 
OUTPUT=stderr 

Possible values for this key are:

tcp:destination:port

Send output to a distant Reporter through TCP. The IP/port string refers to the running Reporter (Reporter can be used locally, using Wine). The default value for the IP/port string is "localhost:25998"
OUTPUT=tcp:coder1.palmsource.com:12345

file

Traces are send to a text file. By default, they are sent to /etc/traces.txt.
OUTPUT=file:/etc/mytraces.txt

stderr

Output in raw format to stderr.

syslog

Traces are written to the system SYSLOG daemon, to a syslog file (currently, /etc/log/traceserver.log). Warning: this is not the primary purpose of SYSLOG and could lead to unwanted behavior, such as a system slowdown.

From within your program you can modify the OUTPUT key with:

void alp_trace_setoutput(
    const char *aTracerKind,
    const char *config)

You can check the current value of the OUTPUT key with:

void alp_trace_getoutput(
    const char *aTracerKind,
    int nBufferLen, const char *config)

Keep in mind that any change in the traces.conf file impacts all traces from all components.

Filtering ^TOP^

Filtering is done through the traces.conf configuration file. This file should have a [FILTERS] section, with keys reflecting displayable traces. If a [FILTERS] section is not specified, or if the [FILTERS] section doesn't contain any keys, all traces are displayed.

The following is a sample configuration file:

#Configuration file for traces 
#Filters: should be like: Bluetooth=0x03000000 Y (see  
# main/include/alp/sysclass.h for values). 
#If no filter are specified, everything will be output. 
[SETTINGS] 
OUTPUT=tcp:coder1.palmsource.com 
 
#Filters list 
[FILTERS] 
AppServer=0x02000000 Y 
Bluetooth=0x03000000 Y 
EXCHANGE=0x04000000 N 
NOTIFY=0x05000000 N 
PACKAGE=0x06000000 N 
PDIUDA=0x07000000 N 
SAL=0x08000000 N 
TELEPHONY=0x09000000 Y 
MUX=0x0A000000 Y 
MOBILE=0x0B000000 N 
HOTSYNC=0x0C000000 N 
CNC=0x0D000000 N 
IPC=0x0E000000 N 
CONTACTS_DML=0x0F000000 Y 
EXGMGR=0x0D000000 Y 
SETTINGS=0x10000000 Y 

Command Line Operations ^TOP^

As is mentioned in "Linux Shell Commands and the Simulator," ACCESS Linux Platform—whether in the Simulator or on a real device—contains a basic Linux shell that can be accessed from a terminal window. When working with Scratchbox, simply enter commands into the Terminal window you used to launch Scratchbox from (be sure to log in as "root" first). If you have a real ACCESS Linux Platform device that is connected (typically via USB) to your desktop computer, you can telnet to that device (the IP address is often 192.168.2.101) and enter commands through the telnet session.

Application Launching and Debugging ^TOP^

The alp_app command-line tool can be used to launch and/or command-line debug your ACCESS Linux Platform applications. It can also be used to manipulate the application and various parts of the system. Typing alp_app on the command line with no options will display basic help text.

Table 11.2  Using alp_app 

When using alp_app, if the supplied application name does not include a ":", then the string "bar:com.access.apps." is automatically prepended. Thus, the command:

alp_app --exit test

will terminate the application named "bar:com.access.apps.test".

Exploring and Manipulating Global Settings ^TOP^

Occasionally it can be helpful to explore and alter the current values of various global settings. ACCESS Linux Platform includes the alp_settings command-line tool for just this purpose. It runs in the Simulator or on a real device (use it from a telnet session).

Use this tool like this:

alp_settings options... 

The options can be:

--install file_name 

--base-dir base_directory 

--crypto

--set key_name --value value --type type

When using the --set option, the "--type type" clause is optional and can be omitted. Valid types are: "int", "integer", "bool", "boolean", and "string".

--delete-tree directory 

--delete key_name 

--get key_name 

--Get key_name 

--uid user_id 

--list pattern 

--mode mode 

--no-notify

--quiet

As an example, here is a sample alp_settings command:

alp_settings --set /alp/input_methods/soft_keyboard/override_qwerty --value TRUE 

or:

alp_settings --setþ '/dev/key-input/type' --value soft 

Note that the above command line turns on the soft keyboard in the Simulator. This is useful when simulating devices that don't have a keypad, enabling you to enter a password, for instance.