TRK On-device Debugging

# Date 1284561616 18000 # Node ID b622387629d6a054b804375efc32916d3c32f5df # Parent 549473f3167ee2c96f04688da5a43463e833e5b4 changed TRK to CODA in docs except where it related to pre-3.0 versions diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/concepts/concepts.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/concepts/concepts.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/concepts/concepts.htm Wed Sep 15 09:40:16 2010 -0500 @@ -26,6 +26,7 @@

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/concepts/ngage_projects.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/concepts/ngage_projects.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/concepts/ngage_projects.htm Wed Sep 15 09:40:16 2010 -0500 @@ -61,7 +61,7 @@

Once you have an .N-GAGE game file, you need to deploy it on the target device:

Verify that you have a valid developer certificate on the target device given to you by the Nokia R&D Certificate Service. If not, get and install one.
Verify that you have Application TRK installed on the target device. If not, install it now using On-Device Connections > New Connection Wizard > Install remote agents pane.
Verify that you have Application CODA installed on the target device. If not, install it now using On-Device Connections > New Connection Wizard > Install remote agents pane.
Manually install the .N-GAGE file on the device

Debugging the Game project

@@ -69,11 +69,11 @@

Open Window > Preferences > Run/Debug > Launching preference panel and disable the Build (if required) before launching option under the General Options group
Right-click the project and choose Debug As > Debug Configuration to open the Debug Cinfigurations window
Create an Symbian OS Application TRK launch configuration +
Create an Symbian OS Application CODA launch configuration
- In the Connection tab select the COM port used to connect to the device.
- In the Installation tab, verify that the game SISX file is correct
- In the Debug tab, enable the View messges between PC and debug agent on the phone if you want to monitor communications between TRK and Carbide
- In the Debug tab, enable the View messages between PC and debug agent on the phone if you want to monitor communications between CODA and Carbide

General registers

Registers are the register contents of the central processing unit (CPU) of the host computer or the targeted device. When debugging projects using the emulator, only the host computer x86 registers are visible in the Registers view. When debugging projects on a device, only the target device registers are visible.

In most cases, the contents of all the registers can be modified. However, when debugging applications on a target device with Application TRK, you cannot change the LR and SP registers.

In most cases, the contents of all the registers can be modified. However, when debugging applications on a target device with Application CODA, you cannot change the LR and SP registers.

Figure 1. Registers view with possible register types

The types of registers can include:

R14 is the link register (it is used for storing return addresses in the construction of sub routines)
R15 is the program counter (PC)

In most cases, the contents of all the registers can be modified. However, when debugging applications on a target device with Application TRK, you cannot change the LR, SP, and CPSR registers.

In most cases, the contents of all the registers can be modified. However, when debugging applications on a target device with Application CODA, you cannot change the LR, SP, and CPSR registers.

Figure 2 - ARM Registers

Other references

Target Communication Framework (TCF)

TCF (Target Communication Framework) is a vendor-neutral, lightweight, extensible network protocol used mainly for communicating with embedded systems (targets). Its most distinguishing feature is that TCF is designed to transparently plug in value-adding servers between the tool and the target. TCF is protocol agnostic in that it does not depend on a specific transport like TCP/IP, serial, SSH tunnel, or other. It also supports auto-discovery of targets and services, so any tool can determine which services are available from the target.

Carbide.c++ uses TCF to communicate with TRK, Trace, and other services on a target device. For example, the Carbide debugger uses TCF to communicate with the TRK remote agent to control debuggable programs running on the target. Other Carbide plug-ins can also use TCF to communicate with their specific services.

Carbide.c++ uses TCF to communicate with CODA, Trace, and other services on a target device. For example, the Carbide debugger uses TCF to communicate with the CODA remote agent to control debuggable programs running on the target. Other Carbide plug-ins can also use TCF to communicate with their specific services.

Related tasks

Concepts

TRK On-device Debugging

Carbide On-device Debug Agent

TRK On-device Debugging

The on-device TRK remote agent (Application TRK or System TRK) is a program that enables on-device debugging of phone prototypes, reference boards, and retail phones. An on-device debug agent is a program that is installed on a phone or reference board. It communicates with the debugger using a serial-over-Bluetooth or serial-over-USB connection. Through this serial communication, the on-device debug agent acts as the interface between the Carbide.c++ debugger and the target device. An on-device debug agent provides:

Carbide On-device Debug Agent

The Carbide On-device Debug Agent (CODA) is a program that enables on-device debugging of phone prototypes, reference boards, and retail phones. An on-device debug agent is a program that is installed on a phone or reference board. It communicates with the debugger using a serial-over-Bluetooth or serial-over-USB connection. Through this serial communication, the on-device debug agent acts as the interface between the Carbide.c++ debugger and the target device. The CODA provides:

Debug agent running on Symbian OS
Provides a stable & integrated interface to Symbian OS
Can be built-in to the OS image or installed as a .sis file

Using the on-device remote agent, one can use the Carbide.c++ IDE to debug programs running on phone hardware, making the debugging process much easier. The on-device debug agent works on all Nokia Qt SDK, Symbian^3, and Symbian TechView devkits.

The Application TRK remote agents are stored online and can be downloaded and installed using the On-Device Connections > New Connection Wizard > Install remote agents pane.

The Application CODA is stored online and available for download and installation using the On-Device Connections > New Connection Wizard > Install remote agents pane.

Some of the key benefits to using an on-device debug agent include:

Easy debugging via serial interface (Bluetooth, USB, IrDA, etc)

There are two variations of the on-device debug agent, they are:

