Initial commit

Author: Novakov

.gitignore

@@ -0,0 +1,3 @@
+build
+.vscode
+.idea

CMakeLists.txt

@@ -0,0 +1,21 @@
+cmake_minimum_required(VERSION 3.18)
+
+project(OrbcodeLibtrace NONE)
+
+option(ORBCODE_LIBTRACE_BUILD_TEST "Build tests" OFF)
+option(ORBCODE_LIBTRACE_DOCS "Build Doxygen documentation" OFF)
+
+if(ORBCODE_LIBTRACE_BUILD_TEST)
+    enable_language(C)
+    enable_language(CXX)
+endif()
+
+add_subdirectory(libs)
+
+if(ORBCODE_LIBTRACE_BUILD_TEST)
+    add_subdirectory(tests)
+endif()
+
+if(ORBCODE_LIBTRACE_DOCS)
+    add_subdirectory(docs)
+endif()

README.md

@@ -0,0 +1,107 @@
+# Orbcode Trace functions library
+
+## Overview
+This library provides C/C++ functions for configuring ARM Cortex-M trace components.
+
+## Contents
+Following features are supported:
+* Trace Port Interface Unit
+    * Configuring trace protocol
+* Instrumentation Trace Macrocell
+    * Configuring ITM
+    * Outputing data over stimulus ports
+* Data Watchpoint & Trace Unit
+    * Configuring DWT including PC sampling, timestamp generations and counters
+    * Setting up watchpoints
+
+All functions are available as header-only library depending only on CMSIS `core_cmXX.h` header provided by MCU vendor. Once library is available (see Installation section below) it can be used in application code as follow:
+
+```cpp
+#include "my_mcu_device.h" // Vendor-provided header that includes core_cmXX.h
+#include "orbcode/trace/tpiu.h"
+#include "orbcode/trace/itm.h"
+#include "orbcode/trace/dwt.h"
+
+static void ConfigureTraceComponents()
+{
+    TpiuOptions tpiu;
+    // TODO: setup TPIU using by setting fields in tpiu variable
+    ITMOptions itm;
+    // TODO: setup ITM using by setting fields in itm variable
+    DWTOptions dwt;
+    // TODO: setup DWT using by setting fields in dwt variable
+
+    // Apply configuration as defined in structs
+    TpiuSetup(&tpiu);
+    ITMSetup(&itm);
+    DWTSetup(&dwt);
+}
+
+static void UseITM()
+{
+    // Output data on ITM stimulus port
+    ITMWrite8(4, 'H');
+    ITMWrite8(4, 'E');
+    ITMWrite8(4, 'L');
+    ITMWrite8(4, 'L');
+    ITMWrite8(4, 'O');
+}
+
+int main()
+{
+    ConfigureVendorSpecificOptionsRequiredForTracing(); // i.e. clock, GPIOs
+    ConfigureTraceComponents();
+
+    UseITM();
+}
+```
+
+Refer to documentation of each module for details how each component is configured and what functionalities are available.
+
+**Warning:** Currently `libtrace` is optimistic when it comes to MCU capabilities. For devices with limited trace features it is possible for `libtrace` to generate invalid configuration. If that happens, please let us know by submitting issue and we will try to adapt library.
+
+## Installation
+As library is header only it is straightforward to use with any build system.
+
+### CMake + FetchContent
+For projects using CMake it is recommended to use `FetchContent` to download `libtrace` library and include it in build system automatically.
+
+Fetch library:
+
+```cmake
+include(FetchContent)
+
+FetchContent_Declare(
+    libtrace
+    GIT_REPOSITORY <todo>
+    GIT_TAG <todo>
+)
+FetchContent_MakeAvailable(libtrace)
+```
+
+Include `Orbcode::Trace` as dependency:
+
+```cmake
+target_link_libraries(MyApplication PUBLIC Orbcode::Trace)
+```
+
+### Other build systems
+Other build system must download `libtrace` manually (git submodule, wget, etc) and add folder `libs/trace/include` to include directories in compiler command line:
+
+```
+CFLAGS += -Idownloaded_libs/libtrace/libs/trace/include
+```
+
+## Building
+Although for end-user this library can be treated as header-only with no build steps required, for development of library itself it is useful to be able to generate proper build system.
+
+Simple command line for using Ninja generator:
+```
+cmake -G Ninja -S<libtrace source dir> -B<build directory> --toolchain <toolchain file for arm-none-eabi> -DORBCODE_LIBTRACE_BUILD_TEST=ON -DORBCODE_LIBTRACE_DOCS=ON
+ninja -C <build directory> # Compile test libraries
+ninja -C <build directory> docs # Generate Doxygen documentation in <build directory>/docs/html
+```
+
+Following options are availble:
+* `ORBCODE_LIBTRACE_BUILD_TEST` (default: `OFF`) - compile simple test files to make sure that header files are correct (useful for detecting syntax errors). When this option is enable toolchain capable for compiling for ARM Cortex-M is required (e.g. arm-none-eabi-gcc with `-mmcu=cortex-m3`)
+* `ORBCODE_LIBTRACE_DOCS` (default: `OFF`) - build Doxygen documentation (requires Doxygen)

