documentation: adds application qemu and debug reference

This commit adds a quick reference on how to debug an
application with qemu and gdb.

Change-Id: Ib75465b110a65285dc55888fbfb95e8271ad83f9
Signed-off-by: Juan Manuel Cruz <juan.m.cruz.alcaraz@linux.intel.com>

doc/development/kbuild_project.rst

@@ -98,3 +98,107 @@ The following predefined variables configure the development project:
   The output directory stores all the Kconfig generated files.
   The default output directory is set to the
   :file:`$(PROJECT_BASE)/output` directory.
+
+Project Debugging
+=================
+
+This section is a quick hands-on reference to start debugging |project|
+with QEMU. Most of the content in this section is already covered on
+`QEMU`_ and `GNU_Debugger`_ reference manuals.
+
+.. _QEMU: http://wiki.qemu.org/Main_Page
+
+.. _GNU_Debugger: http://www.gnu.org/software/gdb
+
+In this quick reference you find shortcuts, specific environmental
+variables and parameters that can help you to quickly setup your
+debugging environment.
+
+The simplest way to debug an application running in QEMU is using the GNU
+Debugger and setting a local GDB server in your development system
+through QEMU.
+
+You will need an ELF binary image for debugging purposes.
+This image will be generated by the build system in the output directory.
+By default, the kernel binaries names are :file:`microkernel.elf` and
+:file:`nanokernel.elf`. The names can be changed using Kconfig.
+
+.. note::
+
+   We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)`
+   server instance in this reference manual. This port number can be changed
+   for a port that best suits your development system.
+
+|codename| uses QEMU as the supported emulation system. QEMU must be invoked
+with the -s and -S parameters.
+
+* -S  Do not start CPU at startup (you must type 'c' in the monitor).
+* -s  Shorthand for -gdb tcp::1234, i.e. open a GDB server on TCP port 1234.
+
+The build system can build the elf binary and call the QEMU process with
+the :makevar:`qemu` target. The QEMU debug parameters can be set using the
+environment variable :makevar `QEMU_EXTRA_FLAGS`. To set the -s and -S
+parameters type:
+
+.. code-block:: bash
+
+    export QEMU_EXTRA_FLAGS="-s -S"
+
+The build and emulation processes are called with the Makefile qemu target:
+
+.. code-block:: bash
+
+   make qemu
+
+The build system will start a QEMU instance with the CPU halted at startup
+and with a GDB server instance listening at the TCP port 1234.
+
+The :file:`.gdbinit` will help initialize your GDB instance on every run.
+In this example, the initialization file points to the GDB server instace.
+It configures a connection to a remote target at the local host on the TCP
+port 1234. The initialization should set the kernel's root directory as a
+reference. The :file:`.gdbinit` file contains the following lines:
+
+.. code-block:: bash
+
+   target remote localhost:1234
+   dir ZEPHYR_BASE
+
+.. note::
+
+   Substitute ZEPHYR_BASE for the current kernel's root directory.
+
+Execute your debug application from the same directory that you chose for
+the :file:`gdbinit` file. The command may include the --tui option to enable
+the use if a teminal user interface. The following commands connects to the
+GDB server using :file:`gdb`. --tui).The command loads the symbol table from
+the elf binary file. In this example, the elf binary file name corresponds
+to :file:`microkernel.elf` file:
+
+.. code-block:: bash
+
+   gdb --tui microkernel.elf
+
+.. note::
+
+   The --tui option might not be supported by the GDB
+   version installed in your development system.
+
+Finally, this command connects to the GDB server using the Data
+Displayer Debugger (:file:`ddd`). The command loads the symbol table from the
+elf binary file, in this instance, the :file:`nanokernel.elf` file.
+
+.. note::
+
+   The Data Displayer Debugger may not be installed in your development
+   system by default. Follow your system instructions to install it.
+
+.. code-block:: bash
+
+   ddd --gdb --debugger "gdb nanokernel.elf"
+
+.. note::
+
+   Both commands use the :command:`gdb` to execute the GNU Debugger.
+   The command name might change depending on the toolchain you are using
+   and your cross-development tools.