v0.24.1

Fixes

• Fixed regression where programming an ELF file failed, caused by missing import. (Thanks @DurandA!)

v0.24.0

New features

• Support for legacy AP BASE register formats seen on early Cortex-A platforms. While Cortex-A cores are not supported yet, pyOCD can at least read the ROM tables and identify the cores now.
• Support for the new SWJ sequences introduced in ADIv5.2 with SWJ-DPv2. These sequences transition between SWD and JTAG by going through a dormant mode. By default, pyOCD will first attempt the deprecated SWJ sequences, then if that fails it will attempt the new sequences.
• New user options:
  • dap_protocol: One of swd, jtag, or default. (JTAG is still not fully supported, but is getting closer.)
  • dap_enable_swj: Whether SWJ sequences are sent (default True).
  • dap_use_deprecated_swj: Whether to attempt deprecated SWJ sequences (pre-ADIv5.2). Most Cortex-M MCUs do not support the new sequences.
  • probe_all_aps: Force a scan of all 256 AP addresses instead of stopping the AP scan at the first invalid AP.
  • xpsr_control_fields: Defines bitfields for XPSR and CONTROL registers when presented in gdb.

Boards and targets

• Added board ID for Embedded Planet Agora platform.
• Major refactoring of Cypress PSoC6 target support. (Thanks Cypress!)
• Nordic nRF52 APPROTECT security and unlock support. This works for both builtin and CMSIS-Pack targets. (Thanks @nocko!)
• Fixed NXP LPC1768 reset and halt.
• Fixed Arm Musca-B1 software reset.
• Added test binaries for a handful of STMicro Nucleo boards.

Changes

• More debug log messages when operations like stepping are performed.

Fixes

