Sie sind auf Seite 1von 14

Command-Line Primer

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

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

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

Command-Line Primer Setup This topic covers setup of your development environment. Prerequisites/Environment setup The

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>"

Command-Line Primer The Simulator will be launched running <target name>. Be sure to take note

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.

Command-Line Primer Building the application This section covers building the application for Simulator and device.

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

Command-Line Primer Running the application This section covers running the application on a simulation and/or

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.

Command-Line Primer For more information on Connect Tool or using the Simulator, including creating targets,

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.

Command-Line Primer Debugging This section covers using Brew MP Debugger with the GDB command-line interface.

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

Command-Line Primer The breakpoints are bound when the module loads. The list of extensions loaded

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.

Command-Line Primer Appendix Device setup The Appendix provides additional application development information on device

Command-Line Primer

Appendix

Device setup

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

Command-Line Primer Device compilers to "USB". Failure to do this will probably cause the phone

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

Command-Line Primer Device compilers File type Required files for Brew MP Simulator Required files for

Command-Line Primer

Device compilers

File type

Required files for Brew MP Simulator

Required files for Brew MP device

File source

Module Information File (MIF)

yes

yes

Generated by Brew MP Resource Manager

Brew MP Applet Resource File (BAR)

yes

yes

Generated by Brew MP Resource Manager

Dynamic Link Library

yes

n/a

Compiled by Visual Studio or Eclipse IDEs

(DLL/DLL1)

Module File (MOD/

n/a

yes

Compiled by ARM Compiler

MOD1)

Test Signature File (SIG)

n/a

yes

Obtained from the device manufacturer

Locally-generated ClassID contained in MIF

yes

n/a

Locally generated via the Resource Manager

Unique ClassID included in MIF

n/a

yes

Web-based Brew MP ClassID 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.