Application TRK—supports application debugging only and available to developers creating applications for devices. Developers do not have access to system level routines, system ROM, other user application code, cannot modify the LR and SR registers, and must use a SIS file to debug an application.
System TRK— +
Application CODA—supports application debugging only and available to developers creating applications for devices. Developers do not have access to system level routines, system ROM, other user application code, cannot modify the LR and SR registers, and must use a SIS file to debug an application.
System CODA— supports both application and limited ROM debugging (includes application executables and limited ROM based components (i.e. no device drivers) and available to original equipment manufacturers (OEM) for device creation and customization

Related tasks

- Specify TRK connection information. + Specify CODA connection information.

Other Useful Commands

The Debug view has a few other commands that are useful under some debugging situations:

Disconnecting from a process

Use the Disconnect command () when debugging with Application TRK or System TRK to detach the debugger from a process on the device while leaving the device running.

Use the Disconnect command () when debugging with Application CODA or System CODA to detach the debugger from a process on the device while leaving the device running.

When debugging in stop-mode it will detach the debugger and leave the CPU running on the device.

Click the Disconnect button () in the Debug view

Use the Terminate command () to stop or halt a program based on the type of debugging session underway. Terminate behavior includes:

Emulator - terminates program execution and ends the debug session
Application TRK or System TRK - kills the process on the device and ends the debug session. To terminate without killing the process, use Disconnect instead.
Application CODA or System CODA - kills the process on the device and ends the debug session. To terminate without killing the process, use Disconnect instead.
Stop-mode soft attach - suspends the attached process while other processes continue to run on the device. If only a single process is running on the device, the device CPU is suspended. Once the CPU is suspended you must launch a new debug session to resume the device CPU.

This behavior differs from suspending a program, as this temporarily suspends execution.

Detaches the debugger from the selected process (useful for debugging attached processes).

NOTE After detaching the debugger from an on-device process, closing TRK on the device will also close the process.

NOTE After detaching the debugger from an on-device process, closing CODA on the device will also close the process.

Remove All Terminated

This is commonly caused when the binary parser is not set correctly in the project. To correct, open the project properties window (right-click project name in Project Explorer view and select Properties), expand the C/C++ Build section and click the Binary Parser tab in the C/C++ Build page. Now look for the PE Windows Parser option. If it's not checkmarked, checkmark it and click Apply. If it is already set then uncheck it and click Apply, then reapply a checkmark and click Apply. The debug icon should now appear.

Connectivity

Unable to connect to device using Bluetooth and debug it using TRK

Unable to connect to device using Bluetooth and debug it using CODA

When using Bluetooth to connect to a device there are several things that require correction, including:

-
If using built-in Bluetooth under WinXP SP2, ensure the manufacturer’s device drivers are installed and active. The default Microsoft drivers do not work correctly for debugging devices using TRK. For example, if using IBM Integrated Bluetooth on your computer, make sure you have the IBM drivers for the device.
+
If using built-in Bluetooth under WinXP SP2, ensure the manufacturer’s device drivers are installed and active. The default Microsoft drivers do not work correctly for debugging devices using CODA. For example, if using IBM Integrated Bluetooth on your computer, make sure you have the IBM drivers for the device.

Ensure the COM port used by Bluetooth is not commandeered by another process or device.
-
Ensure that you have the latest version of TRK on the target device.
+
Ensure that you have the latest version of CODA on the target device.

Attach to Process Launch Configuration

Use the Symbian OS Attach to Process launch configuration to attach the debugger to an already running Symbian OS process or thread on a target device from within any project. This is useful for debugging servers running in RAM in a client-server relationship where the client relies on the presence of the server process to operate as one example.

Attaching to a process requires a both target device running the Symbian OS and the presence of a TRK debug agent on the device. You can also use the Symbian OS Data view to attach to a process while debugging. However, you can not attach to a process running on an emulator.

If the New Launch Configuration Wizard created the Attach to Process launch configuration no changes are usually needed. The Attach to Process options match those of System TRK with one additional step, selection of the process to debug in the Attach to Process dialog.

Attaching to a process requires a both target device running the Symbian OS and the presence of CODA on the device. You can also use the Symbian OS Data view to attach to a process while debugging. However, you can not attach to a process running on an emulator.

If the New Launch Configuration Wizard created the Attach to Process launch configuration no changes are usually needed. The Attach to Process options match those of System CODA with one additional step, selection of the process to debug in the Attach to Process dialog.

To modify the launch configuration settings, select the Run > Debug As menu option to open the Debug dialog. Select the Attach to Process configuration and click a tab to set specific options. Click Apply to save any option modifications. Click Debug to launch a debugging session using the new settings.

Figure 1. Attach to Process launch configuration in the Debug dialog

Launch configurations come in several varieties, each designed for a specific purpose. You must choose one at the very start of the New Launch Configuration Wizard, so knowing the differences between them is important. Currently, the types to choose from include:

Symbian OS Application — used to run or debug executables.
Symbian OS Appication TRK — used to run or debug applications on a target device using the Application TRK on-device debug agent. Application TRK is an application that runs on released phones and allows you to debug your executables. The debugger will download a Symbian OS installation file to the phone and install it prior to launching.
Symbian OS Attach to Process — used to debug processes running on a target device for which a symbol file is available. This is available only for TRK and stop mode debugging. This launch configuration is not available for emulator debugging. Stop mode and TRK can both attach to a process from the Symbian OS Data view.
Symbian OS Appication CODA — used to run or debug applications on a target device using the Application CODA on-device debug agent. Application CODA is an application that runs on released phones and allows you to debug your executables. The debugger will download a Symbian OS installation file to the phone and install it prior to launching.
Symbian OS Attach to Process — used to debug processes running on a target device for which a symbol file is available. This is available only for CODA and stop mode debugging. This launch configuration is not available for emulator debugging. Stop mode and CODA can both attach to a process from the Symbian OS Data view.
Symbian OS Crash Debugger — used to launch an interactive command-line session with the Symbian OS crash debugger when the device crashes
Symbian OS Emulation — used to run or debug executables on an emulator.
Symbian OS System TRK — used to run or debug applications or ROM code on a target device using the System TRK on-device debug agent. System TRK is an application that runs on reference boards and prototype phones and allows you to debug your executables. The debugger will download files to the phone prior to launching.
Symbian OS System CODA — used to run or debug applications or ROM code on a target device using the System CODA on-device debug agent. System CODA is an application that runs on reference boards and prototype phones and allows you to debug your executables. The debugger will download files to the phone prior to launching.

Other references

The following launch configuration types are available:

Other references

The options shown in the Debugger page differ based upon the type of launch configuration. Generally, the options fall into these choices:

Emulation Debugger page (Emulation)
Run-mode Debugger page (Application TRK)
Stop-mode Debugger page (System TRK, Attach to Process)
Run-mode Debugger page (Application CODA)
Stop-mode Debugger page (System CODA, Attach to Process)

Emulation Debugger page

The Symbian OS Emulation launch configurations the Debugger page to specify entry point breaks and which logs to output to the Console view.

Run-mode Debugger page

In a run-mode launch configuration like Application TRK, you can specify an entry break point and how messages are handled as well as define the default instruction set.

In a run-mode launch configuration like Application CODA, you can specify an entry break point and how messages are handled as well as define the default instruction set.

Figure 2 - Debugger page showing run-mode options

Table 2. Debugger page — run-mode options

View program output

Enable to direct standard output messages to the TRK Program Output Console in the Console view.

Enable to direct standard output messages to the CODA Program Output Console in the Console view.

NOTE In the epoc.ini file the option LogToFile must also be set to 1.

Stop-mode Debugger page

In stop-mode launch configurations like System TRK, and Attach to Process, use the Startup Options to attach to a target and debug or run from the specified start address. Then use Target Options to specify the target's processor type, and set which initialization and memory configuration files to use in the debug session.

In stop-mode launch configurations like System CODA, and Attach to Process, use the Startup Options to attach to a target and debug or run from the specified start address. Then use Target Options to specify the target's processor type, and set which initialization and memory configuration files to use in the debug session.

Figure 3 - Debugger page showing stop-mode options

Table 3. Debugger page — stop-mode options

Other references

Executables page

The Executables page specifies the executables available to debug with your project based on the chosen rule. The Executables page gives you project level control over the executables associated with it. The page shows all the executables in the workspace or those imported into the Executables view from outside the workspace that can be debugged by this project. See the Executables view for information on controlling executables from the workspace.

Figure 1 - Executables page (System TRK example)

Figure 1 - Executables page (System CODA example)

Table 1. Executable page —items

File Transfer page

The File Transfer page displays an auto-populated list of files for System TRK that the IDE transfers to the target device at the start of each launch. For RnD device images, the target location for files is normally c:\sys\bin or another protected area. For production device images Application TRK does not support the transfer of files to c:\sys\bin or other protected areas.

Users can add, edit, or delete files in the list and sort by clicking on a column header. By default, any file added is automatically checked for downloading to the device. Users can uncheck a file to remove it from the download list without removing the file itself. System TRK users can use this panel to download any type of file, like bitmaps, HTML, sounds, and more, to the phone and applicable to Application TRK for transfering any files outside of the installation file.

The File Transfer page displays an auto-populated list of files for System CODA that the IDE transfers to the target device at the start of each launch. For RnD device images, the target location for files is normally c:\sys\bin or another protected area. For production device images Application CODA does not support the transfer of files to c:\sys\bin or other protected areas.

Users can add, edit, or delete files in the list and sort by clicking on a column header. By default, any file added is automatically checked for downloading to the device. Users can uncheck a file to remove it from the download list without removing the file itself. System CODA users can use this panel to download any type of file, like bitmaps, HTML, sounds, and more, to the phone and applicable to Application CODA for transfering any files outside of the installation file.

Figure 1. File Transfer page

Table 1. File Transfer page —items

Target directory—the path to the target directory where transfered files are placed on the device.

-
The target directories where files can be installed depends upon the type of device image you have on the device and which version of TRK you are using.
+
The target directories where files can be installed depends upon the type of device image you have on the device and which version of CODA you are using.

-
Application TRK - public folders only on production device images
-
System TRK - public and protected folders, like c:\sys\bin, on RnD device images
+
Application CODA - public folders only on production device images
+
System CODA - public and protected folders, like c:\sys\bin, on RnD device images

Installation page

The Installation page specifies the .sis file to install on the target device when using Application TRK. This is required when using the TRK debug agent with 9.x based SDK’s.

The Installation page specifies the .sis file to install on the target device when using Application CODA. This is required when using the CODA debug agent with 9.x based SDK’s.

Figure 1. Installation page

Table 1. Installation page —items

The options shown in the Main page differ based upon the type of launch configuration. Generally, the options fall into these choices:

Emulation Main page (Emulation)
Run-mode Main page (Application TRK)
Stop-Mode Main page (System TRK)
Run-mode Main page (Application CODA)
Stop-Mode Main page (System CODA)

Emulation Main page

The Symbian OS Emulation launch configuration uses the Main page to define the process to be launched by the emulator.

Run-mode Main page

The Symbian OS Application TRK launch configuration uses the Main page to defines the project and the process to launch on the target device.

The Symbian OS Application CODA launch configuration uses the Main page to defines the project and the process to launch on the target device.

Figure 2 - Main page (Application TRK shown)

Figure 2 - Main page (Application CODA shown)

Table 2. Run-mode Main page —items

Stop-mode Main page

The Symbian OS System TRK launch configurations uses the Main page to defines the project and the executable to launch on the target device.

The Symbian OS System CODA launch configurations uses the Main page to defines the project and the executable to launch on the target device.

Figure 3. Main page

Table 3. Stop-mode Main page — items

ROM Image page

Use the ROM Image page in a System TRK launch configuration to define startup options and ROM image download information.

Use the ROM Image page in a System CODA launch configuration to define startup options and ROM image download information.

Figure 1 - ROM Image page in launch configuration

Table 4. Launch configuration window—ROM Image tab items

ROM Log page

Use the ROM Log page in a System TRK launch configuration to specify where the ROM log file is stored and the Epoc32 directory.

Use the ROM Log page in a System CODA launch configuration to specify where the ROM log file is stored and the Epoc32 directory.

Figure 1. ROM Log page

Table 1. ROM Log page—items

Application TRK Launch Configuration (Run-mode)

Select the Symbian OS Application TRK launch configuration to debug or run applications on a target device using the Application TRK on-device debug agent. Application TRK is an application that runs on released phones and allows you to debug your executables. The debugger will download a Symbian OS installation file to the phone and install it prior to launching.

If the New Launch Configuration Wizard was used to create the Application TRK launch configuration no changes are usually needed. To modify the launch configuration settings, select the Run > Debug As menu option to open the Debug dialog. Select the Application TRK configuration and click a tab to set specific options. Click Apply to save any option modifications. Click Debug to launch a debugging session using the new settings.

Application CODA Launch Configuration (Run-mode)

Select the Symbian OS Application CODA launch configuration to debug or run applications on a target device using the Application CODA on-device debug agent. Application CODA is an application that runs on released phones and allows you to debug your executables. The debugger will download a Symbian OS installation file to the phone and install it prior to launching.

If the New Launch Configuration Wizard was used to create the Application CODA launch configuration no changes are usually needed. To modify the launch configuration settings, select the Run > Debug As menu option to open the Debug dialog. Select the Application CODA configuration and click a tab to set specific options. Click Apply to save any option modifications. Click Debug to launch a debugging session using the new settings.

Figure 1. Application TRK launch configuration in the Debug dialog

The Application TRK launch configuration panes include:

Figure 1. Application CODA launch configuration in the Debug dialog

The Application CODA launch configuration panes include:

The Main tab defines the project to be launched. Enter the name of the project in the Project field, and the executable name in the Executable field.
The Arguments tab (standard CDT page) lets you specify the program arguments that an application uses.

System TRK Launch Configuration (Stop-mode)

Select the Symbian OS System TRK launch configuration provides C/C++ stop-mode debug options that use a JTAG interface when a Symbian OS launch configuration is created. The settings included in these launch configuration are a combination of Carbide, CDT, and Eclipse options.

If the New Launch Configuration Wizard was used to create the System TRK launch configuration no changes are usually needed. To modify the launch configuration settings, select the Run > Debug As menu option to open the Debug dialog. Select the System TRK configuration and click a tab to set specific options. Click Apply to save any option modifications. Click Debug to launch a debugging session using the new settings.

System CODA Launch Configuration (Stop-mode)

Select the Symbian OS System CODA launch configuration provides C/C++ stop-mode debug options that use a JTAG interface when a Symbian OS launch configuration is created. The settings included in these launch configuration are a combination of Carbide, CDT, and Eclipse options.

If the New Launch Configuration Wizard was used to create the System CODA launch configuration no changes are usually needed. To modify the launch configuration settings, select the Run > Debug As menu option to open the Debug dialog. Select the System CODA configuration and click a tab to set specific options. Click Apply to save any option modifications. Click Debug to launch a debugging session using the new settings.

Figure 1. System TRK launch configuration in the Debug dialog

The System TRK launch configuration panes include:

Figure 1. System CODA launch configuration in the Debug dialog

The System CODA launch configuration panes include:

The Main tab defines the project to be launched. Enter the name of the project in the Project field, and the executable name in the Executable field.
The Debugger tab defines debug configurations, such as entry point to begin debugging and target options.

New Launch Configuration Wizard

The New Launch Configuration Wizard launches when no launch configuration exists for a build configuration in a project. Wherever possible the New Launch Configuration wizard gathers the information from the project and asks additional questions based on the type of launch configuration chosen. For example, a launch configuration using Application TRK requires different information than one targeted for System TRK.

The New Launch Configuration Wizard launches when no launch configuration exists for a build configuration in a project. Wherever possible the New Launch Configuration wizard gathers the information from the project and asks additional questions based on the type of launch configuration chosen. For example, a launch configuration using Application CODA requires different information than one targeted for System CODA.

Every project consists of one or more build configurations as listed under the Build project icon () of the toolbar or in the Add/Remove Carbide Build Configuration dialog. Every build configuration needs a launch configuration to enable debugging. Launch configurations can be shared between build configurations. The New Launch Configuration Wizard detects when a build configuration doesn't have an associated launch configuration and guides you through the setup process.

Figure 1. Build configurations for the chosen project appear under the Build icon

Application TRK and System TRK

Application CODA and System CODA

TRK Connection Settings
TRK SIS Selection (Application TRK only)
CODA Connection Settings
CODA SIS Selection (Application CODA only)

Attach to Process

TRK Connection Settings
CODA Connection Settings

Debug As dialog

Figure 1 - Debug As dialog

Launch Types

Use the Launch Types page to select the type of launch configuration for the build target. This page does not appear when using an Emulator target. Available types are listed from the most frequently chosen (Application TRK) to the least likely type (Attach to Process). Select a type and click Next.

Use the Launch Types page to select the type of launch configuration for the build target. This page does not appear when using an Emulator target. Available types are listed from the most frequently chosen (Application CODA) to the least likely type (Attach to Process). Select a type and click Next.

Figure 2 - Launch Type page

Build Options Selection

Select the Executable to launch, verify it is the correct binary, then click Next.

Figure 4 - Executable Selection page (when project has multiple EXEs)

TRK Connection Settings

Use the TRK Connection Settings page to specify the connection used to communicate with the target device. If the device is already connected, the drop down list will include both the COM port and the name of the device using that port. Use the On-Device Conection dialog to verify and update all Carbide software services on the device. Choose the serial port used to communicate with the target device and click Next.

CODA Connection Settings

Use the CODA Connection Settings page to specify the connection used to communicate with the target device. If the device is already connected, the drop down list will include both the COM port and the name of the device using that port. Use the On-Device Conection dialog to verify and update all Carbide software services on the device. Choose the serial port used to communicate with the target device and click Next.

Figure 5 - TRK Connection Settings page

Figure 5 - CODA Connection Settings page

TRK SIS Selection

Use the TRK SIS Selection page to select the SIS file to install on the target device. Click the Modify SIS builder settings for build configuration link to open the SIS Builder properties pane to add, edit, or review the SIS files to build. Once the correct SIS File to Install is selected, click Next.

CODA SIS Selection

Use the CODA SIS Selection page to select the SIS file to install on the target device. Click the Modify SIS builder settings for build configuration link to open the SIS Builder properties pane to add, edit, or review the SIS files to build. Once the correct SIS File to Install is selected, click Next.

Figure 6 - TRK SIS Selection page

Figure 6 - CODA SIS Selection page

New Launch Configuration

Use the New Launch Configuration page to note the name of the configuration, confirm the launch configuration settings, and then launch the debug session. If something doesn't look right, click Back to return to a page and change its setting. If all the settings are correct, click Finish to start the debug session using this launch configuration.

If you checkmark Advanced settings, the Debug dialog appears instead of launching the project. This enables you to make additional changes to the new launch configuration before starting the debug session. By design and intent, this should seldom be required for the initial launch.

Remote Target Debugging (Run-mode) Tutorial

In this example we demonstrate how to debug applications on a remote device using the Application TRK remote debug agent. This enables you to test programs on the actual device it will operate on while observing its behavior using the Carbide debugger. The steps to do this include:

In this example we demonstrate how to debug applications on a remote device using the Application CODA remote debug agent. This enables you to test programs on the actual device it will operate on while observing its behavior using the Carbide debugger. The steps to do this include:

Connect target device for PC
Install TRK remote agent (v3.2.7) or later on the target device
Install CODA remote agent (v3.2.7) or later on the target device
Configure project for downloading
Debug project on target device

Connect target device to PC

Connect target device to PC
Install TRK remote agent (v3.2.7) or later on the target device
Install CODA remote agent (v3.2.7) or later on the target device
Configure project for downloading
Debug project on target device

Connect the USB cable between the remote device and PC running Carbide.

Use the Remote Connections view to verify a successful connection or by looking at the remote connection trim display shown at the bottom of the workplace window.

-
The Status column indicates whether the service you need for debugging, TRK, is Available. If it's status is Not Accessible you are probably missing the TRK remote agent on the remote device.
+
The Status column indicates whether the service you need for debugging, CODA, is Available. If it's status is Not Accessible you are probably missing the CODA remote agent on the remote device.
Click OK on the remote device when it asks to use PC Suite mode with USB.

NOTE Debugging requires the use of PC Suite mode. If you are in another mode, like Mass storage mode, an alert appears asking you to change.

NEXT: Install TRK remote agent

NEXT: Install CODA remote agent

Other references

Remote Target Debugging (Run-mode)

Install TRK remote agent Tutorial

Install TRK remote agent

Install CODA remote agent

Connect target device to PC
Install TRK remote agent (v3.2.7) or later on the target device
Install CODA remote agent (v3.2.7) or later on the target device
Configure project for downloading
Debug project on target device

To debug on a remote device you need a program to communicate between the Carbide debugger and your executable running on the device. That program is the TRK (Terminal Resident Kernel) remote agent, also known as Application TRK.

To debug on a remote device you need a program to communicate between the Carbide debugger and your executable running on the device. That program is the CODA (Carbide On-device Debug Agent) remote agent, also known as Application CODA.

Installing or updating the TRK remote agent

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/projects/tutorials/run_mode_debug_example_03.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/projects/tutorials/run_mode_debug_example_03.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/projects/tutorials/run_mode_debug_example_03.htm Wed Sep 15 09:40:16 2010 -0500 @@ -9,10 +9,10 @@

Configure project for debugging

Connect target device to PC
Install TRK remote agent (v3.2.7) or later on the target device
Install CODA remote agent (v3.2.7) or later on the target device
Configure project for downloading
Debug project on target device

@@ -33,7 +33,7 @@

New Launch Configuration Wizard

Enable the 'Launch program on device' option and select the executable to launch. -

This tells the TRK remote agent which application to launch once its downloaded.

This tells the CODA remote agent which application to launch once its downloaded.

Click the 'Modify SIS builder settings for build configuration' to open the Properties for project dialog.

The Carbide.c++ > Build Configurations > SIS Builder tab is shown.

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/projects/tutorials/run_mode_debug_example_04.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/projects/tutorials/run_mode_debug_example_04.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/projects/tutorials/run_mode_debug_example_04.htm Wed Sep 15 09:40:16 2010 -0500 @@ -9,15 +9,15 @@

Debug project on target device

Connect target device to PC
Install TRK remote agent (v3.2.7) or later on the target device
Install CODA remote agent (v3.2.7) or later on the target device
Configure project for downloading
Debug project on target device

You debug on a remote device using the exact same methods used for the emulator. Once the project is built and downloaded to the target device, the TRK remote agent then takes control. Then, using the Carbide debugger you can use all the debugger features to exercise the program on the device while monitoring its vitals in the Debug perspective.

You debug on a remote device using the exact same methods used for the emulator. Once the project is built and downloaded to the target device, the CODA remote agent then takes control. Then, using the Carbide debugger you can use all the debugger features to exercise the program on the device while monitoring its vitals in the Debug perspective.

Debugging a program on a remote device

Partial Upgrade Files

The SIS Builder supports the generation of partial upgrade .SIS files. A dialog appears when a SIS file exceeds 250k in size that describes the partial upgrade feature with a link to the SIS Builder page. Partial upgrade files enable Carbide to generate and download to the device only those portions of the application that have changed, enabling faster debug cycles. It does this using the SIS partial upgrade (PU) flag to mark the SIS file as a replacement or addition to the original SIS file. Debugging of large applications using Application TRK is enhanced as the entire application no longer needs to be installed on the device each time a change is made.

The SIS Builder supports the generation of partial upgrade .SIS files. A dialog appears when a SIS file exceeds 250k in size that describes the partial upgrade feature with a link to the SIS Builder page. Partial upgrade files enable Carbide to generate and download to the device only those portions of the application that have changed, enabling faster debug cycles. It does this using the SIS partial upgrade (PU) flag to mark the SIS file as a replacement or addition to the original SIS file. Debugging of large applications using Application CODA is enhanced as the entire application no longer needs to be installed on the device each time a change is made.

When the Partial update option is checked for a SIS file, both a complete and partial SIS files are generated. This ensures that the full SIS file is kept in sync with the partial upgrade SIS file. The partial upgrade SIS files are placed in the same folder as the full SIS file when stored in a project directory, or in the root of the project directory when the SIS file exists outside of the project. You can see where a partial upgrade file is created by examining the Partial upgrade sis/sisx path in the Installation tab of the launch configuration. Links to the partial upgrade files are added to the project within the Project Explorer view.

NOTE Internally, the .PKG file format of a partial upgrade file is identical to a complete .PKG file with two exceptions, 1) the file list only includes the names of files changed, and 2) the PU flag is set.

Partial upgrade files are deleted and only full SIS/SISX files are generated when:

Set PKG File for Build Configuration

The Set PKG File for Build Configuration dialog appears when an Application TRK build configuration does not include a PKG file. Use it to assign a PKG file to the project's current build configuration that will be used to create a project's SIS installation file. If you define a launch configuration used for on-device debugging with the TRK debug agent, you will need to specify a PKG file for the project. A PKG file primarily provides a list of program and resource files to install on the device.

The Set PKG File for Build Configuration dialog appears when an Application CODA build configuration does not include a PKG file. Use it to assign a PKG file to the project's current build configuration that will be used to create a project's SIS installation file. If you define a launch configuration used for on-device debugging with the CODA debug agent, you will need to specify a PKG file for the project. A PKG file primarily provides a list of program and resource files to install on the device.

Figure 1 - Set PKG File for Build Configuration

Table 1 Items

NOTE On Symbian OS 9.x builds, if the key/cert pair are not defined, makekeys will be called and temporary ones will be generated for you to "self-sign" the application. Self-signed applications should be in the 0xE0000000-0xEFFFFFFF range.

NOTE All Application TRK build configuration require a PKG file. If none is found in the active project then you will be asked to choose one.

NOTE All Application CODA build configuration require a PKG file. If none is found in the active project then you will be asked to choose one.

