The Kernel package includes the source code for the instdump command line tool. The instdump tool can be used to convert binary instrumentation data created by an application into human readable form, or into formats required by specific trace viewers. It can also be used to examine the information embedded in application images. The source for the instdump tool can be found in the BASE_DIR/packages/kernel/<version>/host/instr directory. The tool currently requires libelf for parsing the application image to extract the embedded information, and libiberty for C++ symbol de-mangling. It can be built as follows on a suitable Linux host:

$ cd $ECOS_REPOSITORY/kernel/$ECOS_VERSION/host/instr
$ gcc -o instdump instdump.c -lelf -liberty

A Windows binary can be cross-built on a Linux host, assuming a suitable mingw environment is available. The following example build sequence assumes that the relevant libiberty and libelf sources have been downloaded and un-packed into the relevant /tmp/mingw directories.

An example mingw libelf cross-build:

$ mkdir -p /tmp/mingw/build_libelf
$ cd /tmp/mingw/build_libelf
$ AR="i686-pc-mingw32-ar" CC="i686-pc-mingw32-gcc" ../libelf-0.8.13/configure --disable-shared \
  --disable-nls --enable-compat --target=i686-pc-mingw32
$ make
$ i686-pc-mingw32-ranlib lib/libelf.a

An example mingw libiberty cross-build:

$ mkdir -p /tmp/mingw/build_libiberty
$ cd /tmp/mingw/build_libiberty
$ CC="i686-pc-mingw32-gcc" ../libiberty/configure --host=i686-pc-mingw32 --disable-shared
$ make

Once the static libraries are available the actual instdump.exe can be compiled and linked by executing the following commands:

$ cd $ECOS_REPOSITORY/kernel/$ECOS_VERSION/host/instr
$ i686-pc-mingw32-gcc -I/tmp/mingw/libelf-0.8.13/lib/ -I/tmp/mingw/build_libelf/lib/ \
  -o instdump.exe instdump.c /tmp/mingw/build_libelf/lib/libelf.a \
  /tmp/mingw/build_libiberty/libiberty/libiberty.a

In the future extended versions of instdump or additional tools may be provided to make use of the embedded (INFO) sections for specific uses. For example, to convert the eCos specific binary instrumentation into other trace/instrumentation formats such as the Common Trace Format (CTF). The source code of instdump provides a useful example of how to extract and process the embedded sections and eCos trace information.

The tool provides a simple overview of its options by using the --help option.

The instdump tool can then be used to display embedded (INFO) data held within an ELF application image for verification of the embedded data. e.g.

$ instdump elfimage

It can also interpret raw binary instrumentation dump as produced by executing the elfimage application with whatever instrumentation capture support is suitable. e.g.

$ instdump --record-format instdata.bin elfimage 

The --instrumentation option allows a binary file of contiguous records to be passed. This would normally be used when examining memory buffer captures. The --record-format option allows the Cortex-M specific ITM record format to be parsed as captured by suitable SWD hardware debug interfaces (e.g. OpenOCD ST-LINKv2, PEEDI).

Further, when instrumentation data is being parsed then the --chrome-json option can be used to have instdump generate JSON trace-viewer compatible output. This can be displayed using the trace viewer that is built in to the Chrome browser. You can activate this by entering about:tracing as the URL, and then clicking the Load button on the tool bar that then appears.

If needed the example tool can extract the binary (INFO) sections if they need to be processed by some other tool. e.g.

$ instdump --only-section .ecos_inst_time -o time.bin elfimage

Though it should be noted that the standard objcopy tool also provides support for extracting arbitrary sections from an executable.

For backwards compatibility it can also be used to generate an instrument_desc.h compatible header.

$ instdump --gen-header --output instrument_desc.h elfimage

If the CDL option CYGDBG_KERNEL_INSTRUMENT_BUFFER_API is enabled then a simple API is provided to allow for the application to cleanly access the instrumentation buffer itself. Without this API the application is itself responsible for ensuring serialised access to the instrumentation memory to ensure that valid/complete records are interpreted.

	Note
	This API may be extended in the future to allow for multiple instrumentation buffers to be supported, allowing for better memory buffer instrumentation coverage (to minimise the times when records may be missed due to unavailability of buffer space).

The API has the following interface functions:

If needed the internal buffer lock control can be directly accessed via the cyg_instrument_lock() and cyg_instrument_unlock() functions. When the lock is held any calls to the underlying cyg_instrument() function will result in missed events since the aim is to never block the run-time processing from within the instrumentation recording support.

If GDB is being used to control the execution of the application, then when the CPU is halted it is very easy to save the instrumentation buffer to a file on the host. From the GDB prompt we can do something like:

(gdb) dump binary memory test.bin &instrument_buffer[0] &instrument_buffer[256]

to get hold of the binary data. For a system configured with buffer wrapping capture enabled (CYGDBG_KERNEL_INSTRUMENT_BUFFER_WRAP) this does not track where the active “head” of the captured data is. For “halt when full” capture then the above command is sufficient to record the instrumentation data.

