Add vfd_bench and other improvements (#8)

Author: milesfrain

.clang-format

@@ -6,7 +6,7 @@ AlignAfterOpenBracket: Align
 AlignConsecutiveMacros: false
 AlignConsecutiveAssignments: false
 AlignConsecutiveDeclarations: false
-AlignEscapedNewlines: Right
+AlignEscapedNewlines: Left
 AlignOperands:   true
 AlignTrailingComments: true
 AllowAllArgumentsOnNextLine: true

.github/workflows/main.yml

@@ -8,5 +8,5 @@ jobs:
     - uses: actions/checkout@v2
     - name: CI action step for stm32
       id: stm32ci
-      uses: milesfrain/stm32-action@F4_V1.25.2
+      uses: milesfrain/stm32-action@F4_V1.25.2-local-share
 

.gitignore

@@ -6,3 +6,4 @@
 .metadata
 RemoteSystemsTempFiles
 FreeRTOS_TAD_logs
+*.bin

.vscode/c_cpp_properties.json

@@ -0,0 +1,20 @@
+{
+    "configurations": [
+        {
+            "name": "Linux",
+            "includePath": [
+                "${workspaceFolder}/**",
+                "/usr/local/share/stm_repo/STM32Cube_FW_F4_V1.25.2/Middlewares/Third_Party/FreeRTOS/Source/include",
+                "/usr/local/share/stm_repo/STM32Cube_FW_F4_V1.25.2/Middlewares/Third_Party/FreeRTOS/Source/CMSIS_RTOS",
+                "/usr/local/share/stm_repo/STM32Cube_FW_F4_V1.25.2/Middlewares/Third_Party/FreeRTOS/Source/portable/GCC/ARM_CM4F",
+                "/usr/local/share/stm_repo/STM32Cube_FW_F4_V1.25.2/Drivers/STM32F4xx_HAL_Driver/Inc"
+            ],
+            "defines": [],
+            "compilerPath": "/usr/bin/gcc",
+            "cStandard": "gnu17",
+            "cppStandard": "gnu++14",
+            "intelliSenseMode": "gcc-x64"
+        }
+    ],
+    "version": 4
+}

.vscode/launch.json

@@ -0,0 +1,50 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "g++ - Build and debug commander",
+      "type": "cppdbg",
+      "request": "launch",
+      "program": "${workspaceFolder}/host_apps/commander/commander",
+      "args": [],
+      "stopAtEntry": false,
+      "cwd": "${workspaceFolder}",
+      "environment": [],
+      "externalConsole": false,
+      "MIMode": "gdb",
+      "setupCommands": [
+        {
+          "description": "Enable pretty-printing for gdb",
+          "text": "-enable-pretty-printing",
+          "ignoreFailures": true
+        }
+      ],
+      "preLaunchTask": "C/C++: g++ build commander",
+      "miDebuggerPath": "/usr/bin/gdb"
+    },
+    {
+      "name": "g++ - Build and debug throughput",
+      "type": "cppdbg",
+      "request": "launch",
+      "program": "${workspaceFolder}/host_apps/throughput/throughput",
+      "args": [],
+      "stopAtEntry": false,
+      "cwd": "${workspaceFolder}",
+      "environment": [],
+      "externalConsole": false,
+      "MIMode": "gdb",
+      "setupCommands": [
+        {
+          "description": "Enable pretty-printing for gdb",
+          "text": "-enable-pretty-printing",
+          "ignoreFailures": true
+        }
+      ],
+      "preLaunchTask": "C/C++: g++ build throughput",
+      "miDebuggerPath": "/usr/bin/gdb"
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,33 @@
+{
+  "tasks": [
+    {
+      "type": "cppbuild",
+      "label": "C/C++: g++ build commander",
+      "command": "make",
+      "args": [],
+      "options": {
+        "cwd": "${workspaceFolder}/host_apps/commander"
+      },
+      "problemMatcher": [
+        "$gcc"
+      ],
+      "group": "build",
+      "detail": "Task generated by Debugger."
+    },
+    {
+      "type": "cppbuild",
+      "label": "C/C++: g++ build throughput",
+      "command": "make",
+      "args": [],
+      "options": {
+        "cwd": "${workspaceFolder}/host_apps/throughput"
+      },
+      "problemMatcher": [
+        "$gcc"
+      ],
+      "group": "build",
+      "detail": "Task generated by Debugger."
+    },
+  ],
+  "version": "2.0.0"
+}

README.md

@@ -1,24 +1,31 @@
 ## Overview
 
-This repo demonstrates how to incorporate some best practices into STM32CubeIDE-based projects. It preserves ST's .ioc workflow with autogeneration and easy pin reconfiguration in a git-friendly way, and also showcases:
+This repo demonstrates a strategy for working with STM32CubeIDE-based projects. It preserves ST's .ioc workflow with autogeneration and easy pin reconfiguration in a git-friendly way, and also showcases:
 - C++ used appropriately in a constrained embedded environment (no dynamic allocations - see [no_new.cpp](common/src/no_new.cpp)).
 - Convenience wrappers for static allocation of FreeRTOS components (see [static_rtos.h](common/inc/static_rtos.h))
 - Code deduplication:
   - Linking to versioned vendor firmware
   - Common code shared across projects
-- Unit testing with [CppUTest](https://cpputest.github.io/) (not used extensively yet, [example](common/tests/src/test_basic.cpp))
+- Unit testing with [CppUTest](https://cpputest.github.io/) ([example](common/tests/src/test_software_crc.cpp))
 - Code coverage with lcov
 - Autoformatting with [clang-format](https://clang.llvm.org/docs/ClangFormat.html)
 - ITM debug logging
 - FreeRTOS task profiling
-- High-performance UART and USB communication interface abstractions (see the [loopback](loopback) project)
+- High-performance UART and USB peripheral abstractions (see the [loopback](loopback) project)
 
 CI checks on each pull request ensure that all projects compile, pass unit tests, and are formatted correctly. Here are example PRs demonstrating:
 - [Broken build](https://github.com/milesfrain/stm32template/pull/2)
 - [Failing unit tests](https://github.com/milesfrain/stm32template/pull/3)
 - [Incorrect formatting](https://github.com/milesfrain/stm32template/pull/4)
 - [Passing all checks](https://github.com/milesfrain/stm32template/pull/5)
 
+## Projects
+
+- [`common`](common) - Common code shared among all projects.
+- [`loopback`](loopback) - Demonstrates sending binary packets across USB and UART peripherals.
+- [`vfd_bench`](vfd_bench) - A more real-world project demonstrating control of VFDs (variable-frequency drives) via modbus commands.
+- [`host_apps`](host_apps) - Applications which run on the host PC for communicating with the target microcontroller.
+
 ## Linux setup instructions
 
 These instructions were verified on a fresh install of Ubuntu 20.04.
@@ -34,7 +41,7 @@ sh st-stm32cubeide_1.4.0_7511_20200720_0928_amd64.sh
 ```
 Note that `ctrl-C` will let you jump to the bottom of the licenses.
 
-When updating the IDE, it will continue to use the original install path. So rather than requiring constant path editing or full IDE reinstalls for CI script compatibility, we're using a versionless symlinked path that's also compatible with the docker image directory structure. Set up that symlink by running (substitue `1.5.1` for your particular IDE version):
+When updating the IDE, it will continue to use the original install path. So rather than requiring constant path editing or full IDE reinstalls for CI script compatibility, we're using a versionless symlinked path that's also compatible with the docker image directory structure. Set up that symlink by running (substitute `1.5.1` for your particular IDE version):
 ```
 sudo mkdir /opt/st
 sudo ln -frs ~/st/stm32cubeide_1.5.1 /opt/st/stm32cubeide
@@ -86,9 +93,10 @@ sudo apt install libncurses5
 ### Setting-up the real workspace
 
 #### Firmware linking
+
 We need to setup a symlink to the STM FW repo to ensure we all share the same absolute path to shared project assets.
 ```
-sudo ln -s ~/STM32Cube/Repository /usr/share/stm_repo
+sudo ln -s ~/STM32Cube/Repository /usr/local/share/stm_repo
 ```
 Switch your workspace to the checked-out repo.
 ```
@@ -98,9 +106,16 @@ Use the symlinked firmware location in this workspace.
 ```
 Window > Preferences > STM32Cube > Firmware Updater > Firmware Repository
 ```
-Set to `/usr/share/stm_repo`.
+Set to `/usr/local/share/stm_repo`.
+
+#### Patching FreeRTOS
+
+There was a bug in FreeRTOS message buffers that has recently been [fixed](https://github.com/FreeRTOS/FreeRTOS-Kernel/pull/264); however, this fix has not yet been incorporated into [ST's F4 firmware package](https://github.com/STMicroelectronics/STM32CubeF4). As of writing, ST's F4 firmware V1.26.1 uses FreeRTOS V10.3.1. The FreeRTOS bug affects at least V10.4.1 and below.
+
+In the meantime, the simplest solution is to overwrite `Middlewares/Third_Party/FreeRTOS/Source` with a clone of this [patched repo](https://github.com/milesfrain/stm32FreeRTOS).
 
 #### Project import
+
 Add each folder to this workspace.
 ```
 File > Open Projects from Files System
@@ -111,22 +126,6 @@ loopback
 ```
 Now try building and flashing each project. Sometimes you'll need to expand the project folder in order for the build hammer to work.
 
-### Debugging info
-
-When you first debug, you'll see a popup. This default configuration works fine, but if you want to see ITM traces you'll need to enable SWV:
-`Debugger > Serial Wire Viewer`, check `Enable`, set `Core Clock` to `96.0`. This needs to match `SYSCLK` in the .ioc clock configuration.
-
-If you skip this step for the first pop-up, you can find the setting later under `Run > Debug Configurations`.
-
-To view ITM traces while debugging, open `Window > Show View > SWV > SWV ITM Data Console`. Click on the wrench icon in this new terminal and check `ITM Stimulus Ports` `2` and `0`. Logs are written to port `0`, but we're using port `2` as a workaround for this issue:
-https://community.st.com/s/question/0D53W00000Hx6dxSAB/bug-itm-active-port-ter-defaults-to-port-0-enabled-when-tracing-is-disabled
-
-Then click the red circle to "Start Trace". Note that this can only be toggled when execution is paused.
-
-For FreeRTOS task monitoring, install the extension described here:
-https://blog.the78mole.de/freertos-debugging-on-stm32-cpu-usage/
-
-
 ## New STM32CubeIDE project setup
 
 Here are some notes on the steps to create a new C++ project. You can either start a fresh project, or import an existing .ioc. This guide shows the "from .ioc" method.
@@ -157,7 +156,7 @@ In the `Project Explorer`, right click on the active project and select `Convert
 Copy the `custom` directory over from the `loopback` example. Note that you'll likely need to right-click on your project in the `Project Explorer` and select `Refresh` for this new folder to appear.
 
 #### Link to common code
-In the `Project Explorer`, right click on the active project, `New > Folder > Advaced > Link to ...`, paste:
+In the `Project Explorer`, right click on the active project, `New > Folder > Advanced > Link to ...`, paste:
 ```
 WORKSPACE_LOC/common
 ```

ci.sh

@@ -17,13 +17,20 @@ build_ret=$?
 ./unit.sh
 unit_ret=$?
 
+# build host apps
+pushd host_apps;
+make
+host_apps_ret=$?
+popd
+
 # disable echo for summaries
 set +x
 
 # print summaries
 echo format return $format_ret
 echo build return $build_ret
 echo unit test return $unit_ret
+echo host apps return $host_apps_ret
 
 status=$((format_ret || build_ret || unit_ret))
 echo exit status $status

common/README.md

@@ -0,0 +1,104 @@
+## Overview
+
+This directory contains common code shared across applications.
+
+## Interfaces
+
+Common [interfaces](inc/interfaces.h) (specifically `read()` and `write()`) enable composability among hardware abstractions and some FreeRTOS wrappers.
+
+See the [loopback](../loopback) and [vfd_bench](../vfd_bench) projects for more usage examples of these interfaces.
+
+## Static FreeRTOS Wrappers
+
+The STM32 applications in this repo use FreeRTOS. Most FreeRTOS components allow either dynamic or static allocation, with static allocation offering some additional runtime predictability. Unfortunately, static allocation can be more tedious and error-prone with the existing C-API. C++ wrappers simplify the creation of static components, and offer some additional conveniences.
+
+See [static_rtos.h](inc/static_rtos.h) for what wrappers are currently available. More wrappers may be added as required.
+
+## Hardware Abstractions
+
+High-performance hardware abstractions are available for UART and USB peripherals. These abstractions are DMA-based and built on top of FreeRTOS.
+
+Common interfaces make it easy to substitute peripherals. For example, it is trivial to swap a UART communications link for USB.
+
+See the [loopback](../loopback) project readme for more detailed examples of these abstractions in-use.
+
+## Binary Packets
+
+Data is sent between devices (e.g. microcontrollers and host PC) and between tasks running on each device as binary c-struct packets.
+
+<img src="../docs/images/binary-packet.png" width="600">
+
+Binary packets all share the following fields:
+- `magicStart` - A hardcoded value which improves efficiency of resynchronizing after data corruption.
+- `CRC` - The CRC value of all following bytes in the packet.
+- `length` - The number of bytes in the packet. This excludes the size of the first two `magicStart` and `CRC` fields. Those two fields are considered part of the "Packet Wrapper" and are only applied to data "on the wire". These fields are not passed around internally.
+- `sequenceNum` - An incrementing number assigned to each packet, which is used to check if any packets were dropped.
+- `origin` - Describes where the packet was created.
+- `id` - Describes which packet to use from the following `body` union field.
+- `body` - A union of all packet types. For efficiency, only the bytes used by the particular sub-type are transmitted, rather than always sending bytes for the full union.
+
+The packet definitions ([`packets.h`](inc/packets.h)) and parsing, printing, and packing code ([`packet_utils.cpp`](src/packet_utils.cpp)) are shared across all applications in this repo. This avoids packet definition mismatches between applications running on the host PC and target devices.
+
+To add new a binary packet, edit the following:
+- [`PacketID`](inc/packets.h)
+- [`Packet`](inc/packets.h)
+- [`packetBodySizeFromID`](inc/packets.h)
+- [`packetIdToString`](inc/packets.h)
+- [`snprintPacket`](src/packet_utils.cpp)
+
+
+## ITM Logging
+
+Tasks may send printf-style log messages over the ITM interface via the `ItmLogger`. Since this is commonly used by all tasks, it is included as part of [TaskUtilities](#Task-Utilities) for convenience.
+
+<img src="../docs/images/itm-logging.png" width="400">
+
+To see ITM traces in the IDE you'll need to enable SWV: `Run > Debug Configurations > Debugger > Serial Wire Viewer`, check `Enable`, set `Core Clock` to `96.0`. This needs to match `SYSCLK` in the .ioc clock configuration.
+
+To view ITM traces while debugging, open `Window > Show View > SWV > SWV ITM Data Console`. Click on the wrench icon in this new terminal and check `ITM Stimulus Ports` `31` and `0`. Logs are written to port `0`, but we're using port `31` as a workaround for [this issue](https://community.st.com/s/question/0D53W00000Hx6dxSAB/bug-itm-active-port-ter-defaults-to-port-0-enabled-when-tracing-is-disabled).
+
+Then click the red circle to "Start Trace". Note that this can only be toggled when execution is paused. When tracing is disabled, then the expensive printf formatting operation is skipped.
+
+<img src="../docs/images/itm-ide.png" width="600">
+
+Counters tracking incoming and outgoing byte and packet totals are also logged over ITM. These can be a helpful sanity check for troubleshooting suspected data loss. See the [`ItmPort` enum](inc/itm_logging.h) for port mapping. Unfortunately, the IDE interface is [not as user-friendly as it could be](https://community.st.com/s/question/0D53W00000Y4DuCSAV/log-numeric-data-in-swv-itm-data-console).
+
+An area of future work is to completely eliminate formatting operations from the target microcontroller. One possibility is to send an ID representing the particular format string, along with the raw arguments to the host for formatting.
+
+Note that [binary packets](#binary-packets) are another high-performance logging option that is currently available, but they're a bit more tedious to introduce than printf log statements for debugging purposes.
+
+## Watchdog
+
+A watchdog task monitors other tasks for unexpected stalls. A maximum of 24 tasks may be monitored, due to the use of FreeRTOS event group for efficiency.
+
+To use this feature, pass the watchdog object to each task you wish to monitor, then call `registerTask()` in each task's entry function, followed by `kick()` for each loop iteration.
+
+If any task is not kicked for 2000 ticks (2 seconds with current project config), then a stall is detected and a watchdog timeout is reported. This timeout report is sent over ITM logging and/or Binary Packet logging, depending on which output options are provided to the watchdog. This watchdog task may be extended to allow a hardware watchdog to reset the device; however, reporting without resetting seems like the most practical way to handle stalls during product prototyping.
+
+See [TaskUtilities](#Task-Utilities) for a more convenient way to use the watchdog.
+
+<img src="../docs/images/watchdog.png" width="300">
+
+## Error capture
+
+There are a limited number of hardware breakpoints available on Cortex-M devices. The STM32F4 has 6. In order to conserve the number of breakpoints that are necessary to detect a variety of errors, common error-detection functions in [`catch_errors.cpp`](src/catch_errors.cpp) are aggregated. For example, setting a single breakpoint at `catchDefault()` will break at all critical errors, nonCritical warnings, and non-ideal timeouts.
+
+<img src="../docs/images/catch.png" width="400">
+
+## Task Utilities
+
+<img src="../docs/images/task-utilities.png" width="500">
+
+Almost all tasks make use of ITM Logging and Watchdog. Task Utilities wraps this common functionality and adds some additional conveniences:
+
+### ITM Logging
+
+Manages a local `LogMsg` struct per task, which is necessary for high-performance logging.
+
+### Watchdog
+
+Manages a per-task ID necessary for using the watchdog functions. It also provides wrappers for `read()` and `write()` interfaces to allow infinite blocking without triggering watchdog timeouts, while still allowing inspecting stack frames of blocked tasks during debugging. Setting a breakpoint at `allTimeouts()` steps through all blocking tasks.
+
+### Initialization
+
+Rather than passing both a `Watchdog` and `ItmLogger` instance to each task, pass a single `TaskUtilitiesArg` to the task's constructor.

common/inc/basic.h

@@ -7,11 +7,26 @@
 
 // Just putting this here, so we don't need to include all of <algorithm>
 template<class T>
-const T& min(const T& a, const T& b)
+inline constexpr const T& min(const T& a, const T& b)
 {
   return a < b ? a : b;
 }
 
+template<class T>
+inline constexpr const T& max(const T& a, const T& b)
+{
+  return a > b ? a : b;
+}
+
+// Rounds up, rather than performing truncating integer division.
+// Assumes positive integers.
+// roundUpDiv(12, 7) == 2
+template<class T>
+inline constexpr T roundUpDiv(const T& n, const T& d)
+{
+  return (n + d - 1) / d;
+}
+
 // Helper function for concatenating prefix to names
 // Note that the existing strncat is not exactly what we need here.
 inline char* concat(char* dst, const char* s1, const char* s2, size_t len)
@@ -21,3 +36,8 @@ inline char* concat(char* dst, const char* s1, const char* s2, size_t len)
   strncpy(dst + lenS1, s2, len - lenS1);
   return dst;
 }
+
+// Could combine this macro with enum definition,
+// but might lose some IDE autocompletion
+#define ENUM_STRING(enumType, enumName) \
+  case enumType::enumName: return #enumName;