ONEembedded.com

Samples can be found in the program installation folder by default (e.g. c:\Program Files (x86)\ONEembedded\ONEinspect\x.x\Samples). To work with them, we recommend to make a copy to a folder of your choice.

The Windows installer adds following to your computer:

1. All program files, help files, samples, plugins etc will be copied to the default system program directory,  (eg. c:\Program Files (x86)\ONEembedded\ONEinspect\x.x\)
2. Product quicklaunch link and an uninstall icon will be added to the default system start menu, eg. c:\ProgramData\Microsoft\Windows\Start Menu\Programs\ONEinspect\
3. Commands and icon references will be added to the system registry to open ONEinspect project groups and projects from the file explorer
4. Path to ONEinspect binaries (eg. c:\Program Files (x86)\ONEembedded\ONEinspect\x.x\)  is added to the PATH environment variable. This ensures that all postbuild steps calling the FormatConverter utility will work correctly.

All files and registry entries (including the entry in PATH variable) will be removed on uninstall.

Most of the UI has been tested with higher DPI settings but we still recommend using default DPI settings where possible. On Windows it is 100% font size, which corresponds to 96 DPI on most "classic" displays. These are the settings where the application has been originally developed and tested.

Well, this is really simple.

You already probably know we add the debug info with FormatConverter utility to the application binary file. FormatConverter reads the application binary file (usually an Intel hex file), adds ONEinspect debug information (usually few kilobytes of data) and saves the resulting binary file (usually again a hex file).

The resulting binary file is few kilobytes larger than the original one.

So far the theory.

However, it might be difficult for a "ONEinspect newbie" to understand how the debug info is exactly added to the application binary file and  how ONEinspect uses this later.

If you already are familiar with the samples then you probably know that they are always built with the bootloader/application scheme.
This might be complicated for starters so let's now assume a simple application, without bootloader feature.

Let's assume you already added target library into your application and you are able to communicate with ONEinspect.
Let's also assume an Eclipse based IDE (for other IDE's there might be slight differences, if your IDE is clever enough to support build configurations and postbuild steps).

Debug info placed at fixed address (simplest example)

Step 1

Add a new build configuration to your project and inherit its settings from your existing configuration.
Specify additional macro for the configuration, DIAG_APPLICATION.
The DIAG_APPLICATION macro tells the target library to use application configuration (and not the bootloader configuration).

Step 2

In postbuild settings, add commands which actually call FormatConverter to add ONEinspect debug info into your application:

For example:

arm-none-eabi-objcopy -O ihex ${BuildArtifactFileName} ${BuildArtifactFileBaseName}.hex
arm-none-eabi-objcopy --gap-fill 0xFF -O ihex ${BuildArtifactFileName} ${BuildArtifactFileBaseName}_fill.hex
FormatConverter ${BuildArtifactFileBaseName}_fill.hex ${BuildArtifactFileBaseName}_final.hex -d ${BuildArtifactFileName} -a 0x00020000

These postbuild commands first convert the ELF file to hex file, then fill empty places with 0xFF and finally add ONEinspect debug info from the ELF file to the resulting hex file, in this example at fixed address 0x00020000.

Note: This address must not be occuppied by your application otherwise FormatConverter won't succeed!

Note: If your IDE does not allow multiple postbuild commands just place them into a batch file (as shown in the samples).

Step 3

In your application code, setup access to ONEinspect debug info in a response to the Target Info command (function diagCbInfo in diag_arch.c file):

systemDesc->debugInfoAddress = (native_addr_t)0x00020000;
if (((DIAG_DEBUG_INFO_HEADER_T *)(native_addr_t)systemDesc->debugInfoAddress)->size != (uint32_t)0xFFFFFFFFU) {
  systemDesc->debugInfoSize = ((DIAG_DEBUG_INFO_HEADER_T *)(native_addr_t)systemDesc->debugInfoAddress)->size;
  systemDesc->debugInfoCRC = ((DIAG_DEBUG_INFO_HEADER_T *)(native_addr_t)systemDesc->debugInfoAddress)->crc;
} else {
  systemDesc->debugInfoAddress = 0U;
  systemDesc->debugInfoSize = 0U;
  systemDesc->debugInfoCRC = 0U;
}

These commands fill target info structure members with required values. There is also a simple check that given location is not empty (more detailed check might be implemented when needed).

Step 4

