Debugger-based On-Target Testing
Release Notes

Features

DOTT.NG - Debugger-based On-Target Testing framework 'new-gen' supporting:

  • On-target testing of unmodified firmware functions.
  • Selective injection of data into execution flow.
  • Execution of test on host machine.

Documentation

Documentation comes as an integrated package in HTML format which contains the following chapters:

  • Overview
  • Release notes and changelog
  • Setup instructions
  • Component testing guide
  • System testing guide
  • Developer's guide
  • Reference platform
  • External test equipment

Test Level

  • All testing is performed with Python v3.10 and 3.12.
  • Tests are performed on Windows 10 (64 bit) and Ubuntu Linux 22.04 (64bit).
  • Limited testing is performed on Manjaro (Arch) Linux and Windows 11.

Changelog

1.17.0

  • Made NotifySubscriberExt the default implementation.
  • Enhanced InterceptPoint performance.
  • Update usages of log.warn with log.warning.

1.16.0

  • Release is considered deprecated as stability issues on Windows 11 were discovered.

1.15.1 (2024/06/23)

  • Changed behavior of notification propagation: Strict ordering of notifications is now maintained.
  • Added GDBMI in memory log dump (enabled via environment variable DOTT_DEBUG_GDBMI=1) when HaltPoint is not reached.
  • Added target.finish() which resumes execution of the current target function and returns when the function is completed. The target is then in halted state.
  • Added reason sanity checks to calls for wait_halted.

1.15.0 (2024/04/24)

  • Added exception propagation from sub threads to main thread.
  • Improved fairness for notifications for threads waiting for halted/running events.
  • Enhanced GDB server port auto increment.
  • Added snippet which illustrates handling of function pointers in Arm Thumb mode.

1.14.0 (2024/03/08)

  • Added DOTT register access classes.
  • Added svd2dott command line tool to convert CMSIS SVD peripheral and register descriptions to DOTT register classes.

1.13.1 (2024/02/10)

  • Enhanced thread handling for GDB MI response management.

1.13.0 (2024/02/06)

  • Added fast in-memory log capture utility for GDBMI tracing (enabled via environment variables: DOTT_DEBUG_GDBMI=1 and DOTT_DEBUG_GDBMI_DUMP_ON_EXIT=1).
  • Fixed potential issue where target state was captured incorrectly in target halt/cont calls.
  • Improved state change handling in source line and instruction stepping commands.

1.12.1 (2024/01/27)

  • Raise value error if zero bytes of on-target memory are requested to be allocated.
  • Allow to skip setting target as default target if there is no default target yet.

1.12 (2024/01/24)

  • Fixed issue where singleton was not correctly accepting constructor parameters.
  • Default target is no longer mandatory (see examples in 03_snippets).
  • Deprecated method Dott.create_gdb_server() has benn removed.
  • Updated DottConf(Ext) documentation.
  • DottConfExt.parse_config() has new silence argument.
  • DOTT logger can now be also accessed via dott().target.log property.

1.11 (2023/11/26)

  • DOTT-NG is now compliant (and tested) with Python 3.12.0 (64bit).

1.10 (2023/11/13)

  • Added first support for PE-Micro debug probes via PE-Micro gdb server from Eclipse plugin
  • Fixed issue with alignment calculation of scoped on target memory allocator
  • Officially changed minimum Python requirement to 3.10.

1.9.3 (2023/08/01)

  • Fixed issue where target was not propagated to HaltPoints created in fixture helpers.

1.9.2 (2023/07/30)

  • Allow app_symbol_elf to be not set in DottConf (and avoid issue when app_load_elf is not set either).
  • Omit startup info messages about J-Link if monitor type is not J-Link.

1.9.1 (2023/07/16)

  • Updated stopping of sub-threads with now stop automatically when the main thread terminates. With that, the dott_auto_connect_and_disconnect fixture was removed.
  • Allow app_load_elf to be not set in DottConf.
  • Changed location of gdb_pre_connect_hook and passing the target instance to it.

1.9.0 (2023/07/09)

  • A new pre-connect gdb_pre_connect_hook was added which is called before GDB client connects to GDB server.
  • Internal re-work of debug monitor and gdb server creation.
  • Ongoing internal re-structuring of the DottConf configuration mechanisms resulting in API changes listed below:
  • The method dott().create_gdb_server(...) will be deprecated as part of API refinement. Use dott().target.monitor.create_gdb_server() instead.
  • The parameter jlink_serial was removed from dott().create_target(...).
  • Monitor type can now be a (fully qualified) class name which is then instantiated and used.

