Merge branch 'main' of /home/alex/projects/arduino/libraries/Arduino_ThreadsafeIO into integrate-io

Author: aentinger

.codespellrc

@@ -2,7 +2,7 @@
 [codespell]
 # In the event of a false positive, add the problematic word, in all lowercase, to a comma-separated list here:
 ignore-words-list = inot
-skip = ./.git
 builtin = clear,informal,en-GB_to_en-US
 check-filenames =
 check-hidden =
+skip = ./.git

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# See: https://docs.github.com/en/code-security/supply-chain-security/configuration-options-for-dependency-updates#about-the-dependabotyml-file
+version: 2
+
+updates:
+  # Configure check for outdated GitHub Actions actions in workflows.
+  # See: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-actions-up-to-date-with-dependabot
+  - package-ecosystem: github-actions
+    directory: / # Check the repository's workflows under /.github/workflows/
+    schedule:
+      interval: daily
+    labels:
+      - "topic: infrastructure"

.github/workflows/check-arduino.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Arduino Lint
         uses: arduino/arduino-lint-action@v1
         with:
-          compliance: strict
+          compliance: specification
           # Change this to "update" once the library is added to the index.
           library-manager: submit
           # Always use this setting for official repositories. Remove for 3rd party projects.

.github/workflows/compile-examples-private.yml

@@ -0,0 +1,97 @@
+name: Compile Examples
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    paths:
+      - ".github/workflows/compile-examples-private.ya?ml"
+      - "library.properties"
+      - "examples/**"
+      - "src/**"
+  pull_request:
+    paths:
+      - ".github/workflows/compile-examples-private.ya?ml"
+      - "library.properties"
+      - "examples/**"
+      - "src/**"
+  schedule:
+    # Run every Tuesday at 8 AM UTC to catch breakage caused by changes to external resources (libraries, platforms).
+    - cron: "0 8 * * TUE"
+  workflow_dispatch:
+  repository_dispatch:
+
+env:
+  SKETCHES_REPORTS_PATH: sketches-reports
+  SKETCHES_REPORTS_ARTIFACT_NAME: sketches-reports
+
+jobs:
+  build:
+    name: ${{ matrix.board.fqbn }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        board:
+          - fqbn: arduino:mbed_nano:nano33ble
+            platforms: |
+              - name: arduino:mbed_nano
+          - fqbn: arduino:mbed_nano:nanorp2040connect
+            platforms: |
+              - name: arduino:mbed_nano
+          - fqbn: arduino:mbed_portenta:envie_m4
+            platforms: |
+              - name: arduino:mbed_portenta
+          - fqbn: arduino:mbed_portenta:envie_m7
+            platforms: |
+              - name: arduino:mbed_portenta
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Compile examples
+        uses: arduino/compile-sketches@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          fqbn: ${{ matrix.board.fqbn }}
+          platforms: ${{ matrix.board.platforms }}
+          libraries: |
+            # Install the library from the local path.
+            - source-path: ./
+            # Additional library dependencies can be listed here.
+            # See: https://github.com/arduino/compile-sketches#libraries
+          sketch-paths: |
+            - examples
+          enable-deltas-report: true
+          sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }}
+
+      - name: Save sketches report as workflow artifact
+        uses: actions/upload-artifact@v2
+        with:
+          if-no-files-found: error
+          path: ${{ env.SKETCHES_REPORTS_PATH }}
+          name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
+
+  report-size-deltas:
+    needs: build
+    # Run even if some compilations failed.
+    if: always() && github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download sketches reports artifact
+        id: download-artifact
+        continue-on-error: true # If compilation failed for all boards then there are no artifacts
+        uses: actions/download-artifact@v2
+        with:
+          name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
+          path: ${{ env.SKETCHES_REPORTS_PATH }}
+
+      - name: Comment size deltas report to PR
+        uses: arduino/report-size-deltas@v1
+        # If actions/download-artifact failed, there are no artifacts to report from.
+        if: steps.download-artifact.outcome == 'success'
+        with:
+          sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }}

README.md