Related reference

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/reference/pref_carb_debugger.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/reference/pref_carb_debugger.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/reference/pref_carb_debugger.htm Wed Sep 15 09:40:16 2010 -0500 @@ -40,7 +40,7 @@ Time interval for auto-refreshing OS View - Determines how often to refresh data in the Symbian OS Data view which is available to the developer when using TRK or stop-mode debugging. + Determines how often to refresh data in the Symbian OS Data view which is available to the developer when using CODA or stop-mode debugging.

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/reference/trk/importing_remote_conns.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/reference/trk/importing_remote_conns.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/reference/trk/importing_remote_conns.htm Wed Sep 15 09:40:16 2010 -0500 @@ -30,7 +30,7 @@

Related references

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/reference/trk/panel_filter.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/reference/trk/panel_filter.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/reference/trk/panel_filter.htm Wed Sep 15 09:40:16 2010 -0500 @@ -35,7 +35,7 @@

Related concepts

Related references

TRK Pane Overview

When debugging a remote device using TRK, the following panes appear in the launch configuration window:

CODA Pane Overview

When debugging a remote device using CODA, the following panes appear in the launch configuration window:

Main Pane
Debugger Pane
File Transfer Pane
Executables Pane
Installation Pane
ROM Log (System TRK only)
ROM Log (System CODA only)
Source—specifies the location of source files used when debugging a C or C++ application
Common—specifies the location to store your run configuration, how to access it and what perspective to open when running an application

