Command-Line Primer

QUALCOMM Incorporated
5775 Morehouse Drive
San Diego, CA. 92121-1714
U.S.A
.

This documentation was written for use with Brew Mobile Platform, software version 1.0. This document and the Brew Mobile
Platform software described in it are copyrighted, with all rights reserved. This document and the Brew Mobile Platform software
may not be copied, except as otherwise provided in your software license or as expressly permitted in writing by QUALCOMM
Incorporated.

Copyright© 2010 QUALCOMM Incorporated

All Rights Reserved

Not to be used, copied, reproduced in whole or in part, nor its contents revealed in any manner to others without the express written
permission of Qualcomm.

This technical data may be subject to U.S. and international export, re-export or transfer ("export") laws. Diversion contrary to U.S.
and international law is strictly prohibited.

The BREW MP logo is a trademark of QUALCOMM Incorporated.Brew is a registered trademark of QUALCOMM Incorporated.

QUALCOMM is a registered trademark of QUALCOMM Incorporated in the United States and may be registered in other countries.
Other product and brand names may be trademarks or registered trademarks of their respective owners.

Sample Code Disclaimer:

This QUALCOMM Sample Code Disclaimer applies to the sample code of QUALCOMM Incorporated (“QUALCOMM”) to which it
is attached or in which it is integrated (“Sample Code”). Qualcomm is a trademark of, and may not be used without express written
permission of, QUALCOMM.

Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, QUALCOMM provides the Sample Code on an
"as is" basis, without warranties or conditions of any kind, either express or implied, including, without limitation, any warranties or
conditions of title, non-infringement, merchantability, or fitness for a particular purpose. You are solely responsible for determining
the appropriateness of using the Sample Code and assume any risks associated therewith. PLEASE BE ADVISED THAT
QUALCOMM WILL NOT SUPPORT THE SAMPLE CODE OR TROUBLESHOOT ANY ISSUES THAT MAY ARISE WITH IT.

Limitation of Liability. In no event shall QUALCOMM be liable for any direct, indirect, incidental, special, exemplary, or consequential
damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business
interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or
otherwise) arising in any way out of the use of the Sample Code even if advised of the possibility of such damage.

HT80-VT500-166 Rev.B
June 28, 2010
Command-Line Primer

Contents
Command-Line Primer..........................................................................................................2
Setup.......................................................................................................................................3
Building the application....................................................................................................... 5
Running the application......................................................................................................6
Debugging.............................................................................................................................. 8
Appendix ........................................................................................................................... 10
Device setup............................................................................................................. 10
Device compilers......................................................................................................11

i
Command-Line Primer

Command-Line Primer
®
This primer gets you started as a Brew Mobile Platform (Brew MP) developer. This document is written
for use with the Brew MP multiplatform SDK.

The purpose of this primer is to provide you with instructions for building, running and debugging a Brew
MP application using the command-line.
The following steps are covered in this primer.
1. Setup on page 3
2. Building the application on page 5
3. Running the application on page 6
4. Debugging on page 8

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 2

Command-Line Primer

Setup
This topic covers setup of your development environment.

Prerequisites/Environment setup
The Brew MP downloads page on the Brew MP website provides information about the required software
to proceed through this primer. You should complete all the steps under Setup for C/C++ Environment -
command-line.
Once you have installed the required software, make the following changes to environment variables:
• Remove C:\utils\Cygwin\bin from the Path environment variable
• Remove the path to make.d from the Path environment variable (the path to the make.d that used to
be in the Brew MP SDK)
• Ensure CodeSourcery bin precedes Cygwin or other bin\utils tool in PATH. For instance:
Add C:\Program Files\CodeSourcery\SourceryG++Lite\bin to the PATH environment variable.
This example uses RVCT 2.2.

Sample code setup

This primer uses a sample included with the Brew MP SDK sample code. The sample code is installed to
your machine via the Brew MP SDK Manager.
1. Click the Setup tab of the SDK Manager.
2. For the current toolset, next to Sample Code, select Install.
3. Follow the prompts to complete the installation of the sample code.

Create a simulation target

Prior to using the Simulator, you need to create a target. This step is optional if you already have a target.
Targets are based on device profiles. For more information on simulation targets and device profiles, see
the Simulator Help and Target Manager Help, in the Brew MP Tools Reference.
1. You will need a profile name to create your target from. To view the list of available profiles, enter
the following in the command-line prompt.
"%BREWMP_TOOLSET%\bin\tm" lp
2. To create a target, enter the following in the command-line prompt:
"%BREWMP_TOOLSET%\bin\tm" create <name> <profile>
Where <name> is the name of the target to be created, and <profile> is the name of the profile the
target is based on.