@@ -1,19 +1,59 @@
+<img src="https://content.arduino.cc/website/Arduino_logo_teal.svg" height="100" align="right" />
+
 `Arduino_Threads`
 =================
 
 [![Compile Examples status](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/compile-examples.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/compile-examples.yml)
 [![Check Arduino status](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/check-arduino.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/check-arduino.yml)
 [![Spell Check status](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/spell-check.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_Threads/actions/workflows/spell-check.yml)
 
-This library makes it easy to use the multi-threading capability of [Arduino](https://www.arduino.cc/) boards that use an [Mbed OS](https://os.mbed.com/docs/mbed-os/latest/introduction/index.html)-based core library.
+This library makes it easy to use the multi-threading capability of [Arduino](https://www.arduino.cc/) boards that use an [Mbed OS](https://os.mbed.com/docs/mbed-os/latest/introduction/index.html)-based core library. Additionally this library provides thread-safe access to `Wire`, `SPI` and `Serial` which is relevant when creating multi-threaded sketches in order to avoid common pitfalls such as race-conditions and invalid state.
 
 ## :zap: Features
-### :thread: Multi-threaded sketch execution
+### :thread: Multi-Threading 
+#### :thread: Multi-threaded sketch execution
 Instead of one big state-machine-of-doom you can split your application into multiple independent threads, each with it's own `setup()` and `loop()` function. Instead of implementing your application in a single `.ino` file, each independent thread is implemented in a dedicated `.inot` representing a clear separation of concerns on a file level.
 
-### :calling: Easy communication between multiple threads
+#### :calling: Easy communication between multiple threads
 Easy inter-thread-communication is facilitated via a `Shared` abstraction providing thread-safe sink/source semantics allowing to safely exchange data of any type between threads.
 
+### :thread: Threadsafe IO
+#### :thread: Threadsafe
+A key problem of multi-tasking is the **prevention of erroneous state when multiple threads share a single resource**. The following example borrowed from a typical application demonstrates the problems resulting from multiple threads sharing a single resource:
+
+Imagine a embedded system where multiple `Wire` client devices are physically connected to a single `Wire` server. Each `Wire` client device is managed by a separate software thread. Each thread polls its `Wire` client device periodically. Access to the I2C bus is managed via the `Wire` library and typically follows this pattern:
+
+```C++
+/* Wire Write Access */
+Wire.beginTransmission(addr);
+Wire.write(val);
+Wire.endTransmission();
+
+/* Wire Read Access */
+Wire.beginTransmission(addr);
+Wire.write(val);
+Wire.endTransmission();
+Wire.requestFrom(addr, bytes)
+while(Wire.available()) {
+  int val = Wire.read();
+}
+```
+
+Since we are using [ARM Mbed OS](https://os.mbed.com/mbed-os/) which is a [preemptive](https://en.wikipedia.org/wiki/Preemption_(computing)) [RTOS](https://en.wikipedia.org/wiki/Real-time_operating_system) for achieving multi-tasking capability and under the assumption that all threads share the same priority (which leads to a [round-robin](https://en.wikipedia.org/wiki/Round-robin_scheduling) scheduling) it can easily happen that one thread is half-way through its Wire IO access when the scheduler interrupts it and schedules the next thread which in turn starts/continues/ends its own Wire IO access.
+
+As a result this interruption by the scheduler will break Wire IO access for both devices and leave the Wire IO controller in an undefined state. :fire:.
+
+`Arduino_ThreadsafeIO` solves this problem by encapsulating a complete IO access (e.g. reading from a `Wire` client device) within a single function call which generates an IO request to be asynchronously executed by a high-priority IO thread. The high-priority IO thread is the **only** instance which actually directly communicates with physical hardware.
+
+#### :zzz: Asynchronous
+
+The mechanisms implemented in this library allow any thread to dispatch an IO request asynchronously and either continue operation or [yield](https://en.wikipedia.org/wiki/Yield_(multithreading))-ing control to the next scheduled thread. All IO requests are stored in a queue and are executed within a high-priority IO thread after a context-switch. An example of this can be seen [here](examples/Threadsafe_SPI/Threadsafe_SPI.ino)).
+
+#### :sparkling_heart: Convenient API
+
+Although you are free to directly manipulate IO requests and responses (e.g. [Threadsafe_Wire](examples/Threadsafe_Wire/Threadsafe_Wire.ino)) there do exist convenient `read`/`write`/`write_then_read` abstractions inspired by the [Adafruit_BusIO](https://github.com/adafruit/Adafruit_BusIO) library (e.g. [Threadsafe_Wire_BusIO](examples/Threadsafe_Wire_BusIO/Threadsafe_Wire_BusIO.ino)).
+
+
 ## :mag_right: Resources
 
 * [How to install a library](https://www.arduino.cc/en/guide/libraries)

examples/Threadsafe_SPI/Threadsafe_SPI.ino

@@ -0,0 +1,89 @@
+/**************************************************************************************
+ * INCLUDE
+ **************************************************************************************/
+
+#include <Arduino_ThreadsafeIO.h>
+
+/**************************************************************************************
+ * CONSTANTS
+ **************************************************************************************/
+
+static int  const BMP388_CS_PIN  = 2;
+static int  const BMP388_INT_PIN = 6;
+static byte const BMP388_CHIP_ID_REG_ADDR = 0x00;
+
+static size_t constexpr NUM_THREADS = 20;
+
+/**************************************************************************************
+ * FUNCTION DECLARATION
+ **************************************************************************************/
+
+byte bmp388_read_reg(byte const reg_addr);
+void bmp388_thread_func();
+
+/**************************************************************************************
+ * GLOBAL VARIABLES
+ **************************************************************************************/
+
+BusDevice bmp388(SPI, BMP388_CS_PIN, 1000000, MSBFIRST, SPI_MODE0);
+
+static char thread_name[NUM_THREADS][32];
+
+/**************************************************************************************
+ * SETUP/LOOP
+ **************************************************************************************/
+
+void setup()
+{
+  Serial.begin(9600);
+  while (!Serial) { }
+
+  pinMode(BMP388_CS_PIN, OUTPUT);
+  digitalWrite(BMP388_CS_PIN, HIGH);
+
+  for(size_t i = 0; i < NUM_THREADS; i++)
+  {
+    snprintf(thread_name[i], sizeof(thread_name[i]), "Thread #%02d", i);
+    rtos::Thread * t = new rtos::Thread(osPriorityNormal, OS_STACK_SIZE, nullptr, thread_name[i]);
+    t->start(bmp388_thread_func);
+  }
+}
+
+void loop()
+{
+
+}
+
+/**************************************************************************************
+ * FUNCTION DEFINITION
+ **************************************************************************************/
+
+byte bmp388_read_reg(byte const reg_addr)
+{
+  /* REG_ADDR | DUMMY_BYTE | REG_VAL is on SDO */
+  byte read_write_buf[] = {static_cast<byte>(0x80 | reg_addr), 0, 0};
+
+  IoRequest req(read_write_buf, sizeof(read_write_buf), nullptr, 0);
+  IoResponse rsp = bmp388.transfer(req);
+
+  /* Do other stuff */
+
+  rsp->wait();
+
+  return read_write_buf[2];
+}
+
+void bmp388_thread_func()
+{
+  for(;;)
+  {
+    /* Sleep between 5 and 500 ms */
+    rtos::ThisThread::sleep_for(rtos::Kernel::Clock::duration_u32(random(5,500)));
+    /* Try to read some data from the BMP3888. */
+    byte const chip_id = bmp388_read_reg(BMP388_CHIP_ID_REG_ADDR);
+    /* Print thread id and chip id value to serial. */
+    char msg[64] = {0};
+    snprintf(msg, sizeof(msg), "%s: Chip ID = 0x%X", rtos::ThisThread::get_name(), chip_id);
+    Serial.println(msg);
+  }
+}

examples/Threadsafe_SPI_BusIO/Threadsafe_SPI_BusIO.ino

@@ -0,0 +1,84 @@
+/**************************************************************************************
+ * INCLUDE
+ **************************************************************************************/
+
+#include <Arduino_ThreadsafeIO.h>
+
+/**************************************************************************************
+ * CONSTANTS
+ **************************************************************************************/
+
+static int  const BMP388_CS_PIN  = 2;
+static int  const BMP388_INT_PIN = 6;
+static byte const BMP388_CHIP_ID_REG_ADDR = 0x00;
+
+static size_t constexpr NUM_THREADS = 20;
+
+/**************************************************************************************
+ * FUNCTION DECLARATION
+ **************************************************************************************/
+
+byte bmp388_read_reg(byte const reg_addr);
+void bmp388_thread_func();
+
+/**************************************************************************************
+ * GLOBAL VARIABLES
+ **************************************************************************************/
+
+BusDevice bmp388(SPI, BMP388_CS_PIN, 1000000, MSBFIRST, SPI_MODE0);
+
+static char thread_name[NUM_THREADS][32];
+
+/**************************************************************************************
+ * SETUP/LOOP
+ **************************************************************************************/
+
+void setup()
+{
+  Serial.begin(9600);
+  while (!Serial) { }
+
+  pinMode(BMP388_CS_PIN, OUTPUT);
+  digitalWrite(BMP388_CS_PIN, HIGH);
+
+  for(size_t i = 0; i < NUM_THREADS; i++)
+  {
+    snprintf(thread_name[i], sizeof(thread_name[i]), "Thread #%02d", i);
+    rtos::Thread * t = new rtos::Thread(osPriorityNormal, OS_STACK_SIZE, nullptr, thread_name[i]);
+    t->start(bmp388_thread_func);
+  }
+}
+
+void loop()
+{
+
+}
+
+/**************************************************************************************
+ * FUNCTION DEFINITION
+ **************************************************************************************/
+
+byte bmp388_read_reg(byte const reg_addr)
+{
+  /* REG_ADDR | DUMMY_BYTE | REG_VAL is on SDO */
+  byte write_buf[2] = {static_cast<byte>(0x80 | reg_addr), 0};
+  byte read_buf = 0;
+
+  bmp388.spi().write_then_read(write_buf, sizeof(write_buf), &read_buf, sizeof(read_buf));
+  return read_buf;
+}
+
+void bmp388_thread_func()
+{
+  for(;;)
+  {
+    /* Sleep between 5 and 500 ms */
+    rtos::ThisThread::sleep_for(rtos::Kernel::Clock::duration_u32(random(5,500)));
+    /* Try to read some data from the BMP3888. */
+    byte const chip_id = bmp388_read_reg(BMP388_CHIP_ID_REG_ADDR);
+    /* Print thread id and chip id value to serial. */
+    char msg[64] = {0};
+    snprintf(msg, sizeof(msg), "%s: Chip ID = 0x%X", rtos::ThisThread::get_name(), chip_id);
+    Serial.println(msg);
+  }
+}