Related references

Install remote agents

A list of the most current versions of remote agents sorted by SDK and version. Select the version most compatable with the device. For example, a device running S60 5.0 needs a version of the TRK software compiled for that SDK, which in the image above is Application TRK 3.2.6.

Additional information about the selected entry is displayed to the right to help you choose the correct version of TRK for the target device.

Additional information about the selected entry is displayed to the right to help you choose the correct version of CODA for the target device.

Save

Install

Click Install to download and install the TRK selected in the Install remote agents list. A progress bar is shown if the install operation requires more than a few seconds to complete.

Click Install to download and install the CODA selected in the Install remote agents list. A progress bar is shown if the install operation requires more than a few seconds to complete.

NOTE Drivers installed by PC Suite or Ovi Suite are required in order for Install to download a remote agent onto the target device.

NOTE The SIS and SISX file types must be associated with an installer application like Nokia PC Suite or Ovi Suite in order to install them onto the device. Use the Save command above to perform a manual install to the device if you don't have an installer application.

Install Remote Agents

A list of the most current versions of remote agents sorted by SDK and version. Select the version most compatable with the device. For example, a device running S60 3.1.0 needs a version of the TRK software compiled for that SDK, which in the image above is Application TRK 2.8.7.

Additional information about the selected entry is displayed to the right to help you choose the correct version of TRK for the target device.

Additional information about the selected entry is displayed to the right to help you choose the correct version of CODA for the target device.

Save

Install

Click Install to download and install the TRK selected in the Install latest TRK list. A progress bar is shown if the install operation requires more than a few seconds to complete.

Click Install to download and install the CODA selected in the Install latest CODA list. A progress bar is shown if the install operation requires more than a few seconds to complete.

NOTE The SIS and SISX file types must be associated with an installer application like Nokia PC Suite in order to install them onto the device. Use the Save command above to perform a manual install to the device if you don't have an installer application.

Initiate Service Testing

Click Initiate Service Testing to query the remote agent software on the device for its version number. It then compares the version number found with the latest version available for Carbide. A progress bar will appear should the Check TRK version operation requires more than a few seconds.

Click Initiate Service Testing to query the remote agent software on the device for its version number. It then compares the version number found with the latest version available for Carbide. A progress bar will appear should the Check CODA version operation requires more than a few seconds.

NOTE The PC must have an internet connection to perform a remote agent version check.

Once the comparison is complete the Status text is updated with the result and further instructions as required.

If a connection fails, the errors normally fall into these two categories:

connection failure - this usually indicates the chosen COM port is not open. Try selecting a different COM port, specifically one with a name attached to it (COM4 - BthModem0) for the type of connection you are using (USB or Bluetooth). Repeat as necessary until you get a successful response.
TRK not responding - this indicates that the COM port is open but TRK is not responding. First, verify that TRK is up and running on the device. Second, TRK may be listening on a different COM port, so choose another named COM port and try again.
CODA not responding - this indicates that the COM port is open but CODA is not responding. First, verify that CODA is up and running on the device. Second, CODA may be listening on a different COM port, so choose another named COM port and try again.

Install Remote Agents

A list of the most current versions of remote agents sorted by SDK and version. Select the version most compatable with the device. For example, a device running S60 5.x needs a version of the TRK software compiled for that SDK, which in the image above is Application TRK 3.2.6.

Additional information about the selected entry is displayed to the right to help you choose the correct version of TRK for the target device.

Additional information about the selected entry is displayed to the right to help you choose the correct version of CODA for the target device.

Save

Install

Click Install to download and install the TRK selected in the Install latest TRK list. A progress bar is shown if the install operation requires more than a few seconds to complete.

Click Install to download and install the CODA selected in the Install latest CODA list. A progress bar is shown if the install operation requires more than a few seconds to complete.

Related references

Test Service Status

Click Initiate service testing to query the remote agent software on the device for its version number. It then compares the version number found with the latest version available for Carbide. A progress bar will appear should the Check TRK version operation requires more than a few seconds.

Click Initiate service testing to query the remote agent software on the device for its version number. It then compares the version number found with the latest version available for Carbide. A progress bar will appear should the Check CODA version operation requires more than a few seconds.

NOTE The PC must have an internet connection to perform a remote agent version check.

Once the comparison is complete the Status text is updated with the result and further instructions as required.

If a connection fails, the errors normally fall into these two categories:

connection failure - this usually indicates the chosen COM port is not open. Try selecting a different COM port, specifically one with a name attached to it (COM4 - BthModem0) for the type of connection you are using (USB or Bluetooth). Repeat as necessary until you get a successful response.
TRK not responding - this indicates that the COM port is open but TRK is not responding. First, verify that TRK is up and running on the device. Second, TRK may be listening on a different COM port, so choose another named COM port and try again.
CODA not responding - this indicates that the COM port is open but CODA is not responding. First, verify that CODA is up and running on the device. Second, CODA may be listening on a different COM port, so choose another named COM port and try again.

Install remote agents

Additional information about the selected entry is displayed to the right to help you choose the correct version of TRK for the target device.

Additional information about the selected entry is displayed to the right to help you choose the correct version of CODA for the target device.

Save

Install

Click Install to download and install the TRK selected in the Install latest TRK list. A progress bar is shown if the install operation requires more than a few seconds to complete.

Click Install to download and install the CODA selected in the Install latest CODA list. A progress bar is shown if the install operation requires more than a few seconds to complete.

Related references

And the supported services may include:

TRK
CODA
Tracing
and others

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/reference/trk/wnd_on_device_check_tab.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/reference/trk/wnd_on_device_check_tab.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/reference/trk/wnd_on_device_check_tab.htm Wed Sep 15 09:40:16 2010 -0500 @@ -11,7 +11,7 @@

Test Connection

Use the Set Connection Settings pane to compare the version of remote service installed on the device with the latest version available for Carbide. A remote service is any software on the device that can communicate with Carbide. This includes TRK, Trace, Performance Investigator, and other services. In this pane you can:

Use the Set Connection Settings pane to compare the version of remote service installed on the device with the latest version available for Carbide. A remote service is any software on the device that can communicate with Carbide. This includes CODA, Trace, Performance Investigator, and other services. In this pane you can:

Set the device OS used by the device and supported by the remote service
Verify that Carbide can communicate with the remote service via the chosen connection setting
Verify that you have the latest version of the remote service installed on the device

Device OS

A dropdown list of device OSes that are supported by the TRK debug agent software. Select the OS used by the device before running a check.

A dropdown list of device OSes that are supported by the CODA debug agent software. Select the OS used by the device before running a check.

Select a service to test

On-Device Connections

Use the New Connection wizard to verify and update Carbide software services on a device. Click the Help > On-Device Connections... menu option to open. Current services available include TRK, Tracing, and others. The following tabs are present:

Use the New Connection wizard to verify and update Carbide software services on a device. Click the Help > On-Device Connections... menu option to open. Current services available include CODA, Tracing, and others. The following tabs are present:

Setup Connection - define connection type, name and settings
Test Connection - verify connection operates as intended
Platform Security Diagnostics
New Windows System Messages Console
New Emulation Program Output Console
New TRK Program Output Console
New TRK Communications Log Console
New CODA Program Output Console
New CODA Communications Log Console
New Symbian Rom Log Console
New Emulator Output Console
CVS
New Console View

Remember that program output is console output from the running binary and communications log is the messages sent between TRK and the on-device debug agent.

Remember that program output is console output from the running binary and communications log is the messages sent between CODA and the on-device debug agent.

NOTE You can pin any message log view so that it does not lose focus.

find and set breakpoints, watchpoints, and eventpoints in source files. Double-click a source file to open it in an editor view and to review the status of its breakpoints.

In addition, an Executables project is created in the Project Explorer view. The binaries shown in the Executables project can be deleted which also removes them from the Executables view. For binaries outside the workspace you must import them into the Executables view so their symbolics can be used during the debug session. You can also drag and drop executables into the view.

