This chapter explains how to setup WinGDB for debugging and building programs for embedded Linux systems.
In this scenario the sources are stored and built on Windows using a cross compiler. You will need a toolchain, a specialized bundle of development tools for your embedded system. A toolchain usually includes the compiler, linker and debugger, as well as other tools. After compiling on Windows, the binary is transfered to the device and executed there. The GDB debugger is then executed on Windows and connects with its on-device counterpart (called "gdbserver").
This situation differs from remote Linux development in sources and tools location. To conserve space on the device, all of them reside on local Windows host machine. Only actual binaries are copied onto the device.
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 embedded Linux using WinGDB without any special project type. Just use any C++ project type that Visual Studio offers, e.g. Console application. This facilitates on-host testing possible with some embedded platforms, where special libraries emulate various aspects of the device.
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 location 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.
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.
To be able to build programs under Visual Studio, the location of the tools used for building (like the compiler, linker, make, etc.) must be known. This can be done either by appropriately configuring the system PATH variable, or by specifying paths to search in Default toolchain location field in the preferences. Multiple paths can be entered, separated by a semicolon.
Alternatively you can specify these paths in project or solution properties (Build toolchain paths setting on Environment tab). This will override the global setting described above. Thus, you can use a different toolchain in different projects or configurations. To return to default toolchain, 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 the 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).
Your embedded device may provide some shell access allowing to log in and perform operations. It is not required by WinGDB, but if present, it enables additional features: remote file system browsing and automatic gdbserver launch (see below). The only protocol currently supported is SSH. There are plans to add some other protocols in subsequent versions.
To configure that optional shell access, enter login information in Debug target login field. You specify it in the following format:
username[:password]@host[:port]
Parts in brackets are optional. If you do not specify the port, default one equal to 22 will be assumed, If you do not specify the password, WinGDB will ask you for one later. You can specify either host name or IP address. You can find more information about supported authentication methods in this section.
Linux systems come with a set of standard, system-wide shared libraries. These libraries must be available during various stages:
For typical server/desktop Linux development, in all of these cases the libraries reside on Linux host. But when using a cross-compiler, situation is more complicated. Generally a copy of each library must be located both on the target device and on host system where the development is performed.
The root directory where all system libraries are located is called sysroot. There are two sysroots: the one on target device and another one on host computer. The files contained in these two directories should be identical. You must specify locations of these directories in Sysroot on target and Sysroot on host fields. Otherwise GDB won't be able to locate shared libraries and some debugging options may not work. Sysroot on target may be equal to the filesystem root directory on the device. It's not recommended however, as toolchains often come with their own versions of system libraries.
In order to debug embedded Linux programs you will need a special program called gdbserver. It should be included in your toolchain. It must be installed onto the device. Usually it is bundled with all the libraries in the sysroot. Please consult your toolchain 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:
You can also specify port forwarding. Use this option when the port gdbserver is listening on is visible on the debug host machine under different number. It can happen when using some special communication protocols, like TCP over USB. Some mobile devices use such protocols. To enable port forwarding, set the Server port is forwarded and enter host-visible port number in Forwarded server port field. Typically this feature is disabled.
Either automatically or manually, gdbserver can be started in one of three modes. These modes are relevant in two cases: when you perform the process launch function (Start debugging, Launch process or Start new instance in Visual Studio), or start the server manually. When performing Attach to process option in Visual Studio, WinGDB will always use the automatic attach mode, regardless of this setting (SSH connection is required for this). You specify the mode in Server mode field:
If you use manual start mode, the above option has to be properly set as well. WinGDB must know how to interact with gdbserver.
The remaining options are specific to the automatic server start mode.
If the gdbserver executable is located inside the sysroot package, some special actions must be performed to start it. WinGDB does them if Launch server from sysroot option is turned on. The dynamic linker is used explicitly and shared libraries required to run gdbserver itself are loaded from the sysroot, not the system-wide location. You can specify relative location (to the sysroot) of the linker and the library directories, in Sysroot dynamic linker path and Sysroot shared library paths. Also the path entered in Path to gdbserver should be relative to the sysroot. In case of CodeSourcery Lite toolchain (and probably most others) the default settings should be appropriate.
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. Go to the Project build tab in the Properties dialog. 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 Rebuild and Clean and Deploy options to perform these 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, birefly mentioned above:
You can initiate deployment either manually (using Build/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, Files 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.
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.
As mentioned above, there are several ways to attach to a process:
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.
Devices running embedded linux systems forms a very broad range of platforms: mobile phones, microcontrollers, network routers, and many more. It's not guaranteed that WinGDB will work without problems with every such device. Up to version 1.8, we have tested it on ARM-based development boards and CodeSourcery Lite toolchain for ARM. If you need support for different processor or toolchain, please contact us.
In the table below, there are listed configurations that we tested WinGDB on with success. If your configuration is not listed, it does not mean it won't work. We just were unable to test it due to lack of access to particular hardware. Usually the compatibility depends more on toolchain used than on the hardware. We encourage you to test WinGDB on your configuration and contact us in case of any problems.
| Vendor | Name | CPU | System | Toolchain | Type |
| Propox | MMnet 1001 | AT91SAM9260 | Linux/OpenWRT | CodeSourcery G++ Lite 2009q1-203 | Development board |
| Embest | Devkit 8000 | TI OMAP3530 | Linux/Angstrom | CodeSourcery G++ Lite 2009q3-67 | Development board |
| Palm | Pre | TI OMAP3430 | Palm webOS 1.4 | CodeSourcery G++ Lite 2009q3-67 | Mobile device (smartphone) |