This chapter explains how to setup WinGDB for debugging and building native programs for webOS system.
Palm webOS have two layers available to application developers:
WinGDB in current version can be used for the second type of development. You will have to install PDK from Palm's developer website. Please refer to documentation available on that site for information how to install PDK and configure your device. To get started with WinGDB you should be able to log in to the device using putty. PDK installs the novacom communication utility which allows TCP over USB connections. Your device must be connected via USB to your computer, and the developer mode must be enabled on it. It is also recommended to upgrade to the latest webOS version.
Apart from some initial configuration steps, this debugging scenario does not differ from regular embedded Linux development. Palm webOS is just a special case. The rest of this chapter explains how to configure the embedded mode specifically for webOS.
In case of webOS, you will use a CodeSourcery Lite toolchain which comes along with PDK. Unfortunately, for currently available PDK beta there is a version mismatch problem. Libraries present on the device do not match libraries present in the PDK. This problem can be solved by executing the following steps before startng the development.
gdbserver --version command. You should
see some output like this:
GNU gdbserver (CodeSourcery Sourcery G++ Lite 2007q3-51) 6.6.50.20070821-cvs Copyright (C) 2007 Free Software Foundation, Inc. gdbserver is free software, covered by the GNU General Public License. This gdbserver was configured as "arm-none-linux-gnueabi"
arm-none-linux-gnueabi
subdirectory. There should be another subdirectory called libc there.
/lib
and /usr/lib to arm-none-linux-gnueabi/libc/lib
and arm-none-linux-gnueabi/libc/usr/lib, overwriting already existing
libraries.
Above instructions apply to webOS 1.4.1 and PDK beta version. It is possible that for newer versions they become unnecessary.
One of possible options to start work with WinGDB is using a project template from the New Project dialog. Here you can choose from several project types: executable program, static library or shared library (shared libraries are not supported on some kinds of platforms).
This option creates the project and opens Project configuration wizard described below.
You can also work with webOS using WinGDB without any special project type. Use native C/C++ project, as recommended in the PDK documentation. This way you will be able to debug both host-emulated version and the device. We recommend that you create separate configurations for that in your project.
WinGDB works with Visual Studio solution configurations. After creating the project, it is recommended you review configurations that Visual Studio creates. By default, these are Debug and Release configurations. If you want only to work on single platform, you may configure WinGDB for these configurations. If you plan multiplatform development, please read remarks on multiple configurations and platforms here.
The rest of this document covers the detailed configuration mode. You do not need to perform the steps described below while using the wizard, as it does them for you. It is however recommended to read the following sections and other documentation chapters, as they explain the Properties interface required to to utilise full capabilities of WinGDB. Some settings are also adjustable globally, using the Preferences dialog from main WinGDB menu.
To be able to debug with WinGDB, you must let it know the debugger
location. To set that information, choose Preferences option from WinGDB
menu. There is Default debugger path field in the preferences. You
can enter full path to the debugger executable, or only the executable
name. In the second case you have to configure your PATH variable
on Windows host, so that the executable can be found. In both cases,
GDB version from appropriate CodeSourcery installation directory should
be specified (for example,
C:\Program Files\CodeSourcery\Sourcery G++ Lite\bin\arm-none-linux-gnueabi-gdb.exe).
Alternatively you can specify the debugger path in project or solution properties (Debugger path setting on Environment tab). This will override the global setting described above. Thus, you can use a different debugger in different projects or configurations. To return to default debugger, reset the Properties setting to default value.
The most important properties adjustable for a project or solution, are Target Type and Debug target login. Other machine roles (Debug Host and Build Host) are fulfilled by the local machine, so you do not specify these logins.
WinGDB supports many possible scenarios of debugging with GDB. You have to select which one suits you. In this case, it will be Embedded Linux system (gdbserver).
In order to browse files on the device and start gdbserver automatically,
you will need to set the Debug target login. There exists a fixed
login for webOS installations. For webOS 1.4.x it will be root:pw@localhost:10022.
The default password and port might be changed in future webOS versions, although it's
unlikely. The usage of local host and port 10022 is a consequence of the working
of novacom communication utility installed on your system by the PDK.
The utility forwards all communication from port 22 on the device to port 10022
on your host. In the middle, it maintains a TCP over USB data link.
For detailed explanation of the sysroot concept, please see
embedded Linux chapter. For webOS
you have to enter only Sysroot on host setting. You should enter
full path to libc subdirectory inside your CodeSourcery
installation, for example
C:\Program Files\CodeSourcery\Sourcery G++ Lite\arm-none-linux-gnueabi\libc.
Leave the Sysroot on target field empty, as in webOS case the
system-wide libraries are used.
PDK comes with some additional libraries for webOS development. You should add the path to these libraries location to Shared library directories field (on the Directories tab):
In order to debug webOS programs you will need a special program called "gdbserver". It should be already installed on your device. Please consult PDK documentation for details.
When gdbserver is installed, you have to decide how do you want to start it. With WinGDB you have two options: automatic or manual mode. This setting is located on the Debug tab:
Either automatically or manually, gdbserver can be started in one of three modes. You have to specify the mode in Server mode field:
This option should be properly set both in manual and automatic mode, since WinGDB must know it to properly interact with gdbserver.
The Launch server from sysroot option should be disabled for webOS:
WinGDB includes a simple makefile generator. This generator automatically creates a makefile from current project. Generated makefiles can be used with standard GNU make. Other build systems are in plans. The generator is optional, you can write your makefile by hand if you wish, or use a build system which is currently not supported.
You can find more information about the makefile generator in this section.
WinGDB has a simple mechanism to control compilation using make or any other build system. It works both in remote and local mode. It can start any build command, however if you want to be able to locate errors and warning in the source code, the build command output must be compatible with standard make and gcc message format. For best results, use standard GNU make.
You have to set some additional properties before using it. Right click on your project in Solution Explorer and open the Properties dialog. You do not have to enter any login information, since the build will be performed on local machine. Go to the Project build tab. Here you can set the following properties:
If you click on solution instead of project, there will also be shown another tab, Solution build. On that tab there is a similar set of options, this time concerning the whole solution. There is also one new option, Solution build mode. You can choose whether the soluton build will execute a build command for each project (with respect to their dependencies), or run build commands configured by the remaining options. Use the first possibility when you do not have a separate makefile for the whole solution, and the second one when you do have.
Apart from Solution build, there is also regular Project build tab. On that tab you can set default settings for the projects, which can be then selectively overridden on any project settings page.
To start the build, choose one of options from the Build submenu from WinGDB menu on any project or solution in Solution Explorer. You will see results in the console. When you click on an error or warning, the code editor will jump to appropriate place in the code.
You can also use Remote rebuild and Remote clean options to perform these alternative actions.
After successful build, the resulting executable must be somehow transferred to the device to be run or debugged. WinGDB offers simple deploy mechanism which can work in one of two modes:
You can initiate deploying either manually (using Remote deploy command) or automatically, before starting debugging. To enable automatic deploy set the Deploy before start debugging setting.
Both deploy modes can be configured to skip automatic deploy step when specified file has not been changed since last deploy. To enable this, set Deploy only if file changed option. In this case, the File to deploy must be set also in Run deploy command mode. Note that the skipping will be performed only whe performing automatic deploy. You can always force deployment using the Remote deploy option.
Most options described above exist both on project and solution levels. The Deploy before start debugging option exists only for projects as it is coupled with the Build before start debugging option. Automatic deploy will occur only when automatic build has been performed (otherwise there would be nothing to deploy) and the deployment scope is the same as for the build: project deploy for project build and solution deploy for solution build.
To launch a program in debug mode, WinGDB needs to know the full path of the program both on the host and the device. You specify the first one in the Executable path field on Debug tab, just as in other debugging modes.
The corresponding path on the target is entered into Executable on target field on Target tab.
You can also set some optional parameters, like program Arguments, additional Environment variables and Working directory. If you set Stop in main() option, the program will stop at the beginning of main() function. This option is added for convenience, as you can achieve the same effect by setting a function breakpoint in Visual Studio before starting the program.
In Attach mode, gdbserver needs to know the process ID to attach to. You can enter it in PID on target field. Currently there is no way to browse processes, hence you have to find it manually and enter the PID into the field. This will be addressed in some of next versions of WinGDB.
Mobile devices are usually conected to host computer through USB interface. This can make debugging slow, especially when the program is non-trivial and the number of stack frames and local variables is large. USB links tend to have high latency and GDB serial protocol is not efficient in this case due to large number of small packets being transmitted.
WinGDB offers a mechanism to accelerate the communication. To turn it on, switch Enable protocol controller to Yes. This mechanism work only for TCP connections. It will not make much difference on already fast links (Ethernet), however for USB devices like Palm webOS ones the speedup should be noticeable.
Since this feature is relatively new, it still might contain bugs that have not yet been detected, in spite of thorough testing. If you experience problems (most likely manifesting as hangs), please contact wingdb@wingdb.com. The accelerator has a diagnostic mode, enabled by entering non-zero logging level to Protocol controller log level field, and a path to the log to Protocol controller log file. Please include the log file in your report. For best results set the level to 4. During normal work disable logging by entering zero log level, as logging decreases the performance.