NOTE To debug ROM DLLs with System TRK or in stop mode, always specify the ROM Log file in the project's launch configuration.

NOTE To debug ROM DLLs with System CODA or in stop mode, always specify the ROM Log file in the project's launch configuration.

Figure 1 - Executables view

The Executables view consists of the Executable Name and Source File Name panes describled in the table below. Use the Columns button in the toolbar to show or hide specific columns in each pane. Columns can be sorted and rearranged in the order desired.

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_chunks.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_chunks.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_chunks.htm Wed Sep 15 09:40:16 2010 -0500 @@ -18,12 +18,12 @@

Chunks

Libraries

NOTE Information for the Chunks and Libraries tabs is not available when debugging with the TRK debug agent.

NOTE Information for the Chunks and Libraries tabs is not available when debugging with the CODA debug agent.

Chunks

Chunks are an area of contiguous linear memory. It is the unit of memory allocation where a region of RAM is mapped into contiguous logical addresses. Chunks are allocated during boot for such things as the Kernel's data and stack.

The Chunks tab (Figure 4) provides a flat list of corresponding kernel objects. The list will display “sortable” attributes of that type of object in columns. The “sortable attribute” means you can sort the list by that attribute. For example, you may want to sort the list by the owning process name. Sort the list of any column by clicking on the column header.

NOTE Chunks data is not available during TRK debugging.

NOTE Chunks data is not available during CODA debugging.

Figure 4. Chunks Pane of Symbian OS View

Attaching to a Process

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_libs.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_libs.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_libs.htm Wed Sep 15 09:40:16 2010 -0500 @@ -19,11 +19,11 @@

Chunks

Libraries

NOTE Information for the Chunks and Libraries tabs is not available when debugging with the TRK debug agent.

NOTE Information for the Chunks and Libraries tabs is not available when debugging with the CODA debug agent.

Libraries Tab

The Libraries pane (Figure 5) in the Symbian OS view provides information on libraries in the Symbian OS residing on the target.

NOTE Library data is not available during TRK debugging.

NOTE Library data is not available during CODA debugging.

Figure 5. Libraries Pane of Symbian OS view

Attaching to a Process

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_overview.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_overview.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/reference/view_sym_os_data_overview.htm Wed Sep 15 09:40:16 2010 -0500 @@ -13,9 +13,9 @@

The Symbian OS Data view displays the processes and threads for the suspended debug session based on the selection in the Debug view. Read-only data is displayed for ARM build configurations. To open the Symbian OS Data view select Window > Show View > Symbian OS Data when the Debug perspective is visible or select Window > Show View > Other..., then expand the Carbide.c++ folder and select Symbian OS Data when the Carbide C/C++ perspective is visible. Click Ok to display the Symbian OS Data window (Figure 1).

NOTE The Symbian OS Data view works with the debugger and will only display data during a live debug session. The Symbian OS Data view is not supported for emulator debugging, and will not show anything during emulator debug.

The Symbian OS Data view reveals kernel data in the Symbian OS running on the device being debugged. The kernel data displayed is always that of the device with the currently selected thread or process in Debug view. If you are debugging two devices at the same time, the content of the view will change when focus is switched from a thread on one device to a thread on another device. The kernel data includes more than just processes and threads.

For the stop mode debugger and the crash debugger, all the data listed above is supported. For the Application and System TRK debuggers, the chunks and libraries views are not supported. The Symbian OS Data view is not supported for the emulator debugger and will show nothing during an emulator debug session. During a stop mode debug session or a TRK debug session, you are able to select a process or a thread in the Symbian OS Data view and attach the debugger to it for source level debugging if the binary is listed in the Executables view. Binaries listed in the Executable view can be source level debugged. Binaries not listed in the Executables view can only be assembly code debugged in the Disassembly view.

For the stop mode debugger and the crash debugger, all the data listed above is supported. For the Application and System CODA debuggers, the chunks and libraries views are not supported. The Symbian OS Data view is not supported for the emulator debugger and will show nothing during an emulator debug session. During a stop mode debug session or a CODA debug session, you are able to select a process or a thread in the Symbian OS Data view and attach the debugger to it for source level debugging if the binary is listed in the Executables view. Binaries listed in the Executable view can be source level debugged. Binaries not listed in the Executables view can only be assembly code debugged in the Disassembly view.

NOTE Any executable must be included in the Executables view before it can be debugged.

When the Time interval for auto-refreshing OS View option is enabled (which is on by default except for crash debugger), the data in the Symbian OS Data view will be auto-refreshed. Note that "auto-refresh" has a different meaning in different debuggers. During a stop mode debug session, the view will refresh data whenever the debugged program on the device is stopped and shows data as stale (greyed out) when the program is running. During a TRK debug session, the View will refresh data at a time interval regardless of whether the debugged program is stopped or not. The time interval is specified by an option in the Carbide.c++ global preference panel, which is five seconds by default.

When the Time interval for auto-refreshing OS View option is enabled (which is on by default except for crash debugger), the data in the Symbian OS Data view will be auto-refreshed. Note that "auto-refresh" has a different meaning in different debuggers. During a stop mode debug session, the view will refresh data whenever the debugged program on the device is stopped and shows data as stale (greyed out) when the program is running. During a CODA debug session, the View will refresh data at a time interval regardless of whether the debugged program is stopped or not. The time interval is specified by an option in the Carbide.c++ global preference panel, which is five seconds by default.

When auto-refresh is turned off, the debugger will not automatically refresh data in the View and will show the data as stale (greyed out). However you can manually refresh the data by clicking on the "Refresh" button in the View. Usually you may want to turn off the auto-refresh if you think it is slowing down your debug operations such as stepping.

Symbian OS Data pages

@@ -28,7 +28,7 @@

Chunks

Libraries

NOTE Information for the Chunks and Libraries tabs is not available when debugging with the TRK debug agent.

NOTE Information for the Chunks and Libraries tabs is not available when debugging with the CODA debug agent.

Overview Tab

This tab (shown in Figure 1) provides a tree view of ownership of all processes, threads, and chunks in the OS. In contrast, the other tabs provide a flat list of corresponding kernel objects such as process, thread, chunk, library, etc.

@@ -55,7 +55,7 @@

Debug process or thread

Click the Debug button to attach to the process and debug the selected process or thread. Or right-click an item and choose Debug. This applies to both TRK (run mode) and TCF (stop mode).

Click the Debug button to attach to the process and debug the selected process or thread. Or right-click an item and choose Debug. This applies to both CODA (run mode) and TCF (stop mode).

@@ -88,12 +88,12 @@

Chunks

NOTE Chunks data is not available during TRK debugging.

NOTE Chunks data is not available during CODA debugging.

Figure 4. Chunks Pane of Symbian OS View

Libraries Tab

The Libraries pane (Figure 5) in the Symbian OS view provides information on libraries in the Symbian OS residing on the target.

NOTE Library data is not available during TRK debugging.

NOTE Library data is not available during CODA debugging.

Figure 5. Libraries Pane of Symbian OS View

Attaching to a Process

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/reference/view_symbian_kernel.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/reference/view_symbian_kernel.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/reference/view_symbian_kernel.htm Wed Sep 15 09:40:16 2010 -0500 @@ -13,9 +13,9 @@

NOTE Any executable must be included in the Executables view before it can be debugged.

When the Time interval for auto-refreshing OS View option is enabled (which is on by default except for crash debugger), the data in the Symbian OS Data view will be auto-refreshed. Note that "auto-refresh" has a different meaning in different debuggers. During a stop mode debug session, the view will refresh data whenever the debugged program on the device is stopped and shows data as stale (greyed out) when the program is running. During a CODA debug session, the View will refresh data at a time interval regardless of whether the debugged program is stopped or not. The time interval is specified by an option in the Carbide.c++ global preference panel, which is five seconds by default.

Symbian OS Data pages

@@ -28,7 +28,7 @@

Chunks

Libraries

NOTE Information for the Chunks and Libraries tabs is not available when debugging with the TRK debug agent.

NOTE Information for the Chunks and Libraries tabs is not available when debugging with the CODA debug agent.

Overview Tab

@@ -55,7 +55,7 @@

Debug process or thread

Click the Debug button to attach to the process and debug the selected process or thread. Or right-click an item and choose Debug. This applies to both TRK (run mode) and TCF (stop mode).