Launch simulation target

1. You need the target name to launch it from the command-line. To get a list of simulation targets
(both off and on), enter the following in the command-line prompt:
"%BREWMP_TOOLSET%\bin\tm" lt -Sim
2. Once you have your <target name>, you can turn on the target by typing the following in the
command-line prompt:
"%BREWMP_TOOLSET%\bin\simulator.exe" "<target_name>"

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 3

Command-Line Primer

The Simulator will be launched running <target name>.

Be sure to take note of the target name, you will need it to load the application.

Device Setup
Steps to prepare your PC and Brew MP device for running Brew MP applications are covered in the
device setup on page 10 section of this primer.
1. Connect one or more physical targets to PC (USB port, internet), and turn physical target(s) on.
2. Make sure the device is in developer mode.
3. To obtain a list of connected devices, enter the following on the command-line prompt:
"%BREWMP_TOOLSET%\bin\ct" -g usb listtargets
Note: If the connected device(s) does not show up in the list the phone needs to be put in
developer mode and reset. The USB driver should also be properly installed once the device has
rebooted. If it is not Windows will prompt you to install the USB driver from the SDK.
4. Check if the device is signature file enabled by entering the following on the command-line prompt:
"%BREWMP_TOOLSET%\bin\ct" -p <target_desc> -g usb enablestatus
Note: <target_desc> is not needed if only one device is connected.
5. If the device needs to be signature file enabled, enter the following on the command-line prompt:
"%BREWMP_TOOLSET%\bin\ct" -p <target_desc> -g usb sigenable <sig file path>
Note: <target_desc> is not needed if only one device is connected.
To enable the device using a brewmp.com username and password (username/password enabled)
enter the following on the command-line prompt:
%BREWMP_TOOLSET%\bin\ct" -p <target_desc> -g usb tepenable -u <username>
Note: <target_desc> is not needed if only one device is connected.
You will then be prompted for the password.

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 4

Command-Line Primer

Building the application

This section covers building the application for Simulator and device.

This primer compiles a sample application from the command-line, using a makefile and make.d. The
makefile for c_basicapp is included in the samplecode folder installed on your machine from the SDK
Manager.

Building the application for Win32 - Simulator

The Brew MP Simulator uses a Dynamic Link Library (DLL) as the application executable. This section
covers building the Brew MP application DLL for simulation.
To run the make command to compile the c_basicapp example for Win32 with debug symbols, follow
these steps:
1. In a command-prompt, go to the %VS90COMNTOOLS% directory and run vsvars32.bat to set
VCINSTALLDIR and other environment variables needed by Visual Studio Express.
2. Go to the c_basicapp directory, and enter the following in the command prompt:
cs-make SHELL=cmd
SHELL=cmd may not be required in all cases.

Building the application for the RVCT22arm9 platform - device

The device uses the MOD file as the application executable.
1. Open a command prompt window. Within the c_basicapp directory type the following command and
press Enter. DEVICE is where the MIF and MOD will get created
cs-make V=RVCT22arm9_Debug install MIF_INSTALL_DIR=DEVICE
MOD_INSTALL_DIR=DEVICE

Package the application

Once your application is ready to run on device, you need to package the files to run on device.
• To create a *.brewmp file for installation on device, enter the following in the command-line prompt:
"%BREWMP_TOOLSET%\bin\bmppackager" <directory containing binaries to
package>
To run the application on device and test the application with the Brew MP Debugger you need to
package the files and Debugger (CDB) module to run on device.
• To package the CDB module for debugging, enter the following in the command-line prompt:
"%BREWMP_TOOLSET%\bin\bmppackager" "%BREWMP_TOOLSET%\bin\cdb"
For help with bmppackager, type the following:
"%BREWMP_TOOLSET%\bin\bmppackager" -h

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 5

Command-Line Primer

Running the application

This section covers running the application on a simulation and/or a device target.
The Simulator presents an image of a selected device and emulates running applications as they appear
on the actual device. As you develop your application, you can periodically build and test the application
on the Simulator.
Connect Tool (ct) is used to install modules on the target and run the application on the target. For help
with ct, type the following in a command prompt:
"%BREWMP_TOOLSET%\bin\ct" -h
When using ct, the -p <target> parameter specifies which device to perform the operation on. The -g
<gateway cls> parameter provides the ClassID of the application/module to the port. If there is only a
device running and no simulation targets, -g isn't necessary. If both a device and simulation target are
running, "-g usb" is enough to choose the device.
For simulation targets, the default DestinationPath is C:\Documents and Settings\All Users\Application
Data\Qualcomm\Brew MP\Target Manager\Targets\<target name>