1.8.1 (2023/05/27)

  • Added DottConf parameter gdb_connect_timeout to adjust the timeout when connecting to a GDB server instance.
  • Added DottConf parameter fixture_timeout to adjust the timeout used in default fixtures when waiting for halt points.
  • Breakpoint now interprets int location as address (no need to pass string with * prefix).
  • Internal restructuring of DottConf.

1.8.0 (2023/03/17)

  • Added new convenience functions mem.write_intX(), mem.write_uintX(), mem.read_intX() and mem.read_uintX().
  • Added quicksort example to getting started demo code.
  • Fixed issue with J-Link extra config option.
  • Added support to ignore timeout when disconnecting from GDB client where the target was already reset.

1.7.2 (2023/03/14)

  • Fixed compatibility issue with Python 3.11.
  • Added J-Link extra config option to DottConf.

1.7.1 (2023/03/05)

  • Internal change: Replaced "GDB server quirks" with more generic debug monitor abstraction.
  • Now raising exception if amount of memory allocated via alloc_type and initialization value are incompatible.
  • New DOTT config option to specify JLink script for JLink GDB server initialization.

1.7.0 (2022/11/18)

  • First version of DOTT released under its new name DOTT.NG which is a fork of the original ams DOTT framework. Consider ams DOTT as deprecated. Development will continue on the DOTT.NG fork.
  • DOTT.NG 1.7.0 is fully feature compatible with ams DOTT 1.6.4. Module names (and hence imports) remain the same.
  • The Python packages now carry the names dott-ng and dott-ng-runtime.
  • The included examples are now built with the free Arm GNU toolchain instead of the proprietary Arm Compiler 6.
  • Fixed (cosmetic) issue where gdb stdout was shown in foreground on Linux when running pytest with '-s' flag.

1.6.4 (2022/09/29)

  • Avoid halting already halted target (causing issues with OpenOCD)
  • Improved breakpoint-hit handling for OpenOCD.

1.6.3 (2022/05/10)

  • Fix versions of most important dependencies (as, e.g., pygdbmi).
  • Add index notation for TypedPtr to access elements of arrays allocated on-target. See test_example_SumElements in test_example_functions.py.

1.6.2 (2022/01/20)

  • If GDB server is detected as OpenOCD, monitor reset halt is used instead of monitor reset in dottmi.target.Target.halt().

1.6.1 (2022/01/16)

  • Added quirks to support OpenOCD's naming of xPSR register and monitor commands.

1.6.0 (2021/12/08)

  • Added optional timeout to dottmi.target.Target.eval().
  • Added C:\Program Files\ to search path for JLink dll (supporting 64bit JLink releases).
  • Ignore instances of JLink dll where not JLink GDB server binary is in same folder (e.g., ignore Ozone install dirs which have a JLink DLL but no GDB server binary).
  • If dottmi.target.Target.eval() returns a CPP reference, the address is prefixed with @ by GDB. The leading is now automatically removed from the address.
  • Added decoder/pretty printer dottmi.target.Target.reg_cm_xpsr_to_str(). for Arm Cortex-M xPSR register.
  • Halting the target via dottmi.target.Target.halt() now ensures by default that the target is halted outside an IT block. This behavior can be changed via the new optional parameter halt_in_it_block
  • Fixed parsing issue for BL symbol address in dott.ini.

1.5.1 (2021/08/06)

  • Fixed issue where dottmi.target.Target.ret() when used without return value failed.
  • Enhanced (internal) mechanism which reports the target's state (running or halted).

1.5.0 (2021/06/18)

  • minor code cleanups
  • DOTT released to Open Source community

1.3.2 (2021/04/22)

  • Removed unwanted debug message.

1.3.1 (2021/04/15)

  • Added new function to flush GDB's internal register cache. This is useful if the target is reset by other means than GDB and hence GDB is not aware of this reset (and the register changes resulting from it).
    • dottmi.target.Target.reg_flush_cache()
  • The function dottmi.target.Target.reset() now automatically flushed the GDB register cache. This can be altered by setting the flush_reg_cache parameter.
  • DOTT's default FLASH and SRAM reset fixtures (which use dottmi.target.Target.reset()) now also flush the GDB register cache.