That's all! Compile the application and download to your target microcontroller using your FLASH download utility. Then connect with ONEinspect to your board and the debug info should load from your microcontroller FLASH to ONEinspect.

Debug info placed immediately after application code

Placing debug info at fixed address is very simple but it has some drawbacks:

1. You need to choose some location in FLASH to place the debug info and as your code grows difficulties might arise with that location (either application code suddenly begins to overlap with this location or debug info grows too large to fit into the FLASH area reserved for it).
2. You will get another significant gap in your application code, which might result in longer app flashing (more FLASH pages need to be erased etc.).

That's why normally (everywhere in our samples) we place the debug info immediately after the application code. This requires slight modifications.

Step 1

Is the same.

Step 2

Modify the FormatConverter call:

FormatConverter ${BuildArtifactFileBaseName}_fill.hex ${BuildArtifactFileBaseName}_final.hex -d ${BuildArtifactFileName} -s 0x00000100

This adds the size information of your application code to FLASH address 0x00000100. At this address 4 bytes must be reserved and not used by your application. You typically reserve the desired FLASH area in your linker command file, for example:

MEMORY
{
  m_interrupts  (RX)  : ORIGIN = 0x00000000, LENGTH = 0x00000100
  m_reserved  (RX)  : ORIGIN = 0x00000100, LENGTH = 0x00000004
  m_text  (RX)  : ORIGIN = 0x0000104, LENGTH = 0x000FFEFC

...etc.
}

SECTIONS
{
  /* Reserved area */
  .reserved_area :
  {
    *(.reserved)
    FILL(0xff)
  } > m_reserved  

...etc.
}

The size information normally encompasses entire data present in the source hex file. It always excludes the size of ONEinspect debug info data!

Step 3

In your application code, modify the assignment of debug info address in your target info structure (function diagCbInfo in diag_arch.c file) as follows:

// declare access to fixed address 0x00000100 somewhere in your app
__attribute__ ((section(".reserved")))
const uint32_t appSize = 0x00000000;

// inside of diagCbInfo:
systemDesc->debugInfoAddress = (native_addr_t)DIAG_APP_FLASH_START + *(volatile const uint32_t *)&appSize;

This way ONEinspect can find the debug info exactly at the end of your application code.
The DIAG_APP_FLASH_START macro must be set to correct value in diag_arch.h, ie. to the address where your application is loaded (in our example this address is 0x00000000).

Other commands in your diagCbInfo code remain the same.

Step 4

That's all! ONEinspect should be able to upload debug info again from this dynamically computed address.

Note: In our samples we add the application size information to the code segment accessible by both application and bootloader (section .boot_code). Furthermore, in our samples the bootloader is not built with integrated debug info because we want to minimize its FLASH footprint.

Debugging tips

In case something goes wrong and ONEinspect won't upload the debug info from given location, you'll need to find out where is the problem. Here are some tips:

• Compare the original hex file with the hex file produced by FormatConverter. Here you should find whether FormatConverter adds debug info or the size information (as described above) correctly.
• Flash your application and inspect given memory locations (either with your IDE debugger or with ONEinspect). Debug info should be present there.
• Calculate correctness of the dynamically computed address. Formatconverter adds the size information always in Little Endian byte order.
• Check if debug info is really stored at given address. There should be a debug info header present. This header consists of 2 32-bit integers. 1st is the debug info size in bytes, 2nd is the debug info CRC value. Again these values are stored in Little Endian order. See also DIAG_DEBUG_INFO_HEADER_T type in diagnostic.h for more information.
• If you want to debug the modified application (that contains ONEinspect debug info) with the debugger built in into your IDE (typically gdb) you might need to disable the integrated FLASH loader (which would otherwise flash the original application and destroy the ONEinspect debug info in your FLASH). This can be made by setting the option Attach only to True in your Debug configuration.

Best way to do this is adding the ONEinspect project (or project group as well) to your source code repository (Git, Subversion, Mercurial etc.) since ONEinspect projects are just XML files and can be easily tracked.

You should always use the newest ONEinspect project to access even older firmware versions. New data items (which are not compatible with the old firmware versions) will be marked red upon loading debug information from units with old firmware. Only in case you made bigger changes to your firmware you should use older, compatible version of the ONEinspect project.

In case you don't use debug information in ONEinspect you should always keep backward compatibility in your virtual addressing scheme (which typically is an ANSI C structure) and you should also mark bigger changes in your ONEinspect tables with captions.