Added code comments

Author: Mohammad Azim Khan

platform/retarget.cpp

@@ -73,11 +73,18 @@ extern const char __stderr_name[] = "/stderr";
 #endif
 
 #if defined MBED_CFG_DEBUG_OPTIONS_COVERAGE
+/* Coverage sync flag used between greentea_client\source\test_env.cpp:greentea_notify_completion()
+ * and _open() to indicate that file is being open by gcov.
+ */
 bool coverage_report = false;
+
+/* Special file descriptor for gcov report. It helps in special handling of gcov report file, that
+ * is printing data on serial console rather than writing on file system.
+ */
 const int gcov_fd = 'g' + ((int)'c' << 8);
 
-void greentea_notify_coverage_start(const char *path);
-void greentea_notify_coverage_end(void);
+extern void greentea_notify_coverage_start(const char *path);
+extern void greentea_notify_coverage_end(void);
 #endif
 
 // Heap limits - only used if set
@@ -188,6 +195,7 @@ extern "C" FILEHANDLE PREFIX(_open)(const char* name, int openmode) {
 #if defined MBED_CFG_DEBUG_OPTIONS_COVERAGE
     else if(coverage_report) {
         init_serial();
+        // Encapsulate coverage data in greentea key,value pair.
         greentea_notify_coverage_start(name);
         return gcov_fd;
     }
@@ -252,6 +260,7 @@ extern "C" int PREFIX(_close)(FILEHANDLE fh) {
         return 0;
 #if defined MBED_CFG_DEBUG_OPTIONS_COVERAGE
     else if (coverage_report && gcov_fd == fh) {
+        // Close greentea key,value encapsulation
         greentea_notify_coverage_end();
         return 0;
     }

rtos/rtx/TARGET_CORTEX_M/cmsis_os.h

@@ -89,6 +89,7 @@
 #define DEFAULT_STACK_SIZE         (WORDS_STACK_SIZE/2)
 #else
 #if defined (MBED_CFG_DEBUG_OPTIONS_COVERAGE)
+/* GCOV works with stack size approx. 32K. */
 #define DEFAULT_STACK_SIZE         (WORDS_STACK_SIZE*4*8)
 #else
 #define DEFAULT_STACK_SIZE         (WORDS_STACK_SIZE*4)

targets/TARGET_Freescale/TARGET_KSDK2_MCUS/TARGET_MCU_K64F/device/TOOLCHAIN_GCC_ARM/MK64FN1M0xxx12.ld

@@ -52,7 +52,9 @@ ENTRY(Reset_Handler)
 
 __ram_vector_table__ = 1;
 
-/* Heap 1/4 of ram and stack 1/8 */
+/* Heap 1/4 of ram and stack 1/8. 0x1000 is reduced from both heap
+ * and stack to accomodate static data introduced by GCOV.
+ */
 __stack_size__ = 0x7000;
 __heap_size__ = 0x09000;
 

tools/build_api.py

@@ -299,6 +299,7 @@ def prepare_toolchain(src_paths, target, toolchain_name,
     config - a Config object to use instead of creating one
     app_config - location of a chosen mbed_app.json file
     build_profile - a dict of flags that will be passed to the compiler
+    coverage_filter - list of regex to filter source files for enabling coverage
     """
 
     # We need to remove all paths which are repeated to avoid
@@ -400,6 +401,7 @@ def build_project(src_paths, build_path, target, toolchain_name,
     config - a Config object to use instead of creating one
     app_config - location of a chosen mbed_app.json file
     build_profile - a dict of flags that will be passed to the compiler
+    coverage_filter - list of regex to filter source files for enabling coverage
     """
 
     # Convert src_path to a list if needed
@@ -540,6 +542,7 @@ def build_library(src_paths, build_path, target, toolchain_name,
     properties - UUUUHHHHH beats me
     extra_verbose - even more output!
     project_id - the name that goes in the report
+    coverage_filter - list of regex to filter source files for enabling coverage
     remove_config_header_file - delete config header file when done building
     app_config - location of a chosen mbed_app.json file
     build_profile - a dict of flags that will be passed to the compiler

tools/test_api.py

@@ -2119,6 +2119,9 @@ def build_tests(tests, base_source_paths, build_path, target, toolchain_name,
     """Given the data structure from 'find_tests' and the typical build parameters,
     build all the tests
 
+    Keyword arguments:
+        coverage_filter - list of regex to filter source files for enabling coverage
+
     Returns a tuple of the build result (True or False) followed by the test
     build data structure"""
 

tools/toolchains/gcc.py

@@ -84,6 +84,11 @@ def __init__(self, target,  notify=None, macros=None,
             self.cpu.append("-mfloat-abi=hard")
             self.cpu.append("-mno-unaligned-access")
 
+        # Coverage is turned On if coverage_filter is not empty. This means all sources are compiled with coverage
+        # macro and application is linked with coverage flags.
+        # Only source files that match regex from coverage_filter list are compiled with coverage flags. Since turning
+        # On code coverage on all sources increases static data size it overlaps with stack allocation and causes linker
+        # error.
         self.coverage_filter = coverage_filter
         if self.coverage_filter:
             self.macros.append(self.COVERAGE_MACRO)