Click the Debug button to attach to the process and debug the selected process or thread. Or right-click an item and choose Debug. This applies to both CODA (run mode) and TCF (stop mode).

@@ -88,12 +88,12 @@

Chunks

NOTE Chunks data is not available during TRK debugging.

NOTE Chunks data is not available during CODA debugging.

Figure 4. Chunks Pane of Symbian OS View

Libraries Tab

The Libraries pane (Figure 5) in the Symbian OS view provides information on libraries in the Symbian OS residing on the target.

NOTE Library data is not available during TRK debugging.

NOTE Library data is not available during CODA debugging.

Figure 5. Libraries Pane of Symbian OS View

Attaching to a Process

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/release_notes.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/release_notes.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/release_notes.htm Wed Sep 15 09:40:16 2010 -0500 @@ -30,6 +30,9 @@ changes making the tools unusable!

What's New in 3.0.0

The following features for Symbian development are provided within Carbide.c++:

CODA replaces TRK as the debug agent on remote devices. CODA (Carbide On-device Debug Agent) uses the TCF interface to provice improved communication support between the Carbide debugger and the remote device.

Milestone 2

A new Carbide.c++ Portal view provides easier access to Carbide information, an extensions marketplace, and support.

Run Mode Projects

The topics include:

Run Mode On-Device Debugging

Run mode on-device debugging enables you to download and launch a project on a phone or target device and debug it using the Carbide debugger. Before you can do that, some setup requirements are required. Once the setup is done, Carbide can then use plug-and-play (PnP) with USB to create a remote connection that connects with the TRK agent on the target device to download, launch, and debug the program.

Run mode on-device debugging enables you to download and launch a project on a phone or target device and debug it using the Carbide debugger. Before you can do that, some setup requirements are required. Once the setup is done, Carbide can then use plug-and-play (PnP) with USB to create a remote connection that connects with the CODA agent on the target device to download, launch, and debug the program.

Setup system and development requirements (below)
Install Application or System TRK v3.2.6 or later on the target device
Configure the environmental variables
(Optional) Setup a virtual drive to use Techview and Cust Kits

Once you've setup your environment, its time to verify that the TRK agent is on the phone or target device.

Once you've setup your environment, its time to verify that the CODA agent is on the phone or target device.

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_05.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_05.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_05.htm Wed Sep 15 09:40:16 2010 -0500 @@ -18,7 +18,7 @@

Setup a virtual drive for Techview and Cust Kits

Set the default kit in Devices.xml

Install the SISX file on the target device

Configure TRK connection on the device

Configure CODA connection on the device

Create a launch configuration

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_06.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_06.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_06.htm Wed Sep 15 09:40:16 2010 -0500 @@ -18,15 +18,15 @@

Setup a virtual drive for Techview and Cust Kits

Set the default kit in Devices.xml

Install the SISX file on the target device

Configure TRK connection on the device

Configure CODA connection on the device

Create a launch configuration

Install the SISX File on the Target Device

The on-device debug agent is delivered to the target device as a SISX file. There are two versions of TRK: Application TRK and System TRK.

The on-device debug agent is delivered to the target device as a SISX file. There are two versions of CODA: Application CODA and System CODA.

Application TRK— supports application debugging only and available to developers creating applications for devices. Developers do not have access to system level routines, system ROM, and other user application code. User cannot modify the LR and SR registers, and must use a SIS file to debug an application.
System TRK— supports both application and limited ROM debugging; including application executables and limited ROM based components (no device drivers). Also available to original equipment manufacturers (OEMs) for device creation and customization.
Application CODA— supports application debugging only and available to developers creating applications for devices. Developers do not have access to system level routines, system ROM, and other user application code. User cannot modify the LR and SR registers, and must use a SIS file to debug an application.
System CODA— supports both application and limited ROM debugging; including application executables and limited ROM based components (no device drivers). Also available to original equipment manufacturers (OEMs) for device creation and customization.

The following SISX file is officially signed by Nokia: s60_3_0_app_trk_2_6_nokia_signed.sisx

@@ -41,12 +41,12 @@

On the device you will be prompted to enter the same PIN code. Enter PIN code.

The device will then ask you to accept the connection request from the PC. Press OK.

The OBEX folder on the PC should now be available.

Drop the TRK SISX file into the folder

Drop the CODA SISX file into the folder

The device will prompt you to accept the connection request from the PC. Press OK.

The SISX file should then transfer from the PC to the device

Navigate to where the SISX file was placed

If you dropped it into the OBEX folder it will be in Applications > Messages > Inbox. If you dropped it into the C folder it will be in Applications > Utilities >FileBrowse > C.

Select the TRK SISX file on the device to install the TRK debug agent.

Select the CODA SISX file on the device to install the CODA debug agent.

Installing using PC Suite

Create a launch configuration

Configure TRK Connection on the Device

Configure CODA Connection on the Device

Connecting with Bluetooth

On the device make sure the Bluetooth port is turned on
On the phone launch TRK.

The location of the TRK on-device debug agent will vary based on the phone. On some phones it will be in the Installed folder, on others it may be in the My Own folder.

TRK will ask which host you want to pair with. When requested, select your computer from the available Bluetooth devices list.
After the host and phone are paired, TRK should be connected. Verify that TRK is running.
On the phone launch CODA.

The location of the CODA on-device debug agent will vary based on the phone. On some phones it will be in the Installed folder, on others it may be in the My Own folder.

CODA will ask which host you want to pair with. When requested, select your computer from the available Bluetooth devices list.
After the host and phone are paired, CODA should be connected. Verify that CODA is running.
On the PC:
1. Right click on the Bluetooth icon in the System tray and select Advanced Configuration
2. Click the Local Services tab
3. Write down the Bluetooth COM Port number from the Local Services tab (Figure 1).
4. Click OK to close the Bluetooth Configuration window
diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_08.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_08.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/debugger/run_mode_debug_08.htm Wed Sep 15 09:40:16 2010 -0500 @@ -31,8 +31,8 @@
To communicate between the Carbide.c++ debugger and the on-device debug agent or protocol interface you must define a debug launch configuration. The Debug window is where you define the type of debug launch configuration to use when debugging programs on the target device (Figure 4).

Figure 4. Debug Window
-
Select either a Symbian OS Application TRK or Symbian OS System TRK configuration type for on-device debugging and click New

For debug launch configurations using the TRK debug agent, the following pages require review and possible option settings:

Select either a Symbian OS Application CODA or Symbian OS System CODA configuration type for on-device debugging and click New

For debug launch configurations using the CODA debug agent, the following pages require review and possible option settings:

Main - defines the project to be launched on the target device
Arguments (Eclipse) - defines the arguments to be passed to the application and to the virtual machine

View messages between Carbide and debug agent

When checked, show the communications between the PC and the target device in a Console view when the TRK Communciation message log is visible.

NOTE You can pin the TRK Communication message log view so that it does not lose focus.

When checked, show the communications between the PC and the target device in a Console view when the CODA Communciation message log is visible.

NOTE You can pin the CODA Communication message log view so that it does not lose focus.

Message retry delay (ms)

Connection Tab

Select the Connection tab that is available for TRK. Specify the Serial port for your configuration. The Connection pane specifies the method used to transfer files to the target device. Once the Current Connection to Target type is selected, the remaining options contain default values for the specific connection type. You can change these options to match the target device's communication specifications.

Select the Connection tab that is available for CODA. Specify the Serial port for your configuration. The Connection pane specifies the method used to transfer files to the target device. Once the Current Connection to Target type is selected, the remaining options contain default values for the specific connection type. You can change these options to match the target device's communication specifications.

Figure 7. Debug windows Connection pane using PC Suite

Table 3. Connection pane

Installation Tab

For Application TRK select the Installation tab. The Installation pane specifies the .sis file to install on the target device. This is used by Application TRK because Application TRK downloads all files via a SIS file. This is required when using the TRK debug agent with 9.x based SDK’s.

For Application CODA select the Installation tab. The Installation pane specifies the .sis file to install on the target device. This is used by Application CODA because Application CODA downloads all files via a SIS file. This is required when using the CODA debug agent with 9.x based SDK’s.

Figure 8. Debug windows Installation pane