When wrapping support is being used then the pointer variable instrument_buffer_pointer references the next slot to be filled. In conjunction with information regarding the instrument_buffer:

(gdb) p sizeof(instrument_buffer)

we can just access the relevant parts of the instrument_buffer address space and save the image in two parts if we want a time-ordered capture:

(gdb) dump binary memory file
  start
  end

(gdb) append binary memory file
  start
  end

It is envisaged that generic host tools like instdump (as described in Section 25.2.2.1, “ instdump tool”) will be used to examine the instrumentation data produced when used in conjunction with the ELF image for the application that generated the binary data.

/* this is a program which uses eCos instrumentation buffers; it needs
  to be linked with a kernel which was compiled with support for
  instrumentation */
#include <stdio.h>
#include <pkgconf/kernel.h>
#include <cyg/kernel/instrmnt.h>
#include <cyg/kernel/kapi.h>
#ifndef CYGPKG_KERNEL_INSTRUMENT_BUFFER
# error You must configure eCos with CYGPKG_KERNEL_INSTRUMENT_BUFFER
#endif
#ifndef CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER
# error You must configure eCos with CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER
#endif
struct Instrument_Record instrument_buffer[20];
cyg_uint32 instrument_buffer_size = 20;
int main(void)
{
  int i;
  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_CLOCK, 0);
  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_THREAD, 0);
  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_ALARM, 0);
  printf("Program to play with instrumentation buffer\n");
  cyg_thread_delay(2);
  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_CLOCK, 0);
  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_THREAD, 0);
  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_ALARM, 0);
  for (i = 0; i < instrument_buffer_size; ++i) {
    printf("Record %02d: type 0x%04x, thread %d, ",i, instrument_buffer[i].type, instrument_buffer[i].thread);
#if defined(CYGPKG_KERNEL_INSTRUMENT_TIMESTAMPS_HAL)
    printf("time %5d, ", instrument_buffer[i].timestamp_hal);
#endif // CYGPKG_KERNEL_INSTRUMENT_TIMESTAMPS_HAL
    printf("arg1 0x%08x, arg2 0x%08x\n", instrument_buffer[i].arg1, instrument_buffer[i].arg2);
  }
  return 0;
}

Here is how you could compile and run this program in the examples directory, using (for example) the MN10300 simulator target:

$ make XCC=mn10300-elf-gcc ECOS_INSTALL_DIR=/tmp/ecos-work-mn10300/install instrument-test
  mn10300-elf-gcc -c -o instrument-test.o -g -Wall -I/tmp/ecos-work-mn10300/install/include \
    -ffunction-sections -fdata-sections instrument-test.c
  mn10300-elf-gcc -nostartfiles -L/tmp/ecos-work-mn10300/install/lib -W1,--gc-sections -o \
    instrument-test instrument-test.o -Ttarget.ld -nostdlib
$ mn10300-elf-run --board=stdeval1 instrument-test

Program to play with instrumentation buffer
Record 00: type 0x0207, thread 2, time  6057, arg1 0x48001cd8, arg2 0x00000002
Record 01: type 0x0202, thread 2, time  6153, arg1 0x48001cd8, arg2 0x00000000
Record 02: type 0x0904, thread 2, time  6358, arg1 0x48001d24, arg2 0x00000000
Record 03: type 0x0905, thread 2, time  6424, arg1 0x00000002, arg2 0x00000000
Record 04: type 0x0906, thread 2, time  6490, arg1 0x00000000, arg2 0x00000000
Record 05: type 0x0901, thread 2, time  6608, arg1 0x48009d74, arg2 0x48001d24
Record 06: type 0x0201, thread 2, time  6804, arg1 0x48001cd8, arg2 0x480013e0
Record 07: type 0x0803, thread 1, time    94, arg1 0x00000000, arg2 0x00000000
Record 08: type 0x0801, thread 1, time   361, arg1 0x00000000, arg2 0x00000000
Record 09: type 0x0802, thread 1, time   548, arg1 0x00000001, arg2 0x00000000
Record 10: type 0x0803, thread 1, time    94, arg1 0x00000000, arg2 0x00000000
Record 11: type 0x0801, thread 1, time   361, arg1 0x00000001, arg2 0x00000000
Record 12: type 0x0903, thread 1, time   513, arg1 0x48009d74, arg2 0x48001d24
Record 13: type 0x0208, thread 1, time   588, arg1 0x00000000, arg2 0x00000000
Record 14: type 0x0203, thread 1, time   697, arg1 0x48001cd8, arg2 0x480013e0
Record 15: type 0x0802, thread 1, time   946, arg1 0x00000002, arg2 0x00000000
Record 16: type 0x0201, thread 1, time  1083, arg1 0x480013e0, arg2 0x48001cd8
Record 17: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000
Record 18: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000
Record 19: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000