===========================================================================
                mdebug - A debugger for Cortex-M MCUs
===========================================================================

This is a debugger for Cortex-M MCUs using SWD (serial wire debug) and
(optionally) SWO.  It provides basic standalone functionality including
memory inspection and modification, processor halt, register inspection,
single stepping, breakpoints, etc.  It also acts as a GDB agent, allowing
GDB to control the target device.

Previously it used a custom debug probe board (m3debug).  In its current
iteration firmware is provided for the readily available (and much more
powerful) LPC Link 2 probe board, which is available from Digikey for
under $20:
http://www.digikey.com/product-detail/en/OM13054,598/568-10930-ND/
http://www.embeddedartists.com/products/lpcxpresso/lpclink2.php

It provides flashing functionality via "flash agents" which are little
programs downloaded to the target board RAM and then controlled by the
debugger.  Currently agents are included for the lpc13xx, lpc15xx,
stm32f4xx series MCUs and the lpclink2 board itself (lpc43xx + spifi).

Recently it's seem the most testing against stm32f4xx and lpc43xx MCUs.
It has previously been used successfully with lpc13xx, lpc15xx, and
stm32f2xx MCUs.

Firmware for the LPC Link 2 and installation instructions are in the
firmware directory.  Firmware source code is part of the lk embedded
kernel project (look in app/mdebug):
https://github.com/travisg/lk
https://github.com/travisg/lk/tree/master/app/mdebug

Everything is either Apache 2 or BSD licensed, to allow for easy,
no-strings-attached, inclusion in your own projects.  Share and enjoy!

Features
--------

* simple standalone interactive debugger
* GDB stub/remote integration (default port localhost:5555)
* simple and efficient remoted SWD transaction protocol
* pretty fast: 450KB/s download to target w/ 8MHz SWD clock
* simple flash agents: easy to add support for a new MCU or memory device
* integration with LK for multi-threaded GDB debugging
* supports console-over-SWO, and console-commands-over-SWD (with LK)
* host software runs on Linux or OSX (Windows support not far off)
* only external dependency is libusb 1.0


Included Third Party Software
-----------------------------

linenoise.[ch] 
  excellent tiny commandline editor (BSD license)
  https://github.com/antirez/linenoise


Useful Documents
----------------

ARM DDI0337E Cortex M3 r1p1 Technical Reference Manual
  Has useful details on SW-DP and debug peripherals that was removed
  in later versions of the TRM as "redundant" with other documents.


Historical Notes
----------------

This work is an extension of the older m3dev project, but only brings
the debugger tools foward.  The embedded firmware stuff lives on in
m3dev and the next-gen firmware is part of lk.

https://github.com/swetland/m3dev