Using the command line

Start a command shell (such as the Command shell in Windows) with the environment variables set as described in the toolchain documentation. Change to the directory in which you set up your build tree, and invoke GDB on the test program.

To run the bin_sem0 test (which will test the kernel for the correct creation and destruction of binary semaphores) type:

$ TARGET-gdb -nw install/tests/kernel/<version>/tests/bin_sem0

You should see output similar to the following in the command window:

Copyright (C) 2014 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=THIS-HOST --target=THIS-TARGET".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
Find the GDB manual and other documentation resources online at:
For help, type "help".
Type "apropos word" to search for commands related to "word".

If you are trying to run a synthetic target test on Linux, skip the following connection and download steps. Otherwise, connect to the target by typing:

(gdb) set remotebaud 38400
(gdb) target remote /dev/ttyS0

on Linux or

(gdb) set remotebaud 38400
(gdb) target remote com1

on Windows. To use a simulator in either host O/S use

(gdb) target sim

To use a temote host or target:

(gdb) target remote

or to use a pipe command to OpenOCD:

(gdb) target remote | openocd -f <path_to_target_config_file> -c "gdb_port pipe"

Check the documentation for the target board for the actual baud rate to use when connecting to real targets.

You will see output similar to the following:

Remote debugging using ...
0x0000d50c in ?? ()
    at <BASE_DIR>/kernel/<version>/src/common/kapi.cxx:345

Current language:  auto; currently c++

Or if you are using the simulator:

Connected to the simulator.

Now download the program to the target with

(gdb) load

You should see output similar to the following on your screen:

Loading section .text, size 0x4b04 lma 0x108000
Loading section .rodata, size 0x738 lma 0x10cb08
Loading section .data, size 0x1c0 lma 0x10d240
Start address 0x108000, load size 21500
Transfer rate: 24571 bits/sec, 311 bytes/write.

Now set a breakpoint to trap the target once the test has completed execution:

(gdb) break cyg_test_exit

If you are running the test on the target through a hardware debugger you should additionally run the following command

(gdb) set hwdebug on

This will set a flag within gdb telling it to extract diagnostics messages from a pre-determined location on reaching a pre-defined hardware breakpoint, display them on the GDB console, and resume execution automatically. This is useful in the absense of other external mechanisms for the target hardware to emit debug messages (e.g. through a serial port) but does also normally require enabling the eCos options CYGFUN_HAL_DIAG_VIA_GDB_FILEIO and CYGFUN_HAL_GDB_FILEIO within the eCos configuration. The set hwdebug on is harmless if executed when the above eCos options are not set.

You are now ready to run your program. If you type:

(gdb) continue

you will see output similar to the following:

PASS:<Binary Semaphore 0 OK>

Note: If you are using a simulator or the synthetic target rather than real hardware, you must use the GDB command “run” rather than “continue” to start your program.

You can terminate your GDB session through Control+C if the target is still running and the breakpoint cyg_test_exit was not reached, otherwise it will sit in the “idle” thread and use up CPU time. This is not a problem with real targets, but may have undesirable effects in simulated or synthetic targets. Type quit once back at the gdb prompt and you are done.

Documentation license for this page: Open Publication License