docs/CMakeLists.txt

@@ -0,0 +1,15 @@
+find_package(Doxygen REQUIRED)
+
+set(DOXYGEN_GENERATE_HTML YES)
+set(DOXYGEN_USE_MATHJAX YES)
+set(DOXYGEN_SORT_MEMBER_DOCS NO)
+set(DOXYGEN_EXTRACT_STATIC YES)
+set(DOXYGEN_IMAGE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/images)
+set(DOXYGEN_PROJECT_NAME "Orbcode Trace functions library")
+set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${CMAKE_SOURCE_DIR}/README.md)
+
+doxygen_add_docs(docs
+    ${CMAKE_SOURCE_DIR}/libs
+    ${CMAKE_SOURCE_DIR}/README.md
+)
+

docs/images/trace/dwt_clocks.diagramsnet.svg

@@ -0,0 +1 @@
+add_subdirectory(trace)

libs/CMakeLists.txt

@@ -0,0 +1,7 @@
+set(NAME _orbcode_liborbtrace)
+
+add_library(${NAME} INTERFACE)
+
+target_include_directories(${NAME} INTERFACE include)
+
+add_library(Orbcode::Trace ALIAS _orbcode_liborbtrace)

libs/trace/CMakeLists.txt

@@ -0,0 +1,23 @@
+/**
+ * @defgroup trace ARM Cortex-M tracing functions
+ *
+ * This library provides set of low-level functions for setting up tracing components of ARM Cortex-M microcontrollers directly with code.
+ *
+ * Header files included in this library depend on CMSIS `core_cmXX.h` header files providing necessary type definitions and macros. They are however dependant on vendor specific information and cannot be used standalone (e.g. `IRQn_Type` is required to be defined before including `core_cmXX.h`). Therefore CMSIS headers are **not included** in this library and it is up to user to ensure proper include order:
+ *
+ * @code{.cpp}
+ * #include <my_mcu_cm3.h>         // Typically includes also core_cm3.h
+ * #include "orbcode/trace/tpiu.h" // Now we can include Orbcode functions
+ * @endcode
+ *
+ * Before trace components can be used, they need to be configured which invovles:
+ * 1. Setting up MCU specific options (trace clock, GPIO alternate functions) - refer to vendor's documentation for details.
+ * 2. Setting up TPIU responsible for pushing ITM and ETM data into physical layer (SWO or parallel trace) (See @ref tpiu).
+ * 3. Configure ITM module (if needed) for outputing user-defined data by stimulus port or pass-through of DWT output (See @ref itm).
+ * 4. Configure DWT module (if needed) for timestamping, PC sampling, watchpoints and various counters (See @ref dwt).
+ * 5. Configure ETM module (if needed) for instruction-level tracing (not covered by this library yet).
+ *
+ * Once trace components are configured they can be used during normal program operations (e.g. outputing data via ITM stimulus ports) or will automatically output data (like DWT PC sampling, watchpoints or ETM instruction trace).
+ *
+ * Refer to individual modules for details how to configure and use each component.
+ */