• Fixed uninitialized variable reference in FileProgrammer that appeared when attempting to load ELF files. (#782 and others. Thanks @samkearney!)
• Fixed an issue where v8-M cores would cause the commander show cores command to raise an exception due to separate core type name lists for v6/7-M and v8-M. There is now a single core type name list.
• Improved handling of probes with multiple USB HID interfaces when using the pyusb backends.

Python API

• DebugProbe.swj_sequence() is added, plus supports_swj_sequence property indicating whether the probe can send arbitrary SWJ sequences using this API. Currently only CMSIS-DAP probes are capable of this.
• Fixed the JTAG sequence API in pyDAPAccess. (Not exposed at higher layers.)
• Renamed link attribute of DebugPort to probe.
• Refactored MemoryMap region search methods.
• Renamed FlashRegion.is_erased() to is_data_erased() which better reflects that it operates on passed-in data.
• Changed all the constants in Target to be enums.
• Removed the root context methods on Target that were unused.
• Added Target.get_halt_reason() method.
• Renamed FlashReaderContext to ElfReaderContext.
• Some new GraphNode methods.
• MemoryCache and RegisterCache were moved from pyocd.debug.cache to their own modules in a new subpackage pyocd.cache.
• Moved GDBServerPacketIOThread to its own module.
• Moved FileProgrammer and FlashEraser to their own modules under pyocd.flash.

Documentation

• Documented MemoryMap methods.
• New security features documentation. (Thanks @nocko!)
• Split documentation of user options out from configuration documentation.
• Various little fixes and improvements.

v0.23.0

New features

• Added a connect_mode option. It can be set to one of halt, pre-reset, under-reset, attach. The default is halt, retaining previous behaviour. In particular, under-reset can often be used to connect to out of control targets.
• Watchpoints in v8-M targets work now, with added support for DWT version 2.
• Several additions to the commander:
  • go and halt report target state.
  • continue and c aliases for go.
  • load command to load any file, including hex or ELF. (loadmem only loads binary.)
  • fill command for filling memory with patterns.
  • find command to search for byte patterns in memory ranges.
  • watch, lswatch, and rmwatch commands for managing watchpoints.
  • Hex dumps now include an ASCII representation column.

Boards and targets

• New Cypress PSoC6 devices.
• Add NuMaker-M252KG board and M252KG6AE target.
• HDSC HC32F46X, HC32F120, and HC32M120 targets added.

Changes

• Removed halt_on_connect option in favour of the added connect_mode option. To get the behaviour of turning off halt_on_connect (the default was on), set connect_mode to attach.
• Tildes are expanded in ELF file paths.
• Description message included in exceptions raised for No ACK, SWD protocol error, or unrecognized CMSIS-DAP transfer response values.
• Explicitly denote support for Python 3.8.

Fixes

• Fixed bugs related to converting user options when set from the command line.
• Fixed show option in commander.
• Corrected an undefined attribute error if an invalid path to an ELF file is specified.
• Addressed concurrency issues with recent memory map changes. The target memory map is now deep copied for each session.
• Fix some minor deprecation warnings reported by Python 3.8.

v0.22.0

Boards and targets

• Fixed regression with Cypress PSoC6 targets (#680) and merged in cumulative PSoC6 updates from Cypress.
• Resolved a number of issues (but not all) with NXP LPC55S69.
• Update ST NUCLEO-H743ZI.
• Correct the wrong part number for MIMXRT1064-EVK board.
• Correct part number for ST NUCLEO-WB55RG board.
• Fix location of input data for flash algorithms in STM32F412xx target.
• Address an issue with the built-in target STM32L031x6 by disabling double buffered flash programming.
• New board IDs: DISCO-H747I (stm32h747xihx), NUCLEO-H743ZI2 (stm32h743zitx), micro:bit v1.5 (nrf51), Calliope-mini, MTS_MDOT_F405RG (stm32f405rg), MTS_DRAGONFLY_F411RE (stm32f411re), MTS_DRAGONFLY_L471QG (stm32l471qg), MTS_MDOT_F411RE (stm32f411re), XDOT_L151CC (stm32l151cc), MAX32620MBED (max32620), MAX32620HSP (max32620), MAX32625NEXPAQ (max32625), MAX32630MBED (max32630), MAX32630HSP3 (max32630), EV_COG_AD3029LZ (aducm3029), EV_COG_AD4050LZ (aducm4050), NUCLEO-L073RZ (stm32l073rz), LPC4337 (lpc4337), Teensy 3.1 (mk20dx256vlh7), L-Tek FF1705 (stm32l151cc), L-Tek FF-LPC546XX (lpc54606).

Changes

• Support running pyOCD with cmsis-pack-manager not installed, in which case managed CMSIS packs are not supported. This is primarily for running on small platforms like Raspberry Pi. See installing_on_non_x86.md for more.
• Note in readme about using libusb 1.0.21 on Windows to work around a pyusb issue that only appears on that platform.
• Loading ELF files now uses the segments defined in the file rather than sections.

Fixes

• Fixed regression on quit option for terminal probe selection prompt.
• Gracefully handle cases where the "mbed.htm" file does not appear on STLink USB MSC volumes (#695).
• Fix SVD model handling of unset derived attributes (#688).
• Catching more USB related exceptions that can be caused by misbehaving devices.

v0.21.0

New features

• STLinkV3 support.
• Adding and removing of breakpoints is optimized. The breakpoint manager keep track of requested breakpoints, and only modifies the FPB/BPU immediately before a resume or step. This is useful because gdb likes to remove all breakpoints, then re-add them each time it runs the target.
• Support for configuring log output. See the new configuring logging documentation for details.
• The pyocd list command gained some arguments to filter the output.

Boards and targets

• Added some additional NXP board IDs.
• Addressed some issues with Arm Musca-A1 and Musca-B1 support.

Changes

• More helpful warning if the generic "cortex_m" target type is selected.
• Logging of exception tracebacks can be controlled with the "debug.traceback" user option. Eventually this will default to false.
• Removed "soft_bkpt_as_hard" user option. This was from long ago, before pyOCD even supported soft breakpoints, and is no longer useful.
• Normalised the use of loggers, so each Python module has its own logger with the name of the module.
• The debug probe's firmware version is logged via a debug log message if known.
• A better error is reported if a CMSIS-Pack is not a valid zip file.
• More helpful error message if an unknown target type is specified.

Fixes

• Workaround for .FLM flash algorithms that have a page size larger than the sector size. In particular, this fixes the Keil flash algorithms for STM32L072 and L073.
• Fixed user option priorities and value parsing to work as one would expect. This is documented in the configuration documentation.
• Fixed built-in STM32L475 flash algorithm.
• Fixed some issues in the FlashBuilder class related to filling gaps in pages with no data to program.
• Fixed Flash.program_phrase().
• Fixed the CortexM.available_breakpoint_count property.

Documentation

• Finished converting all Doxygen comments to Doxygen-enabled doc comments.
• Added a section about target types to the target support documentation.
• Added terminology definition documentation.

Python API

• Added some new exception classes, tied a few outstanding exception classes into the pyOCD exception hierarchy, and made sure the appropriate exceptions are being raised for errors.
• New OptionsManager class that handles user options for a session.
• Sorted out some issues in the architecture of the DebugContext class.
• A Session is now automatically opened when used as a context manager. This can be disabled by setting the auto_open parameter of the constructor to False. Conversely, ConnectHelper.session_with_chosen_probe() no longer opens the session for you (but if used in a with statement, the session will still be opened).
• Removed deprecated parameters from ConnectHelper.session_with_chosen_probe().
• Session is the sole notifier for target-related notifications.
• Added support for notifications on changes to user options. In this case, the OptionsManager is the notifier. For instance, to subscribe: my_session.options.subscribe(my_cb, "auto_unlock").
• Removed root_target attribute from Target.

Testing

• Added a basic unit test for CMSIS-Pack loading. However, it is currently disabled because it fails when run under Travis-CI.
• New unit test for the notification API.
• New unit test for the OptionsManager class.

v0.20.1

Fixes

• Fixed an exception caused by the target auto-detection for STLink probes under Windows.

v0.20.0

New features

• pyOCD now supports managed CMSIS-Packs. A new pack subcommand has been added to the pyocd tool that lets you install packs to add target support with a single command. See #610 and the new target support documentation for details.
• Target auto-detection is supported for STLinkV2-1 probes (those with a USB MSD volume containing an "mbed.htm" file), enabling the same ease of use provided by the DAPLink firmware.
• SVD support is now built-in. Most built-in targets have SVD files integrated into pyOCD, and all pack targets should support SVD. The main use right now is through the commander, where you can show peripherals and read or write peripheral registers by name.
• The gdbserver supports the range step command from gdb. This may improve step performance slightly.

Boards and targets

• Fixed a number of built-in targets where the flash algo was accidentally dropped from the flash region definition in the 0.19.0 release: lpc11xx_32, lpc11u24, lpc1768, lpc54114, lpc54608, lpc824, kl28z, stm32f429xx, stm32f439xx.
• Adjusted Musca targets' memory map to work around chip errata.
• Fixed page size and enabled double buffering for some built-in STM32 targets: stm32f412xx, stm32f429xx, stm32f439xx, stm32l031xx.

Changes

• Logging more information about the DP and AP types and versions.
• More changes to reduce the amount of libusb related log messages. Many debug messages were removed, and warnings about possible permissions issues are only logged once per device per process.
• Added debug.log_flm_info user option to log debug messages with details of .FLM flash algorithms.
• Commander show map command prints both sector and page sizes.
• A universal wheel of pyOCD is now released to PyPI in addition to the source distribution.

Fixes

• Flash programming will not attempt to read data from flash regions that are marked as non-readable.
• Fixed the get_probe_with_id() APIs on debug probes.
• Correctly decoding the USB serial number for certain versions of STLinkV2 where the serial number is incorrectly encoded.
• Catching additional errors that could be thrown by USB devices when checking to see if they provide a CMSIS-DAPv2 interface.
• Commander savemem command inits the flash algo when accessing flash regions with is_powered_on_boot flash set to false.
• High level flash erase operations, e.g. via pyocd erase, correctly deal with sector and page sizes being different.
• Invalid CMSIS-Pack paths are handled gracefully with a warning log message, but pyOCD continues executing (unless the selected target type is in the missing pack, in which case you'll get an unknown target type error).
• Removed websocket-client and future packages from requirements.

Python API

• The most recently created Session instance is accessible via Session.get_current().

Testing

• Fixed basic_test.py for flash regions with small number of sectors.
• flash_loader_test.py fixes.

v0.19.0

New features

• Support for different flash erase sector and program page sizes (#452).
• Initial v8-M support, with known issues.
• New commander commands to run the gdbserver from within commander, to view and modify user options, to change the MEM-AP used for memory transfers, and to view and modify the current HPROT/HNONSEC for the selected AP.

Boards and targets

Note: there are still issues with most of the new v8-M targets.

• NXP LPC55S69
• Arm Musca-A1
• Arm Musca-B1

Changes

• pyOCD checks that at least one CPU was found and if not, reports a more understandable error.
• The core number is included in the log message indicating a core was discovered.
• pyocd was added to the commander Python expression evaluation namespace, so that all of pyOCD's Python API can be accessed.
• Major cleanup of log messages related to libusb and debug probes.
• The warning about no libusb is only logged once per process.
• pyOCD clears all sticky DP error flags when a protocol error occurs.
• If pyOCD sees a timeout error on transfers, it will issue a DP abort to stop the erroneous transaction.
• Flash programming raises exceptions when the flash algorithm returns errors.
• Added smart_flash and keep_unwritten user options to better control the flash programming logic.
• Builtin targets that used a custom Flash subclass to handle different erase/program sizes were updated to use the new support for that feature.
• Transfer errors that occur while reading ROM table entries are trapped, and the associated AP is ignored.
• The commander uses a selectable MEM-AP for all memory transfers.
• Configuring the TPIU for SWO is delayed until the TPIU.set_swo_clock() method is called. This is required due to a change in the v8-M TPIU that requires the trace clock to be active before accessing certain registers.

Fixes

• The NXP LPC-LinkII debug probe is recognized properly.
• Worked around apparent libusb issue in Windows where STLink probes would intermittently not be visible (#575).
• Corrected handling of error responses from STLink probes (#581). This also fixes problems with the latest STLink firmware version (V2J33M25).
• Fixed a problem introduced recently where probes running the old "mbed CMSIS-DAP" firmware was not recognized (#588).
• Fixed CMSIS-Pack targets not working with pyocd-gdbserver (#570).
• Fixed --no-init option for commander.
• Fixed the default value for the gdbserver's vector_catch option. If the option was not set, an exception was raised.
• Corrected GDBServer.stop() so it no longer uninits the board.
• Commander disasm command works while the target is running.
• The --help-options argument no longer fails for user options that have multiple allowed types, such as pack.
• Fixed LOG_DAP functionality in pyocd.coresight.ap.
• Updated pyyaml requirement to >= 5.1 (#582). The entire 4.1 release series that pyOCD was pinned to turned out to be buggy (though it didn't seem to affect pyOCD's usage).
• Fixed FileProgrammer trying to raise the undefined ArgumentError exception for errors. It now raises the standard ValueError.
• Fixed a number of issues with how FileProgrammer checked for file errors, including file not found (#590).
• Fixed default names for memory regions.
• Fixed a problem where FileProgrammer used programmatically would not default to sector erase.
• Access permissions are set on memory regions created for Pack targets.
• Fixed the selected_core property setter on CoreSightTarget.

Python API

• Added optional init_board parameter to Session.open() to control whether the board (and therefore target) are initialized. Used to implement the commander --no-init option.
• Removed STLinkException from the STLink probe code; now using standard pyOCD exceptions.
• Added page and phrase sizes and program and erase weight attributes to flash memory regions.
• Added smart_flash and keep_unwritten parameters to FileProgrammer and FlashLoader.
• AccessPort methods are automatically serialized via a mutex.
• Changing the HPROT and HNONSEC values used for MEM-AP transfers is supported.
• MEM_AP attempts to detect the supported HPROT and HNONSEC bits in CSW.
• AHB_AP detects whether the MSTRTYP bit is supported in CSW. (Only the M3/M4 AHB-AP supports this bit.)
• Added context manager methods to MEM_AP to temporarily change HPROT or HNONSEC. The AP is locked while the context manager is live.
• Moved the CoreSight components list to a separate source file.
• New CortexM_v8M subclass for v8-M cores.

Documentation

• Updated contributing guidelines and removed mention of the contributor license agreement that no longer needs to be signed.
• Added readme to udev folder with detailed information.
• The udev section in the main readme was simplified.
• Link to GNU Arm Embedded toolchain in a couple places.
• Updated the architecture diagram.
• Note about gdb_test.py requiring 32-bit Python 2.7 on Windows.

Testing

• Testing both 8- and 32-bit transfers in speed_test.py.
• speed_test.py limits the size it will read or write during testing to 1 MB.
• Rewrote the simple flash erase/program test in basic_test.py to support nonequal erase/program sizes.

Known issues

• The LPC-LinkII probe may not work correctly under Windows using pywinusb.
• All new v8-M targets have certain issues with flash programming or other operations.

v0.18.0

Boards and targets

• Added MAX32620 target and MAX32620FTHR board.
• Added MAX32630 target and MAX32630FTHR board.

Changes

• Sector erase is now the default mode for all flash programming since it is a safer default, especially with so many IoT projects now storing data on internal flash.
• Made the warning for an unknown board ID more helpful and less scary. It now says, ""Board ID XXXX is not recognized; you will be able to use pyOCD but not program flash."
• The SWV reader supports 16- and 32-bit ITM channel 0 events that send multiple characters.
• pyOCD only attempts to read the board ID from the probe's USB serial number if it knows the probe is running DAPLink, by comparing the USB VID and PID. This prevents unknown board ID warnings for other CMSIS-DAP compatible probes.
• pyOCD is now aware that a board ID of "0000" means the DAPLink is generic, so it won't try to look up the matching board.
• Removed websocket support.

Fixes

• Fixed a failure to start SWO transfers from the probe by sending the command to stop SWO before starting it. The failure could happen if the probe was left with SWO running when pyOCD exited, and then pyOCD was started again.
• Updated Argon RTOS support to match the latest version.
• Fixed an issue that prevented SWO from working with CMSIS-DAPv1.
• The SWV reader checks that the probe supports SWO before attempting to enable it.
• The trace_start() delegate and user script method will be called by the SWV reader if the target is reset.
• Fixed memory cache bugs that caused duplication of cache contents. This most often appeared as extra data being sent by the gdbserver in response to a gdb read memory command, though it was not visible to users.
• Fixed the FlashReaderContext class' usage of a removed intervaltree API. This problem would be triggered if you passed pyocd gdbserver an ELF file.
• Any enabled watchpoints are removed on disconnect.
• The list of valid APs is saved only after the full AP scan completes, to prevent a partial list being saved.
• Rewrote gdbserver memory read command handler to use a much simpler and more efficient hex encoding method.
• Catching NotImplementedError exceptions raised on Windows by the CMSIS-DAPv2 interface code.

Python API

• Memory map API now allows empty memory ranges, but not empty memory regions.
• Removed has_fpu attribute from the Target class. This attribute is only supported on CortexM now.
• is_float_register() returns true for both single and double precision float registers.
• Added a setter for the CoreSightTarget.selected_core property. The select_core() method is now deprecated.
• Changed the name of the format parameter of FileProgrammer.program() to file_format so it doesn't shadow the builtin function.
• Refactored GDBSocket into pyocd.utility.socket.ListenerSocket.
• Renamed pyocd.utility.py3_helpers module to pyocd.utility.compatibility.
• Removed unused Flash_cortex_m class.
• A few remaining timeouts were changed to use the Timeout class.
• Got rid of a pointless mutex in GDBServer.
• Removed reading of flash related user options from GDBServer since these are now handled elsewhere.

Documentation

• Renamed files in the docs/ folder to all lower case.
• Started process of converting doxygen comments to doxygen-enabled doc comments.
• Added some missing user options to docs.
• Fixed some errors and typos in user_scripts.md and delegate method doc comments.
• Converted license headers to use single-line comments, mostly so they don't show up in Doxygen output.

Testing

• Set up tox for running functional tests under Python 2.7 and 3.7. This will soon be used in our CI system to test on both Python versions.
• Moved unit tests from the pyocd Python package to the test/ folder in the repo root.
• Added tests to cover memory cache bugs mentioned above.
• flash_loader_test.py tests hex file programming.
• speed_test.py tests cached memory accesses and records the ROM read speed.
• cortex_test.py reports test metrics.
• Removed use of test_boards.yaml file in favour of the now-standard pyocd.yaml config file.
• Fixed blank_test.py.
• New debug_context_test.py.

v0.17.0

New features

• pyOCD now supports user scripts, written in Python, that can extend, modify, and override default behaviour at multiple key points in the connection lifetime. This feature is documented in docs/user_scripts.md.
• Providing the foundation for user scripts, the Python API supports attaching a delegate object to the session and other objects such as the target and cores. The same hook functions are used for delegates and user scripts.
• SWO and SWV are now supported for both CMSIS-DAP and STLink. See the description of #543 for details.
• CMSIS-DAPv2 support. v2 uses bulk endpoints instead of HID for improved latency. Tested with the Keil ULINKplus.
• Sessions have the concept of a project directory. This directory defaults to the working directory where pyOCD was started. It can be changed with the -j/--dir command line argument or project_dir user option. Any files used by pyOCD, such as config files, user scripts, or .FLM flash algos, will be searched for in the project directory if they are specified as a relative path.

Boards and targets

• Added STM32F429xI.

Changes

• The objects in the pyOCD object graph are now linked to form a generic object graph, in addition to the explicit references that already exist. This is intended to make it easier to find objects as the graph gets much more complex with support for SWO and other CoreSight components.
• The path to an .FLM style flash algorithm can be set on a FlashRegion via the flm property. pyOCD will then load the flash algorithm for you. Very useful for user scripts.
• Renamed the flash_algo property of FlashRegion to just algo and made it and flash_class settable. This is all to make it easy to set or modify the flash algo in user scripts and delegates.
• Renamed SESSION_OPTIONS.md documentation file to CONFIGURATION.md since it covers all configuration topics and not just a list of options.
• Added ULINKplus to example udev rules.

Fixes

• Fixed a typo in the code to build a flash algo from an .FLM file, which caused STM32 CMSIS-Pack targets to not be able to program flash.
• Corrected a performance issue for Python 3 on Windows and Linux. The pywinusb and pyusb backends for CMSIS-DAP were not yielding to other threads while waiting for data. (Thanks Cypress!)
• Improved detection of post-reset state for RTX5.
• Reduced warning messages related to USB device permissions issues on Linux through improved filtering for CMSIS-DAP devices.
• A few strings were not being properly formatted with '%'. (Thanks @mbolivar!)
• Added catch for unknown directory when parsing ELF symbols.