Semihosting part of core, RISC-V support (#2685)

Semihosting is handy for debugging, so allow the core to use `SerialSemi` as the
::printf port.  Add menu item to the IDE to allow selection.

Add RISC-V implementation of semihost call

Author: earlephilhower

boards.txt

@@ -126,6 +126,7 @@ extern const String emptyString;
 #endif
 
 #include "SerialUART.h"
+#include "SerialSemi.h"
 #include "RP2040Support.h"
 #include "SerialPIO.h"
 #include "Bootsel.h"

cores/rp2040/Arduino.h

@@ -20,8 +20,8 @@
 #pragma once
 
 #include "Semihosting.h"
-#include <FS.h>
-#include <FSImpl.h>
+#include "FS.h"
+#include "FSImpl.h"
 
 using namespace fs;
 
@@ -57,7 +57,7 @@ class SemiFSFileImpl : public FileImpl {
             a[0] = _fd;
             a[1] = (uint32_t)buf;
             a[2] = size;
-            return 0 == Semihost(SYS_WRITE, a) ? size : -1;
+            return 0 == Semihost(SEMIHOST_SYS_WRITE, a) ? size : -1;
         }
         return -1; // some kind of error
     }
@@ -68,7 +68,7 @@ class SemiFSFileImpl : public FileImpl {
             a[0] = _fd;
             a[1] = (uint32_t)buf;
             a[2] = size;
-            int ret = Semihost(SYS_READ, a);
+            int ret = Semihost(SEMIHOST_SYS_READ, a);
             if (ret == 0) {
                 return size;
             } else if (ret == (int)size) {
@@ -92,7 +92,7 @@ class SemiFSFileImpl : public FileImpl {
         uint32_t a[2];
         a[0] = _fd;
         a[1] = pos;
-        return !Semihost(SYS_SEEK, a);
+        return !Semihost(SEMIHOST_SYS_SEEK, a);
     }
 
     size_t position() const override {
@@ -105,7 +105,7 @@ class SemiFSFileImpl : public FileImpl {
         }
         uint32_t a;
         a = _fd;
-        int ret = Semihost(SYS_FLEN, &a);
+        int ret = Semihost(SEMIHOST_SYS_FLEN, &a);
         if (ret < 0) {
             return 0;
         }
@@ -119,7 +119,7 @@ class SemiFSFileImpl : public FileImpl {
     void close() override {
         if (_opened) {
             uint32_t a = _fd;
-            Semihost(SYS_CLOSE, &a);
+            Semihost(SEMIHOST_SYS_CLOSE, &a);
             _opened = false;
         }
     }
@@ -202,7 +202,7 @@ class SemiFSImpl : public FSImpl {
         a[0] = (uint32_t)path;
         a[1] = mode;
         a[2] = strlen(path);
-        int handle = Semihost(SYS_OPEN, a);
+        int handle = Semihost(SEMIHOST_SYS_OPEN, a);
         if (handle < 0) {
             return FileImplPtr();
         }
@@ -225,7 +225,7 @@ class SemiFSImpl : public FSImpl {
         a[1] = strlen(pathFrom);
         a[2] = (uint32_t)pathTo;
         a[3] = strlen(pathTo);
-        return !Semihost(SYS_RENAME, a);
+        return !Semihost(SEMIHOST_SYS_RENAME, a);
     }
 
     bool info(FSInfo& info) override {
@@ -237,7 +237,7 @@ class SemiFSImpl : public FSImpl {
         uint32_t a[2];
         a[0] = (uint32_t)path;
         a[1] = strlen(path);
-        return !Semihost(SYS_REMOVE, a);
+        return !Semihost(SEMIHOST_SYS_REMOVE, a);
     }
 
     bool mkdir(const char* path) override {
@@ -258,15 +258,15 @@ class SemiFSImpl : public FSImpl {
         a[0] = (uint32_t)path;
         a[1] = 0; // READ
         a[2] = strlen(path);
-        int fn = Semihost(SYS_OPEN, a);
+        int fn = Semihost(SEMIHOST_SYS_OPEN, a);
         if (fn < 0) {
             return false;
         }
         bzero(st, sizeof(*st));
         a[0] = fn;
-        st->size = Semihost(SYS_FLEN, a);
+        st->size = Semihost(SEMIHOST_SYS_FLEN, a);
         a[0] = fn;
-        Semihost(SYS_CLOSE, a);
+        Semihost(SEMIHOST_SYS_CLOSE, a);
         return true;
     }
 

libraries/Semihosting/src/SemiFS.h renamed to cores/rp2040/SemiFS.h

@@ -1,4 +1,6 @@
 #include "Semihosting.h"
+#include "SerialSemi.h"
+#include "SemiFS.h"
 
 SerialSemiClass SerialSemi;
 FS SemiFS = FS(FSImplPtr(new semifs::SemiFSImpl()));

libraries/Semihosting/src/Semihosting.cpp renamed to cores/rp2040/Semihosting.cpp

@@ -0,0 +1,99 @@
+/*
+    Semihosting.h - Semihosting for Serial and FS access via GDB
+    Copyright (c) 2024 Earle F. Philhower, III.  All rights reserved.
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+*/
+
+#pragma once
+
+// Be sure to only use this library with GDB and to enable the ARM semihosting support
+// (gdb) monitor arm semihosting enable
+
+// Input/output will be handled by OpenOCD
+
+// From https://developer.arm.com/documentation/dui0471/g/Semihosting/Semihosting-operations?lang=en
+typedef enum {
+    SEMIHOST_SYS_CLOSE = 0x02,
+    SEMIHOST_SYS_CLOCK = 0x10,
+    SEMIHOST_SYS_ELAPSED = 0x30,
+    SEMIHOST_SYS_ERRNO = 0x13,
+    SEMIHOST_SYS_FLEN = 0x0C,
+    SEMIHOST_SYS_GET_CMDLINE = 0x15,
+    SEMIHOST_SYS_HEAPINFO = 0x16,
+    SEMIHOST_SYS_ISERROR = 0x08,
+    SEMIHOST_SYS_ISTTY = 0x09,
+    SEMIHOST_SYS_OPEN = 0x01,
+    SEMIHOST_SYS_READ = 0x06,
+    SEMIHOST_SYS_READC = 0x07,
+    SEMIHOST_SYS_REMOVE = 0x0E,
+    SEMIHOST_SYS_RENAME = 0x0F,
+    SEMIHOST_SYS_SEEK = 0x0A,
+    SEMIHOST_SYS_SYSTEM = 0x12,
+    SEMIHOST_SYS_TICKFREQ = 0x31,
+    SEMIHOST_SYS_TIME = 0x11,
+    SEMIHOST_SYS_TMPNAM = 0x0D,
+    SEMIHOST_SYS_WRITE = 0x05,
+    SEMIHOST_SYS_WRITEC = 0x03,
+    SEMIHOST_SYS_WRITE0 = 0x04
+} SEMIHOST_OPCODES;
+
+#ifdef __arm__
+
+// From https://github.com/ErichStyger/mcuoneclipse/blob/master/Examples/MCUXpresso/FRDM-K22F/FRDM-K22F_Semihosting/source/McuSemihost.c
+static inline int __attribute__((always_inline)) Semihost(int reason, void *arg) {
+    int value;
+    __asm volatile(
+        "mov r0, %[rsn] \n" /* place semihost operation code into R0 */
+        "mov r1, %[arg] \n" /* R1 points to the argument array */
+        "bkpt 0xAB      \n" /* call debugger */
+        "mov %[val], r0 \n" /* debugger has stored result code in R0 */
+
+        : [val] "=r"(value)  /* outputs */
+        : [rsn] "r"(reason), [arg] "r"(arg)   /* inputs */
+        : "r0", "r1", "r2", "r3", "ip", "lr", "memory", "cc" /* clobber */
+    );
+    return value; /* return result code, stored in R0 */
+}
+#else
+
+// https://groups.google.com/a/groups.riscv.org/g/sw-dev/c/n-5VQ9PHZ4w/m/KbzH5t9MBgAJ
+static inline int __attribute__((always_inline)) Semihost(int reason, void *argPack) {
+    register int value asm("a0") = reason;
+    register void *ptr asm("a1") = argPack;
+    asm volatile(
+        // Force 16-byte alignment to make sure that the 3 instructions fall
+        // within the same virtual page.
+        " .balign 16    \n"
+        " .option push \n"
+        // Force non-compressed RISC-V instructions
+        " .option norvc \n"
+        // semihosting e-break sequence
+        " slli x0, x0, 0x1f \n" // # Entry NOP
+        " ebreak \n"			// # Break to debugger
+        " srai x0, x0,  0x7 \n" // # NOP encoding the semihosting call number 7
+        " .option pop \n"
+        /*mark (value) as an output operand*/
+        : "=r"(value) /* Outputs */
+        // The semihosting call number is passed in a0, and the argument in a1.
+        : "0"(value), "r"(ptr) /* Inputs */
+        // The "memory" clobber makes GCC assume that any memory may be arbitrarily read or written by the asm block,
+        //  so will prevent the compiler from reordering loads or stores across it, or from caching memory values in registers across it.
+        //  The "memory" clobber also prevents the compiler from removing the asm block as dead code.
+        : "memory" /* Clobbers */
+    );
+    return value;
+}
+#endif

cores/rp2040/Semihosting.h

@@ -21,7 +21,7 @@
 
 #include "Semihosting.h"
 
-#include <Arduino.h>
+#include "Arduino.h"
 #include "api/HardwareSerial.h"
 
 class SerialSemiClass : public HardwareSerial {
@@ -61,7 +61,7 @@ class SerialSemiClass : public HardwareSerial {
             _peeked = false;
             return _peekedChar;
         }
-        return Semihost(SYS_READC, nullptr);
+        return Semihost(SEMIHOST_SYS_READC, nullptr);
     }
 
     virtual int available() override {
@@ -80,7 +80,7 @@ class SerialSemiClass : public HardwareSerial {
 
     virtual size_t write(uint8_t c) override {
         int32_t param = c;
-        Semihost(SYS_WRITEC, &param);
+        Semihost(SEMIHOST_SYS_WRITEC, &param);
         return 1;
     }
 

libraries/Semihosting/src/SerialSemi.h renamed to cores/rp2040/SerialSemi.h

@@ -40,6 +40,9 @@ Simply include ``<Semihosting.h>`` in your application and use ``SerialSemi`` as
 * Baud rate, bit width, etc. are all ignored
 * Input is limited because ``read`` may hang indefinitely in the host and ``available`` is not part of the spec
 
+``SerialSemi`` can also be selected as the debug output port in the IDE, in which case ``::printf`` will write
+to the debugger directly.
+
 SemiFS - Host filesystem access through Semihosting
 ---------------------------------------------------
 

docs/semihosting.rst

@@ -86,6 +86,9 @@ digitalReadFast	KEYWORD2
 
 enableDoubleResetBootloader	KEYWORD2
 
+SerialSemi	KEYWORD2
+SemiFS	KEYWORD2
+
 openDir	KEYWORD2
 next	KEYWORD2
 getLastWrite	KEYWORD2