1.3.0 (2021/03/10)

  • Added support to disconnect and reconnect a target's GDB client from the GDB server. Target API additions:
    • dottmi.target.Target.gdb_client_connect()
    • dottmi.target.Target.gdb_client_disconnect()
  • Added support to stop a target's GDB server and to set a (new) GDB server instance for a target. Target API additions:
    • dottmi.target.Target.gdb_server_stop()
    • dottmi.target.Target.gdb_server_set()
  • Added support to created GDB server instances by users. Dott API addition:
    • dottmi.dott.Dott.create_gdb_server()
  • Added check to detect if TCP ports used by GDB server are available before starting the server. If unavailable, port numbers are automatically advanced to the next free ports. Port incrementation now automatically wraps around when approaching the 16bit port limit.
  • Fixed typo in setup guide.

1.2.1 (2021/01/08)

  • Enable setting breakpoints to a known address (and not only to symbols).
  • Corrected handling of char pointers when reading a character address.
  • Added jlink_remote_addr and jlink_remote_port to developer guide.

1.2.0 (2020/11/17)

  • Added alignment option for on-target memory requested via the TargetMem allocator.
  • Scoped on-target memory allocation now officially supported.
  • Relaxed too strict checks for scoped memory implementation.
  • Updated pre-stack on-target memory allocation model.
  • Added NOALLOC on-target memory allocation model.
  • Added note about Segger FLASH caching to developer guide.

1.1.0 (2020/11/05)

  • Linux is now officially supported (requires DOTT runtime version >1.1.0).
    • Dedicated ams-dott-runtime Python packages are now provided for Windows and Linux.
    • The DOTT framework itself (ams-dott) remains a single, platform-independent Python package.
  • Preview of scoped on-target memory implementation for use instead of test_hook based memory allocation.

1.0.4 (2020/09/17)

  • Fixed incompatibility with changes introduced in pygdbmi version 0.10.0.0.

1.0.3 (2020/02/11)

  • Updated DOTT license to Apache 2.0.
  • Structural simplifications in preparation for release on GitHub.
  • Enabled JLink serial number configuration for multi-JLINK setups.
  • Moved dott.ini to the same folder as base conftest.py file. dott.ini is no longer mandatory (i.e., all settings can be made via DottConf).
  • Introduced DottHooks to enable target configuration before debug ports are accessed.
  • Added setup_cb to _target_reset_common for early, device-specific setup.
  • Added DOTT_RUN_SRAM environment variable for examples 1 and 2 to run them from SRAM; binaries are now available for both SRAM and FLASH.
  • New fixture 'target_load_symbols_only' which loads application symbols but does not perform target download.
  • New fixture 'target_load_flash_always' which loads the application binary to the target on a per-test basis (vs. target_load_flash which only loads once per test session).
  • Added setup.py to create wheel package which includes the required GDB and WinPython2.7 dependencies.
  • Made base function for load and reset fixtures public; in addition they take the target as an optional argument (useful for multi-target setups).

1.0.2 (2019/05/16)

  • Fixed issue where GDB server was not correctly started automatically.
  • Linux (Ubuntu 18.04) has been successfully tested as runtime environment for DOTT.
    • Minor modifications have been done (e.g., ensuring that all path delimiters are platform independent).
    • Target live access is currently not supported on Linux hosts.
    • JLINK gdb server auto-launch is currently not supported on Linux hosts.
    • Overall, Linux support is currently provided 'as is'. Testing of DOTT releases is still only done on Windows 10.

1.0.1 (2019/04/17)

  • Extended dott().target.mem.read() function to also accept src address as TypedPtr and str (besides int).
  • Fixed issue in reset fixture for SRAM-based applications.
  • Added note about C++ namespaces to developer's guide.
  • Added 'InterceptAtLabel' example to example tests.

1.0.0 (2019/01/25)

  • First official release.
  • Backend now based on GDB machine interface.
  • Support for component and system testing (free-running target).
  • Live target access support (access target memory while target is running).
  • Includes full set of examples for component and system testing.
  • Examples can be executed out of the box on a low-cost reference board.
  • Includes self-contained template project.
  • Supports on-the-fly data injection (modifying target memory).
  • Supports PiGPIO daemon for as SPI, I2C, GPIO, UART, ... interface to target.
  • Supports multi-binary applications (bootloader + application firmware).

"Preview"

  • Preview release for ams Software Conference 2018.

Known Issues and Limitations

  • Only Arm CLANG (Arm Compiler 6) is supported. GCC support is planned for later versions.
  • Number of hardware breakpoints supported by the target is not checked. It is up to the user to not use more than the maximum number of concurrently available hardware breakpoints in a single test.
Generated by doxygen 1.9.5