Merge pull request #28 from bcmi-labs/integrate-io

Integrate Arduino_ThreadsafeIO

Author: aentinger

Diff for: .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

Diff for: .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"

Diff for: .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.

Diff for: 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)

Diff for: 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);
+  }
+}

Diff for: 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);
+  }
+}

Diff for: examples/Threadsafe_Serial_GlobalPrefixSuffix/Threadsafe_Serial_GlobalPrefixSuffix.ino

@@ -0,0 +1,87 @@
+/**************************************************************************************
+ * INCLUDE
+ **************************************************************************************/
+
+#include <Arduino_ThreadsafeIO.h>
+
+/**************************************************************************************
+ * CONSTANTS
+ **************************************************************************************/
+
+static size_t constexpr NUM_THREADS = 5;
+
+/**************************************************************************************
+ * FUNCTION DECLARATION
+ **************************************************************************************/
+
+String serial_log_message_prefix(String const & /* msg */);
+String serial_log_message_suffix(String const & prefix, String const & msg);
+void   serial_thread_func();
+
+/**************************************************************************************
+ * GLOBAL VARIABLES
+ **************************************************************************************/
+
+static char thread_name[NUM_THREADS][32];
+#undef Serial
+#ifdef ARDUINO_PORTENTA_H7_M4
+  SerialDispatcher Serial(Serial1); /* No SerialUSB for Portenta H7 / M4 Core */
+#else
+  SerialDispatcher Serial(SerialUSB);
+#endif
+
+/**************************************************************************************
+ * SETUP/LOOP
+ **************************************************************************************/
+
+void setup()
+{
+  Serial.global_prefix(serial_log_message_prefix);
+  Serial.global_suffix(serial_log_message_suffix);
+
+  /* Fire up some threads all accessing the LSM6DSOX */
+  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(serial_thread_func);
+  }
+}
+
+void loop()
+{
+
+}
+
+/**************************************************************************************
+ * FUNCTION DEFINITION
+ **************************************************************************************/
+
+String serial_log_message_prefix(String const & /* msg */)
+{
+  char msg[32] = {0};
+  snprintf(msg, sizeof(msg), "[%05lu] ", millis());
+  return String(msg);
+}
+
+String serial_log_message_suffix(String const & prefix, String const & msg)
+{
+  return String("\r\n");
+}
+
+void serial_thread_func()
+{
+  Serial.begin(9600);
+
+  for(;;)
+  {
+    /* Sleep between 5 and 500 ms */
+    rtos::ThisThread::sleep_for(rtos::Kernel::Clock::duration_u32(random(5,500)));
+    /* Print a unbroken log message including thread name and timestamp as a prefix. */
+    Serial.block();
+    Serial.print(rtos::ThisThread::get_name());
+    Serial.print(": ");
+    Serial.print("Lorem ipsum ...");
+    Serial.unblock();
+  }
+}