Table 4. Installation pane

File Transfer Tab

For System TRK select the File Transfer pane. The File Transfer pane displays a list of files the Carbide IDE transfers to the target device at the start of each launch. By default, any file added is automatically checked for downloading to the device.

NOTE If debugging a DLL from an application and using System TRK, ensure that the DLL is included so that it is deployed to the device with the application. It is not added by default.

For System CODA select the File Transfer pane. The File Transfer pane displays a list of files the Carbide IDE transfers to the target device at the start of each launch. By default, any file added is automatically checked for downloading to the device.

NOTE If debugging a DLL from an application and using System CODA, ensure that the DLL is included so that it is deployed to the device with the application. It is not added by default.

Figure 9. Debug windows File Transfer pane

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/processes/attach_to_process.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/processes/attach_to_process.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/processes/attach_to_process.htm Wed Sep 15 09:40:16 2010 -0500 @@ -13,7 +13,7 @@

Use a Symbian OS Attach to Process launch configuration to attach the debugger to an already running Symbian OS process or thread on a target device. This is useful for debugging DLLs where the main process is unknown or for servers running in RAM in a client-server relationship where the client relies on the presence of the server process to operate.

One common debugging DLL use case is when the developer doesn't know which process calls the DLL. This makes it difficult to debug the DLL because you doesn't know which process to attach to nor start. Carbide enables DLL debugging by simply attaching the DLL to any running process as long as the DLL is included in the Executables view.

You can also attach to a process in the Symbian OS Data view when debugging.

NOTE You cannot attach to a process running on the emulator. It must be a target device running the Symbian OS and the TRK debug agent.

NOTE You cannot attach to a process running on the emulator. It must be a target device running the Symbian OS and the CODA debug agent.

When attempting to find a process the debugger uses the UID3 to locate the process.

Attaching to any Running Process

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/prj_creating_sis_file.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/prj_creating_sis_file.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/prj_creating_sis_file.htm Wed Sep 15 09:40:16 2010 -0500 @@ -30,7 +30,7 @@ SIS Builder

Use the Add control to add one or more SIS or PKG files to the project up to the maximum number Carbide supports. Note that the SIS Builder pane operates on a build configuration level. You will need to add files in this pane for every build configuration in the project.

In addition, any PKG file added here is picked up by the Installation tab in Application TRK configurations. However, as only one SIS file can be debugged at a time you must specify which SIS/PKG file to install for debugging purposes. This is handy if you have both a developer SIS file and a certified SIS file that you want to remain in sync during development. Both are always built but you only need to debug one.

In addition, any PKG file added here is picked up by the Installation tab in Application CODA configurations. However, as only one SIS file can be debugged at a time you must specify which SIS/PKG file to install for debugging purposes. This is handy if you have both a developer SIS file and a certified SIS file that you want to remain in sync during development. Both are always built but you only need to debug one.

Figure 1 - SIS Builder tab

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/prj_debug_rom.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/prj_debug_rom.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/prj_debug_rom.htm Wed Sep 15 09:40:16 2010 -0500 @@ -9,13 +9,13 @@

Debugging in ROM

You will see symbolic information for other components when you are debugging in ROM using System TRK if those components were built with symbolic information and the ROM Log file is specified. If a function in the stack crawl is in a ROM module and the IDE is able to find a file containing symbolic information for that module, the IDE will load it automatically and display function names. The IDE will also allow source level debugging and let you set breakpoints in this module.

You will see symbolic information for other components when you are debugging in ROM using System CODA if those components were built with symbolic information and the ROM Log file is specified. If a function in the stack crawl is in a ROM module and the IDE is able to find a file containing symbolic information for that module, the IDE will load it automatically and display function names. The IDE will also allow source level debugging and let you set breakpoints in this module.

Some issues to pay attention to when debugging include:

In System TRK you must specify the ROM log file in the ROM Log tab of the TRK or Attach to Process launch configurations
In System CODA you must specify the ROM log file in the ROM Log tab of the CODA or Attach to Process launch configurations

-
NOTE You cannot debug ROM DLLs using Application TRK.
+
NOTE You cannot debug ROM DLLs using Application CODA.

diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/working_with_sis_pkg_files.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/working_with_sis_pkg_files.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/projects/working_with_sis_pkg_files.htm Wed Sep 15 09:40:16 2010 -0500 @@ -9,7 +9,7 @@

Creating a PKG File

After creating a project for the application you are developing for a device, you will need to create a .pkg file if you are using Application TRK. A .pkg file contains all the files that will need to be downloaded to the device. Once a .pkg file is available, you can add it to a project, and the IDE will use it and additional information entered in the SIS Builder pane to create an application's .sis installation file. By default, when creating a project, the .pkg file is located in the project's sis folder.

After creating a project for the application you are developing for a device, you will need to create a .pkg file if you are using Application CODA. A .pkg file contains all the files that will need to be downloaded to the device. Once a .pkg file is available, you can add it to a project, and the IDE will use it and additional information entered in the SIS Builder pane to create an application's .sis installation file. By default, when creating a project, the .pkg file is located in the project's sis folder.

A minimal .pkg file consists of the following lines:

Header — provides the following information on a single line: diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/start/carbide_example_trk.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/start/carbide_example_trk.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/start/carbide_example_trk.htm Wed Sep 15 09:40:16 2010 -0500 @@ -9,10 +9,10 @@ -
Run Mode Debug Example (Application TRK)
-
This example shows how to create and build an application and debug it on a device using the Application TRK on-device debug agent. The majority of steps are identical to the ones used to create a program and debug in an emulator, with some minor variations.
+
Run Mode Debug Example (Application CODA)
+
This example shows how to create and build an application and debug it on a device using the Application CODA on-device debug agent. The majority of steps are identical to the ones used to create a program and debug in an emulator, with some minor variations.
-
Debugging a Run-mode Project using Application TRK
+
Debugging a Run-mode Project using Application CODA
1. Import the Bld.inf to create a project using the Import wizard
2. Click the Debug icon () to launch the New Launch Configuration wizard
  1. Select the Application TRK Launch Configuration from the Launch Types page, then click Next
  2. Select the Application CODA Launch Configuration from the Launch Types page, then click Next
  3. If you have more than one executable, select the Main Executable in the Executable Selection page of the wizard, then click Next
  4. Select the remote connection to use in the TRK Connection Settings page, then click Next
  5. Select the remote connection to use in the CODA Connection Settings page, then click Next
  6. Select the SIS file to install in the TRK SIS Selection page if not already populated
  7. Select the SIS file to install in the CODA SIS Selection page if not already populated
  -
  Figure 4 - TRK Connection Settings page showing selection
  +
  Figure 4 - CODA Connection Settings page showing selection
  1. Click Finish
Related concepts
diff -r 549473f3167e -r b622387629d6 core/com.nokia.carbide.cpp.doc.user/html/tasks/trk/trk_install_pcsuite.htm --- a/core/com.nokia.carbide.cpp.doc.user/html/tasks/trk/trk_install_pcsuite.htm Wed Sep 15 09:33:14 2010 -0500 +++ b/core/com.nokia.carbide.cpp.doc.user/html/tasks/trk/trk_install_pcsuite.htm Wed Sep 15 09:40:16 2010 -0500 @@ -9,7 +9,7 @@
Installing On-device Debug Agents using PC Suite
-
Use the PC Suite software that came with your device (Nokia PC Suite is one example) to install the on-device debug agent, either Application TRK or System TRK, as a SISX file, to enable on-device debugging. Application TRK is usable on both consumer and RnD versions of the device. System TRK is only usable on RnD devices.
+
Use the PC Suite software that came with your device (Nokia PC Suite is one example) to install the on-device debug agent, either Application CODA or System CODA, as a SISX file, to enable on-device debugging. Application CODA is usable on both consumer and RnD versions of the device. System TRK is only usable on RnD devices.

The installation location of the on-device debug agent software varies based on the phone. On some phones it will be the Installed folder, on others it may be in My Own folder. Refer to the documentation that came with the phone to learn where installed programs are stored.

Using PC Suite you can install any TRK debug agent on the device using a Bluetooth or USB connection.

NOTE You can use the connection software that came with your device to install the on-device debug agent SISX file. See your phone's operating manual for assistance on using it's software.