Merge pull request #61 from apache/aditihilbert-patch-1
Update troubleshoot_faq.rst with multiple debug session Q&A
diff --git a/docs/get_started/debug.rst b/docs/get_started/debug.rst
new file mode 100644
index 0000000..87fbb7a
--- /dev/null
+++ b/docs/get_started/debug.rst
@@ -0,0 +1,64 @@
+Debugging Mynewt
+=============================
+
+If you run into issues with Mynewt applications, you may need to use the debugger. This page will show
+you how to set up and use the debugger in Mynewt.
+
+.. contents::
+ :local:
+ :depth: 2
+
+Prerequisites
+-----------------------------
+
+- You have installed the Newt tool and toolchains on your machine. Visit the :doc:`Native Installation <native_install/index>` page to get started.
+- You have run through one of the tutorials, created a project, or have an existing one.
+- Familiarity with GDB; for more information refer to the `GDB documentation <https://sourceware.org/gdb/current/onlinedocs/gdb/>`__.
+
+Starting the Debugger
+-----------------------------
+
+Mynewt uses GDB to debug applications. To open a debugger session for Mynewt, you can run
+either of the following newt commands:
+
+- ``newt debug <target_name>``
+- ``newt run <target_name> <version_number>``
+
+The ``newt debug`` command will start the debugger for the specified target. That target
+should be running on the device you are debugging on. For more information on the command, take a look at
+the :doc:`command structure in the Newt Tool Guide <../../../../../newt/command_list/newt_debug>`.
+
+The ``newt run`` command also starts the debugger, but will also build the target, create
+an image with the specified version number, and load it onto the board. More details on its usage and syntax are
+on the :doc:`Newt Tool command guide <../../../../newt/command_list/newt_run>`.
+
+
+Starting the debugger will bring up the GDB session in the console:
+
+.. code:: console
+
+ ~/test/1.5 $ newt debug pca40blinky
+ [/Users/dlee/test/1.5/repos/apache-mynewt-core/hw/bsp/nordic_pca10040/nordic_pca10040_debug.sh /Users/dlee/test/1.5/repos/apache-mynewt-core/hw/bsp/nordic_pca10040 bin/targets/pca40blinky/app/apps/blinky/blinky]
+
+ Debugging bin/targets/pca40blinky/app/apps/blinky/blinky.elf
+ GNU gdb (GNU Tools for Arm Embedded Processors 7-2018-q2-update) 8.1.0.20180315-git
+ Copyright (C) 2018 Free Software Foundation, Inc.
+ License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+ This is free software: you are free to change and redistribute it.
+ There is NO WARRANTY, to the extent permitted by law. Type "show copying"
+ and "show warranty" for details.
+ This GDB was configured as "--host=x86_64-apple-darwin10 --target=arm-none-eabi".
+ Type "show configuration" for configuration details.
+ For bug reporting instructions, please see:
+ <http://www.gnu.org/software/gdb/bugs/>.
+ Find the GDB manual and other documentation resources online at:
+ <http://www.gnu.org/software/gdb/documentation/>.
+ For help, type "help".
+ Type "apropos word" to search for commands related to "word"...
+ Reading symbols from bin/targets/pca40blinky/app/apps/blinky/blinky.elf...done.
+ os_tick_idle (ticks=128)
+ at repos/apache-mynewt-core/hw/mcu/nordic/nrf52xxx/src/hal_os_tick.c:164
+ 164 if (ticks > 0) {
+ (gdb)
+
+
diff --git a/docs/get_started/index.rst b/docs/get_started/index.rst
index 4eeffb4..f90766d 100644
--- a/docs/get_started/index.rst
+++ b/docs/get_started/index.rst
@@ -8,6 +8,7 @@
Docker Container <docker>
Create Your First Project <project_create>
Serial Port Setup <serial_access>
+ Debugging Mynewt <debug>
If you are curious about Mynewt and want to get a quick feel for the
project, you've come to the right place. We have two options for you:
