Test and debug section

Author: Irit Arkin

docs.json

@@ -78,6 +78,31 @@
             {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/compile/exporter_instruct.md"}
         ]
     },
+    {
+        "title": "Test and debug",
+        "description": "Test and debug applications using mbed OS and third party tools",
+        "slug": "mbed-os-test",
+        "type": "markdown",
+        "sources": [
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/debugging_mbed_os_apps.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/DAP.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/local_debugging_toolchain.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/debug_builds_cli.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/keil_uvision.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/eclipse_pyocd.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/vs_code.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/other_ides.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/build_script.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/testing.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/greentea.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/utest.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/printf.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/compile_time_errors.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/lights_of_dead.md"},
+            {"type": "markdown", "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/test_debug/microbit.md"}
+        ]
+    },
     {
         "title": "mbed OS API refrences",
         "description": "References to the mbed OS APIs",

docs/advanced/build_script.md

@@ -1,37 +1,37 @@
-# DAPLink
+## DAPLink
 
 DAPlink is an open source project that implements the embedded firmware required for a Cortex debug probe. The project is hosted on GitHub and is published under an Apache 2.0 license, making it attractive for commercial developments.
 
 The software project is complemented by a series of reference designs for creating the DAPLink debug probe hardware, which is available [here](https://docs.mbed.com/docs/mbed-hardware-development-kit/en/latest/).
 
-## DAPLink features
+### DAPLink features
 
 A DAPLink debug probe connects to your host computer through USB and connects to your target system (the one to be programmed and debugged) through a standard [Cortex debug connector](http://infocenter.arm.com/help/topic/com.arm.doc.faqs/attached/13634/cortex_debug_connectors.pdf). It provides three main features - all over a single USB connection.
 
-### HID interface 
+#### HID interface
 
-The driver-less HID interface provides a channel over which the CMSIS-DAP debug protocol runs. This enables all the leading industry standard toolchains to program and debug the target system. 
+The driver-less HID interface provides a channel over which the CMSIS-DAP debug protocol runs. This enables all the leading industry standard toolchains to program and debug the target system.
 
 Supported tools include:
 
   * Keil MDK.
   * IAR Workbench.
   * pyOCD.
 
-### USB disk drag and drop programming 
+#### USB disk drag and drop programming
 
 DAPLink debug probes appear on the host computer as a USB disk. Program files in binary (``.bin``) and hex (``.hex``) formats can be copied onto the USB disk, which then programs them into the memory of the target system.
 
 <span class="notes">**Note:** The DAPLink probe needs to contain the programming algorithms specific to the target system. Therefore, the version of the DAPLink firmware you use must match the target system.</span>
 
-## USB serial port 
+### USB serial port
 
 The DAPLink debug probe also provides a USB serial port, which can be bridged through to a TTL UART on the target system.
 The USB serial port will appear on a Windows machine as a COM port, or on a Linux machine as a /dev/tty interface.
 
 For more information on configuring your host computer to use this feature, please [see here](../getting_started/serial_communication.md).
 
-## Further reading
+### Further reading
 
 * [The DAPLink GitHub repo](https://github.com/ARMmbed/DAPLink/blob/master/README.md).
 * [Debug probes built with DAPLink](https://developer.mbed.org/platforms/SWDAP-LPC11U35).

docs/advanced/DAP.md renamed to docs/test_debug/DAP.md

@@ -0,0 +1,3 @@
+## The build script environment
+
+[needs to be rewritten]

docs/test_debug/build_script.md

@@ -1,4 +1,4 @@
-# Compile time errors
+## Compile time errors
 
 Compile time errors and warnings that incorrect syntax, or misuse of variables or functions, causes. An error prevents the compile process from completing (and therefore no binary file will be created). A warning does not prevent the binary from being created, but you should still review the warning because it may mean that your code is not going to do what you had intended.
 
@@ -9,4 +9,4 @@ Common errors are:
 * Missing quotes or brackets (`""`, `()`, `[]` or `{}`). These are used in pairs to contain various types of statement. The compiler reports an error if you have not used them in correct pairings.
 * Always tackle the first reported error because later errors may be as a result of the first one and will disappear you correct the first one.
 
-If you see a compile time error or warning that you do not understand, you can usually find explanations of the error message on Google, or post to the [mbed forums](https://developer.mbed.org/questions/).
+If you see a compile time error or warning that you do not understand, you can usually find explanations of the error message on Google, or post to the [mbed forums](https://developer.mbed.org/questions/).

docs/test_debug/compile_time.md renamed to docs/test_debug/compile_time_errors.md

@@ -1,10 +1,10 @@
-# Producing debug builds with mbed CLI
+## Producing debug builds with mbed CLI
 
 After you've set up your [local debug toolchain](toolchain.md), you'll need firmware that includes program symbols (an `.elf` file). Because the Online Compiler only produces binaries that omit the program symbols, you need to compile locally using [mbed CLI](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/dev_tools/cli/).
 
 <span class="notes">**Note:** Make sure to do a clean build when switching to and from debug and release by removing the `BUILD` folder.</span>
 
-## Compile commands
+### Compile commands
 
 **mbed OS 5.2 and later**
 
@@ -24,7 +24,7 @@ $ mbed compile -o debug-info
 $ mbed compile --profile .temp/tools/profiles/debug.json
 ```
 
-## Exporting with debug symbols
+### Exporting with debug symbols
 
 You can also enable debug symbols when [exporting your project](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/dev_tools/cli/#exporting-to-desktop-ides) by using:
 

docs/test_debug/debug_builds.md renamed to docs/test_debug/debug_builds_cli.md

@@ -1,16 +1,16 @@
-# Debugging mbed OS applications
+## Debugging mbed OS applications
 
 At the heart of mbed is the [Online Compiler](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/dev_tools/online_comp/). While that is incredibly convenient for getting a project started or while prototyping, chances are that at some point you'll miss a debugger, or you'll want to develop while not having an active internet connection. Through debugging, you can do things such as set breakpoints, set watchpoints, view registers, view disassembly, browse memory and examine the callstack. These docs will help you debug your applications.
 
 The simplest way to debug your code is to augment your code with log statements, which can be observed from your computer. To set this up, read [Debugging with printf() calls](printf.md).
 
-## Compile time and runtime errors
+### Compile time and runtime errors
 
 If your program will not compile, first read [Debugging compile time errors](compile_time.md).
 
 If your development board blinks very fast, or shows 'siren lights', see [Lights of dead](lights_of_dead.md).
 
-## Debugging from an IDE
+### Debugging from an IDE
 
 Keil uVision natively supports debugging mbed OS applications. To set up uVision, read [Debugging with Keil uVision](Keil.md).
 
@@ -21,7 +21,7 @@ mbed also supports debugging using any IDE that supports GDB. To set up the debu
 1. Debugging with [Visual Studio Code](vscode.md).
 1. Debugging with [other IDEs that support GDB](other_ides.md).
 
-## Links to other sources
+### Links to other sources
 
 * [Using CMSIS-DAP to debug a device after it crashes](https://developer.mbed.org/blog/entry/Post-mortem-debugging-with-ARM-mbed/).
 * [Debugging the micro:bit with pyOCD and GDB](debugging_microbit.md).

docs/test_debug/debugging.md renamed to docs/test_debug/debugging_mbed_os_apps.md

@@ -1,8 +1,8 @@
-# Debugging mbed OS 5 applications with Eclipse
+## Debugging mbed OS 5 applications with Eclipse
 
 This document explains how to build and debug mbed OS applications using Eclipse. Before starting, please [configure your local debug toolchain](toolchain.md).
 
-## Installing Eclipse
+### Installing Eclipse
 
 You need to install Eclipse CDT with the GNU ARM Eclipse plugins to begin:
 
@@ -20,11 +20,11 @@ You need to install Eclipse CDT with the GNU ARM Eclipse plugins to begin:
     1. Click **Next** repeatedly, and accept the license agreements.
     1. Click **Finish**. If prompted to restart Eclipse, click **Yes**.
 
-## Exporting a project
+### Exporting a project
 
 To export your project to Eclipse, you can use either the mbed Online Compiler or mbed CLI.
 
-### Online compiler
+#### Online compiler
 
 1. Right click on your project.
 1. Select *Export Program...*.
@@ -35,7 +35,7 @@ To export your project to Eclipse, you can use either the mbed Online Compiler o
 
 ![Exporting to Eclipse](Images/eclipse1.png)
 
-### mbed CLI
+#### mbed CLI
 
 In your project folder, run:
 
@@ -46,7 +46,7 @@ In your project folder, run:
 $ mbed export -i eclipse_gcc_arm -m K64F --profile mbed-os/tools/profiles/debug.json
 ```
 
-## Importing the project in Eclipse
+### Importing the project in Eclipse
 
 1. Open Eclipse.
 1. On the *Welcome* screen, select *Import a project with a working Makefile*.
@@ -58,7 +58,7 @@ $ mbed export -i eclipse_gcc_arm -m K64F --profile mbed-os/tools/profiles/debug.
 1. Dismiss the Welcome screen.
 1. Select *Project > Build Project* to build the project.
 
-<span class="notes">**Note:** If build fails with error 
+<span class="notes">**Note:** If build fails with error
 1. `make[1]: arm-none-eabi-g++: No such file or directory`, you need to configure Eclipse's PATH (not your OS PATH).
 1. `Program "make" not found in PATH`, install [GNU-Make utility](http://gnuwin32.sourceforge.net/packages/make.htm), and configure Eclipse's PATH.
 
@@ -75,7 +75,7 @@ Steps to update Eclipse's PATH
 
 Once the project builds, you can configure the debugger. The configuration depends on the debug server you're using: pyOCD or OpenOCD.
 
-### pyOCD
+#### pyOCD
 
 1. Select *Run > Debug Configurations...*.
 1. If no configuration exists under *GDB pyOCD Debugging*, click on *New launch configuration*.
@@ -92,7 +92,7 @@ Once the project builds, you can configure the debugger. The configuration depen
 1. Click *Apply*.
 1. Click *Debug* to start debugging.
 
-### OpenOCD
+#### OpenOCD
 
 1. Select *Run > Debug Configurations...*.
 1. If a configuration already exists under *GDB pyOCD Debugging*, please remove it.
@@ -113,7 +113,7 @@ Once the project builds, you can configure the debugger. The configuration depen
 
 ![Debugging an mbed OS 5 application in Eclipse](Images/eclipse9.png)
 
-## Building with mbed CLI
+### Building with mbed CLI
 
 We build using Make, but you can also use mbed CLI for building from Eclipse:
 

docs/test_debug/debugging_eclipse_pyocd.md renamed to docs/test_debug/eclipse_pyocd.md

@@ -1,25 +1,23 @@
-[![Circle CI](https://circleci.com/gh/ARMmbed/greentea.svg?style=svg)](https://circleci.com/gh/ARMmbed/greentea)
-[![Coverage Status](https://coveralls.io/repos/github/ARMmbed/greentea/badge.svg?branch=master)](https://coveralls.io/github/ARMmbed/greentea?branch=master)
-[![PyPI version](https://badge.fury.io/py/mbed-greentea.svg)](https://badge.fury.io/py/mbed-greentea)
 
-# Greentea - test automation for mbed
+## Greentea - test automation for mbed
+
 _**G**eneric **re**gression **en**vironment for **te**st **a**utomation_
 
-## Introduction
+### Introduction
 
 Greentea is the automated testing tool for mbed OS development. It automates the process of flashing mbed boards, driving the test and accumulating test results into test reports. Developers use it for local development as well as for automation in a Continuous Integration environment.
 
 This document should help you start using Greentea. Please see the [htrun documentation](https://github.com/ARMmbed/htrun), the tool Greentea uses to drive tests, for the technical details of the interactions between the platform and the host machine.
 
-### Prerequistes
+#### Prerequisites
 
 Greentea requires [Python version 2.7](https://www.python.org/downloads/). It supports the following OSes:
 
 - Windows
 - Linux (Ubuntu preferred)
 - OS X (experimental)
 
-### Installing
+#### Installing
 
 Tools that depend on Greentea usually install it. Determine if Greentea is already installed by running:
 ```
@@ -33,15 +31,15 @@ You can also install it manually via pip.
 pip install mbed-greentea
 ```
 
-## Test specification JSON format
+### Test specification JSON format
 
 The Greentea test specification format decouples the tool from your build system. It provides important data, such as test names, paths to test binaries and the platform on which the binaries should run.
 
 Greentea automatically looks for files called `test_spec.json` in your working directory. You can also use the `--test-spec` argument to direct Greentea to a specific test specification file.
 
 When you use the `-t` / `--target` argument with the `--test-spec` argument, you can select which "build" should be used. In the example below, you could provide the arguments `--test-spec test_spec.json -t K64F-ARM` to only run that build's tests.
 
-### Example of test specification file
+#### Example of test specification file
 
 In the below example, there are two defined builds:
 * Build `K64F-ARM` for NXP `K64F` platform compiled with `ARMCC` compiler.
@@ -96,12 +94,12 @@ In the below example, there are two defined builds:
 
 The examples below use the above test specification file.
 
-## Command-line usage
+### Command-line usage
 This section highlights a few of the capabilities of the Greentea command-line interface. For a full list of the available options, please run `mbedgt --help`.
 
 Assume for the examples below that the above `test_spec.json` file is in the current directory.
 
-### Listing all tests
+#### Listing all tests
 You can use the `-l` argument to list all available tests:
 
 ```
@@ -117,7 +115,7 @@ mbedgt: available tests for built 'K64F-ARM', location 'BUILD/tests/K64F/ARM'
         test 'tests-mbedmicro-rtos-mbed-mail'
 ```
 
-### Executing all tests
+#### Executing all tests
 The default action of Greentea is to execute all tests that were found.
 ```
 $ mbedgt
@@ -531,7 +529,7 @@ mbedgt: completed in 53.59 sec
 
 ```
 
-### Limiting tests
+#### Limiting tests
 You can select test cases by name using the `-n` argument. This command executes all tests named `tests-mbedmicro-rtos-mbed-mail` from all builds in the test specification:
 ```
 $ mbedgt -n tests-mbedmicro-rtos-mbed-mail
@@ -553,7 +551,7 @@ You can use a comma (`,`) to separate test names (argument `-n`) and build names
 $ mbedgt -n tests-mbedmicro-rtos-mbed-mail,tests-mbed_drivers-c_strings -t K64F-ARM,K64F-GCC_ARM
 ```
 
-### Selecting platforms
+#### Selecting platforms
 You can limit which boards Greentea uses for testing by using the `--use-tids` argument.
 
 ```
@@ -576,39 +574,41 @@ $ mbedls
 ```
 In this case, you won't test one target, the LPC1768.
 
-### Creating reports
+#### Creating reports
 Greentea supports a number of report formats.
 
-#### HTML
+##### HTML
 This creates an interactive HTML page with test results and logs.
 ```
 mbedgt --report-html html_report.html
 ```
 
-#### JUnit
+##### JUnit
 This creates an XML JUnit report, which you can use with popular Continuous Integration software, such as [Jenkins](https://jenkins.io/index.html).
 ```
 mbedgt --report-junit junit_report.xml
 ```
 
-#### JSON
+##### JSON
 This creates a general JSON report.
 ```
 mbedgt --report-json json_report.json
 ```
 
-#### Plain text
+##### Plain text
 This creates a human-friendly text summary of the test run.
 ```
 mbedgt --report-text text_report.text
 ```
 
-## Host test detection
+### Host test detection
 When developing with mbed OS, Greentea detects host tests automatically if you place them in the correct location. All tests in mbed OS are placed under a `TESTS` directory. You may place custom host test scripts in a folder named `host_tests` in this folder. For more information about the mbed OS test directory structure, please see the [mbed CLI documentation](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/dev_tools/cli/#test-directory-structure).
 
-## Common issues
+### Common issues
+
+#### `IOERR_SERIAL` errors
 
-### `IOERR_SERIAL` errors
 Possible causes:
+
 - Another program is using the serial port. Be sure all terminals and other instances of Greentea are closed before trying again.
 - The mbed interface firmware is out of date. Please see the platform's page on [developer.mbed.org](https://developer.mbed.org/) for details about how to update it.