Load application files to the target

1. To list targets, type the following:
"%BREWMP_TOOLSET%\bin\ct" listtargets
This provides the input for ct for the -g and -p parameters.
2. To obtain the application ClassID, type the following to get the ClassID:
c_basicapp.bid
3. To stop the running application, type the following, where <clsid> is the application ClassID:
"%BREWMP_TOOLSET%\bin\ct" stop <clsid>
4. There are separate commands for loading the application files to a simulation target or a device:
• To install the application binaries to a simulation target, type the following in the command-line
prompt.
"%BREWMP_TOOLSET%\bin\tm" ct install <target name> SourcePath
DestinationPathName
If the target name contains spaces, it should be enclosed by quotes. SourcePath is the
location of the application binaries on your computer. DestinationPathName is the destination
in the target file system.
• To load the application files to the device file system, enter the following in the command-line
prompt:
"%BREWMP_TOOLSET%\bin\ct" -p <target> install c_basicapp.brewmp"

Run application
To run the application on the target, do the following:
1. To run the application on the target, enter the following in the command-line prompt:
"%BREWMP_TOOLSET%\bin\ct" -p <target_desc> -g usb start <classID>
<target_desc> is only necessary if only one device is connected.

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 6

Command-Line Primer

For more information on Connect Tool or using the Simulator, including creating targets, see the
Simulator Help section of the Brew MP Tools Reference.

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 7

Command-Line Primer

Debugging
This section covers using Brew MP Debugger with the GDB command-line interface.
1. Use cdblauncher.exe to start Debugger on the target by navigating in a command-prompt to the
location of cdblauncher, %BREWMP_TOOLSET%\bin. The following is a sample command.
cdblauncher -device 1 -mod c_basicapp -app <ClassID>
This starts the Debugger server on the target, sends a request to start the Brew MP application with
the provided ClassID, and waits for the application module to load. When the application loads, it
stops at the module entry point as a result of hitting a breakpoint auto-inserted by Debugger. For
help using cdblauncher.exe, type the following in the location of cdblauncher:
cdblauncher -help
2. The next step is to connect to the device with GDB. GDB should be given the ELF file for the
module to be debugged as an argument. The following is a sample to enter in the command-prompt,
in the c_basicapp folder:
arm-none-eabi-gdb.exe RVCT22arm9_Debug\c_basicapp.elf
3. To connect GDB to the device, type the following in the GDB command-shell:
target remote :60891
It make take several seconds for GDB to connect to the device. When GDB connects to the device
it shows the application stopped at the module entry point (for example, AEEMod_Load for Brew
MP MOD files). After this, regular GDB commands can be used to debug the module, set any
breakpoints, and resume execution of the application.

Debugging multiple modules

A Brew MP application and the modules or extensions that the application uses can be debugged
together using the Brew MP Debugger from the command-line. Typically, the application module is
specified as the primary module to be debugged. GDB treats the primary module like an executable and
the additional modules loaded in the process as shared libraries.
Version dependencies: A version of ARM EABI GDB that supports shared libraries is needed for multiple
module debugging.
• Codesourcery Spring 2010 or newer has shared library support
• Brew MP SDK 1.0 Rev 7.5 or newer is needed.
The examples below show usage from the command line with the SDK sample c_basicextapp as the
primary application module and c_basicext as the extension it loads.
Before the extension modules get loaded, the location of the ELF files for the modules needs to be
specified.
This can be done by setting the solib-search-path, shown in the following example:

10 (gdb) set solib-search-path ../c_basicext/RVCT22arm9_Debug

Pending breakpoints can be set in modules yet to be loaded, such as in the following code example:

16 (gdb) br MyExt_DrawText
17 Function "MyExt_DrawText" not defined.
18 Make breakpoint pending on future shared library load? (y or [n]) y

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 8

Command-Line Primer

The breakpoints are bound when the module loads.

The list of extensions loaded can be displayed using the info sharedlibrary command, as in the following
code example:

29 (gdb) info sharedlibrary

30 From To Syms Read Shared Object Library
31 No sysfonts.elf
32 0x02d769e0 0x02d76e6c Yes c:\documents and settings\jojoyk\qualcomm
\samplecode\c_basicext\rvct22arm9_debug\c_basicext.elf

The complete log session is shown below.

1 cdblauncher -mod c_basicextapp -app 0x0071B014

2 cdblauncher : Sending cdb launch request ... Success
3 cdbgwserver : Listening on loopback tcp port 60891
4
5 arm-none-eabi-gdb RVCT22arm9_Debug\c_basicextapp.elf
6
7 GNU gdb (Sourcery G++ 4.4-180) 7.0.50.20100218-cvs
8 Reading symbols from c:\documents and settings\jojoyk\qualcomm
\samplecode\c_basicextapp\rvct22arm9_debug\c_basicextapp.elf...done.
9
10 (gdb) set solib-search-path ../c_basicext/RVCT22arm9_Debug
11 (gdb) target remote :60891
12 Remote debugging using :60891
13 AEEMod_Load (pIShell=0x413ee80, ph=0x1dea224, ppMod=0x0)
at AEEModGen.c:130
14 130 {
15
16 (gdb) br MyExt_DrawText
17 Function "MyExt_DrawText" not defined.
18 Make breakpoint pending on future shared library load? (y or [n]) y
19
20 Breakpoint 1 (MyExt_DrawText) pending.
21 (gdb)
22 Loaded module: sysfonts @ 0xb0807044
23 Error while mapping shared library sections:
24 sysfonts.elf: No such file or directory.
25 Loaded module: c_basicext @ 0x02d769e0
26
27 Breakpoint 1, MyExt_DrawText (po=0x2d7d080) at c_basicext.c:357
28 357 MyExt * pMe = (MyExt *)po;
29 (gdb) info sharedlibrary
30 From To Syms Read Shared Object Library
31 No sysfonts.elf
32 0x02d769e0 0x02d76e6c Yes
c:\documents and settings\jojoyk\qualcomm\samplecode
\c_basicext\rvct22arm9_debug\c_basicext.elf

The Debugger server on the device shuts down when the application being debugged ends or
when the debug session is terminated from the PC. Before connecting with GDB the next time, the
cdblauncher command needs to be run again. Debugger supports most GDB commands. Please see
GDB documentation for more information.

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 9

Command-Line Primer Device setup

Appendix
The Appendix provides additional application development information on device compilers on page
11, and device setup on page 10.

Device setup
This topic discusses steps to prepare your device for working with Brew MP applications.

A Brew MP device needs to be put in Developer Mode prior to using Brew MP SDK Tools to load, run,
and test applications on a Brew MP device.
Note: Developer Mode (Gateway) is supported on Brew MP 1.0.2 devices. Brew MP 1.0.0 and some
1.0.1 devices do not support Developer Mode.
Developer Mode involves the following steps:
• Developer Mode Port Settings -- Enabling the port on the device (USB / Serial) so the tools can
connect. The method of using key sequence on the device is covered in this primer. For other
methods, see the Connect Tech Guide on the Brew MP website.
• Developer Mode device plug in and driver setup -- Physically connecting the device. Instructions for
installation PC drivers for the device are covered in this topic.
• Developer Mode Connect -- Establishing communication between the PC tools and device. This is
done using the Connection Manager dialog in Loader and/or Logger. See the Tools Reference for
more information.
• Developer Mode Enable -- Authorizing the device to run the developer's code and opening the
device to the tools. The legacy method is to copy a Test Signature to the device, which is discussed
in this document.

Developer Mode Port Settings

There are three methods to enable the port on the device. The first is to use the phone menu to place
the phone in developer mode. Not all Brew MP phones provide this menu. A second option is to use the
manufacturer device drivers to connect to the device via DIAG, then use the Gateway Turn-on tool, which
uses Diag or modem ports to enable the Gateway on devices that don't ship with it on by default. These
methods are covered in the Connect Tech Guide on the Brew MP website. The third method of using key
sequences is covered below.
Key sequences can be used on the device to enable the ports.
1. On the keypad (in any screen) enter the following key sequence: ###BREWDEBUG#.
2. The following message displays at the top of the screen: "Debug Keys On".
3. Enter the following key sequence: ###17382977#.
A menu appears.
4. Use the arrow keys to navigate to the following option: Diag, Data, NMEA, and Gateway, and
select it.
5. Select the following option: Yes & Set Default
To exit Gateway mode, type in ###17353617#. Alternatively, enter ###BREWDEBUG### (#17353617#),
or reboot the phone. If you reboot the phone while Gateway is running, you'll have to find the
AUXSETTINGS application and change the port configuration for both the Data and Diag ports back

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 10

Command-Line Primer Device compilers

to "USB". Failure to do this will probably cause the phone to be unresponsive to all PC-based tools,
including QPST and QXDM.

Developer Mode device plug in and driver setup

There are two types of device drivers, device manufacturer driver and the Brew MP SDK driver. Check
the Brew MP device database and/or check with your device manufacturer to obtain the manufacturer
driver. The installation of the manufacturer driver can vary between devices.
To install the Brew MP USB device driver for PC, do the following:
1. Plug the device in to a USB port on your PC.
The Windows New Hardware Wizard dialog opens.
2. If the New Hardware Wizard dialog specifies "Brew Mobile Platform Device", do the following:
Select Install from a list or a specific location, and click Next.
Select Search for the best driver in these locations, and select Include this location in the
search and click Browse to navigate to <C:\Program Files\Qualcomm\Brew MP SDK\Toolset xxx
\drivers\usbdevice\Win32\WinXP\free>.
Select Next, and follow the prompts to finish the installation.

Developer Mode Enable

Versions of BREW preceding Brew MP, such as BREW 1.x, 2.x, 3.x and 4.x, did not have Developer
Mode. Instead they used Test Enable Signatures. Test signatures continue to be supported by Brew MP,
but Developer Mode is preferred. It is generally easier to obtain authorization for and is more convenient.
If you already have a test signature file in the device file system, you can skip this step.
Brew MP Tools support Developer Enablement Service (DES) and Developer Enablement Signature.
When using Brew MP Loader or Logger to connect to a device that does not have a valid signature file, a
dialog will appear prompting you to use one of the following two methods to unlock the phone:
• DES - Enable the device using a developer brewmp.com username and password. Privileges for the
devices are based on username credentials. This is the preferred enablement method for Brew MP
devices. Enablement can be performed by using any Brew MP tool that utilizes Connect. The Brew
MP Connect Tool (CT) can be used to enable the device as well.
• Developer Enablement Signature or signature file enable - Distributors, operators, and OEM
manufactures often have the ability to generate signature files. These files provide privileges,
according to the creator, to run code on the device. This is the common method to enable phones
working off of a BREW distribution system. This is the only enablement path for BREW 3.x and 4.x
devices. The Signature file needs to be installed on the device.
For more information on device setup and Developer Mode, see the Connect Tech Guide on the Brew MP
website.

Device compilers
This topic is a discussion of Brew MP device compiler options and their generated output.
Brew MP applications are run on the Brew MP Simulator using DLL/DDL1s. Brew MP applications run on
a device use a MOD/MOD1 file. The ARM compiler is used to generate these files for the ARM processor.
The following table shows the files used to run an application on the Simulator versus the files used to run
an application on a physical device

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 11

Command-Line Primer Device compilers

File type Required files for Required files for File source
Brew MP Simulator Brew MP device
Module Information yes yes Generated by Brew MP
File (MIF) Resource Manager
Brew MP Applet yes yes Generated by Brew MP
Resource File (BAR) Resource Manager
Dynamic Link Library yes n/a Compiled by Visual Studio or
(DLL/DLL1) Eclipse IDEs
Module File (MOD/ n/a yes Compiled by ARM Compiler
MOD1)
Test Signature File n/a yes Obtained from the device
(SIG) manufacturer
Locally-generated yes n/a Locally generated via the
ClassID contained in Resource Manager
MIF
Unique ClassID n/a yes Web-based Brew MP ClassID
included in MIF Generator

ARM Compilers
The following ARM compilers are compatible with Brew MP devices. This primer uses the RVCT 2.2
compiler.
• RealView Compilation Tools (RVCT) for Brew MP is based on the popular compiler, linker, and
assembler components of the ARM Developer Suite version, but are specifically designed to target
the Brew MP environment. Both the ARM Developer Suite and RVCT for Brew MP can be obtained
from the ARM website. The Brew MP Debugger (CDB) and Brew MP IDE Plugins are compatible
with RVCT 2.2.
• The ARM RealView Development Suite (RVDS) is a software development solution for creating
applications for ARM architecture.
• The CodeSourcery G++ compiler for Brew MP is a free, open-source compiler.
Note: The ARM compiler should be installed in a path that doesn't contain any spaces.

Troubleshooting
The makefile generated points to the ARM environment variable RVCT22BIN. Also ensure that the
ARMLMD_LICENSE_FILE environment variable is pointing to the correct location.

Qualcomm Confidential and Proprietary | © 2010 QUALCOMM Incorporated 12