This chapter explains how to setup WinGDB for debugging and building programs for bare-metal embedded devices with GDB-compatible OCD interface.
In this scenario the sources are stored and built on Windows using the gcc compiler. Then resulting binaries are written into the FLASH memory of the device, using appropriate tools. Usually the device is connected to development computer through JTAG interface. You will need both special hardware (e.g. "Wiggler"-type JTAG adapter) and software controlling it. Such software usually provides gdbserver emulator running locally on the development computer, allowing to connect with compatible GDB to it. WinGDB in turn, controls the GDB. Currently WinGDB supports OpenOCD interface.
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 an also work with embedded devices 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 Target specification. You do not specify any of the logins in this mode, so these settings are disabled.
WinGDB supports many possible scenarios of debugging with GDB. You have to select which one suits you. In this case, it will be "Embedded device (OCD)".
Target specification informs GDB how to connect to your GDB server emulator or stub. This is the same string that you provide as an argument for the target GDB command (without the "target" word).
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 int 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, Remote 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.
Debugging embedded devices usually requires some device-specific initialization that prepares the device for debugging (in simplest case just resets it). You have to write such script by hand. Then enter the path to the script in the Custom pre-load initialization script field on the Initialization page:
There can be many ways to deploy your program and it generally depends on the kind of the device, In case of ARM chips the program is usually written into the flash memory on the chip. You can either use an external utility for that, or provide special commands in the custom initialization file. Please consult your toolchain documentation on that topic.
WinGDB supports standard GDB load command for deploying. In many cases (e.g. CodeSourcery for ColdFire or Yagarto + OpenOCD toolchains) this command is the only one required. WinGDB will call it immediately after connecting to the target, before running the init script. To enable this feature, set the Load program when connected option. There are the following choices:
The load command accepts an optional argument specifying the executable image path. You can leave it empty, in that case GDB will use the image which has been specified for debugging. In some cases however it is desirable to load an alternate version of the image. You can enter the path in the Load path field:
You can also specify a post-load initialization script, which is executed after the load operation completes. Enter the path to the script in the Custom initialization script field on the Initialization page:
Standard pre- and post-load initialization scripts are executed also in case when the load operation has been skipped due to lack of changes in the image file.
On the other hand, conditional versions are executed only if the load operation actually has been (or is going to be) performed.
To be able to debug a program on the device, WinGDB needs to know the location of the binary file containing debug information. You specify it in Executable path field:
