MicroPython: added headless and UART REPL build modes. Added support for frozen scripts. (#6)

MicroPython: implemented compile-time selectable modes for the MicroPython port.

- REPL_SYSCALL (default): Interactive REPL with over stdio. uses Newlib and read()/write() syscalls.
- HEADLESS: Frozen script, no stdio. Executes frozen script at startup.
- UART: REPL over UART, no stdio, optional frozen startup script.

Co-authored-by: Claude <noreply@anthropic.com>

Author: ccattuto

advanced/micropython/README.md

@@ -1,15 +1,70 @@
-## Compiling MicroPython
+# MicroPython port for riscv-emu.py
+
+This is a MicroPython port that runs on the riscv-emu.py RISC-V emulator.
+
+## Prerequisites
+
+Before building, ensure the micropython-lib submodule is initialized:
+
+```bash
+cd micropython
+git submodule update --init lib/micropython-lib
 ```
-cd port-riscv-emu.py
 
-# Build with default (RV32IM)
+## Building
+
+The port supports three build modes:
+
+### 1. REPL_SYSCALL (default)
+Interactive REPL on host's stdio:
+```bash
 make
+# or explicitly
+make MODE=REPL_SYSCALL
+```
 
-# Build with all extensions (RV32IMAC)
-make RVM=1 RVA=1 RVC=1
+### 2. HEADLESS
+Executes a frozen Python script with no stdio (requires `FROZEN_SCRIPT`, defaults to `startup.py`):
+```bash
+make MODE=HEADLESS FROZEN_SCRIPT=startup.py
 ```
 
-## Running MicroPython
+### 3. UART
+REPL over emulated UART, with an optional frozen initialization script (requires `FROZEN_SCRIPT`, defaults to `startup.py`):
+```bash
+make MODE=UART FROZEN_SCRIPT=startup.py
 ```
+
+## Build Options
+
+- `MODE` - Build mode: `REPL_SYSCALL` (default), `HEADLESS`, or `UART`
+- `FROZEN_SCRIPT` - Python script to freeze into firmware (required for HEADLESS, optional for UART, defaults to `startup.py`)
+- `RVM=1` - Enable RISC-V M extension (multiply/divide, default: enabled)
+- `RVA=0` - Enable RISC-V A extension (atomics, default: disabled)
+- `RVC=0` - Enable RISC-V C extension (compressed instructions, default: disabled)
+
+## Running
+
+In the emulator's root directory. Prebuilt binary:
+```bash
 ./riscv-emu.py --raw-tty --ram-size=4096 prebuilt/micropython.elf 
 ```
+
+Compiled binary, REPL over stdio (REPL_SYSCALL default build mode):
+```bash
+./riscv-emu.py --raw-tty --ram-size=4096 advanced/micropython/port-riscv-emu.py/build/firmware.elf
+```
+
+Compiled binary, headless (HEADLESS build mode):
+```bash
+./riscv-emu.py ---ram-size=4096 advanced/micropython/port-riscv-emu.py/build/firmware.elf
+```
+
+Compiled binary, REPL over UART (UART build mode):
+```bash
+./riscv-emu.py ---ram-size=4096 --uart advanced/micropython/port-riscv-emu.py/build/firmware.elf
+```
+And connect to MicroPython using your favorite terminal program:
+```bash
+screen /dev/ttys007 115200
+```

advanced/micropython/port-riscv-emu.py/Makefile

@@ -8,13 +8,59 @@ QSTR_DEFS = qstrdefsport.h
 # MicroPython feature configurations
 MICROPY_ROM_TEXT_COMPRESSION ?= 1
 
+# Mode selection (default to REPL_SYSCALL for backwards compatibility)
+# Valid values: REPL_SYSCALL, HEADLESS, UART
+MODE ?= REPL_SYSCALL
+
+# Script to embed (for HEADLESS and UART modes)
+FROZEN_SCRIPT ?= startup.py
+
+# Frozen module support for HEADLESS and UART modes
+# HEADLESS mode requires a frozen script
+# UART mode optionally accepts a frozen script
+ifeq ($(MODE),HEADLESS)
+    ifeq ($(FROZEN_SCRIPT),)
+        $(error HEADLESS mode requires FROZEN_SCRIPT to be set)
+    endif
+    FROZEN_ENABLED = 1
+else ifeq ($(MODE),UART)
+    ifneq ($(FROZEN_SCRIPT),)
+        FROZEN_ENABLED = 1
+    else
+        FROZEN_ENABLED = 0
+    endif
+else ifeq ($(MODE),REPL_SYSCALL)
+    FROZEN_ENABLED = 0
+else
+    $(error Invalid MODE=$(MODE). Valid values: REPL_SYSCALL, HEADLESS, UART)
+endif
+
+ifeq ($(FROZEN_ENABLED),1)
+    # Module name includes .py extension (manifest system registers with full filename)
+    FROZEN_MODULE_NAME = $(FROZEN_SCRIPT)
+
+    # Use manifest.py for freezing (idiomatic MicroPython approach)
+    # The manifest file will handle compilation via makemanifest.py
+    FROZEN_MANIFEST = $(CURDIR)/manifest.py
+
+    # Pass FROZEN_SCRIPT to manifest as a variable
+    MICROPY_MANIFEST_FROZEN_SCRIPT = $(FROZEN_SCRIPT)
+endif
+
 # include py core make definitions
 include $(TOP)/py/py.mk
 
 ifeq ($(CROSS), 1)
 CROSS_COMPILE ?= riscv64-unknown-elf-
 endif
 
+# MicroPython build tools
+MPY_CROSS ?= $(TOP)/mpy-cross/build/mpy-cross
+MPY_TOOL ?= $(PYTHON) $(TOP)/tools/mpy-tool.py
+# Flags for mpy-cross and mpy-tool to match port configuration
+MPY_CROSS_FLAGS += -msmall-int-bits=31
+MPY_TOOL_FLAGS += -mlongint-impl=longlong
+
 # Extension options - set to 1 to enable, 0 to disable
 # Note: the toolchain might not support all combinations
 RVM ?= 1  # Multiply/Divide (M extension)
@@ -34,12 +80,12 @@ ifeq ($(CROSS), 1)
 DFU = $(TOP)/tools/dfu.py
 PYDFU = $(TOP)/tools/pydfu.py
 CFLAGS_RISCV  = -march=$(MARCH) -mabi=ilp32 -D_REENT_SMALL
-CFLAGS += $(INC) -Wall -Werror -std=c99 $(CFLAGS_RISCV) $(COPT) #-O2
+CFLAGS += $(INC) -Wall -Werror -std=c99 $(CFLAGS_RISCV) $(COPT) -DMICROPY_PORT_MODE=MODE_$(MODE)
 LDFLAGS += -nostartfiles -static -Tlinker_newlib.ld --specs=nosys.specs
 else
 UNAME_S := $(shell uname -s)
 LD = $(CC)
-CFLAGS += $(INC) -Wall -Werror -Wdouble-promotion -Wfloat-conversion -std=c99 $(COPT)
+CFLAGS += $(INC) -Wall -Werror -Wdouble-promotion -Wfloat-conversion -std=c99 $(COPT) -DMICROPY_PORT_MODE=MODE_$(MODE)
 ifeq ($(UNAME_S),Linux)
 LDFLAGS += -nostartfiles -Wl,--gc-sections -static -Tlinker_newlib.ld --specs=nano.specs -Wl,-map,$@.map -Wl,-dead_strip
 else ifeq ($(UNAME_S),Darwin)
@@ -58,17 +104,23 @@ CFLAGS += -O2 -DNDEBUG
 CFLAGS += -fdata-sections -ffunction-sections
 endif
 
+# Add frozen module defines when frozen modules are enabled
+ifeq ($(FROZEN_ENABLED),1)
+CFLAGS += -DFROZEN_MODULE_NAME=\"$(FROZEN_MODULE_NAME)\"
+CFLAGS += -DMICROPY_HAS_FROZEN_MODULES=1
+endif
+
 # Flags for optional C++ source code
 CXXFLAGS += $(filter-out -std=c99,$(CFLAGS))
 
 LIBS = -lm
 
+# Common source files for all build modes
 SRC_C = \
 	main.c \
-	minimal_stubs.c \
 	gccollect.c \
-	mphalport.c \
-	shared/libc/printf.c \
+    minimal_stubs.c \
+    shared/libc/printf.c \
 	shared/readline/readline.c \
 	shared/runtime/pyexec.c \
 	shared/runtime/gchelper_native.c \
@@ -77,18 +129,30 @@ SRC_C = \
 	extmod/machine_mem.c \
 	extmod/moductypes.c
 
+SRC_S = \
+	start_newlib.S \
+    syscalls_newlib.S \
+	gchelper_rv32i.S
+
+# Select HAL based on build mode
+ifeq ($(MODE),REPL_SYSCALL)
+    # Mode 1: syscall-based I/O
+    SRC_C += mphalport.c
+else ifeq ($(MODE),HEADLESS)
+    # Mode 2: headless (no stdio)
+    SRC_C += mphalport_headless.c
+else ifeq ($(MODE),UART)
+    # Mode 3: UART MMIO I/O
+    SRC_C += mphalport_uart.c
+endif
+
 ifeq ($(CROSS), 1)
 SRC_C += shared/libc/string0.c
 endif
 
 SRC_QSTR += shared/readline/readline.c shared/runtime/pyexec.c extmod/modmachine.c extmod/machine_mem.c extmod/moductypes.c
 
-SRC_S = \
-	start_newlib.S \
-    syscalls_newlib.S \
-	gchelper_rv32i.S
-
-OBJ += $(PY_CORE_O)
+OBJ += $(PY_O)
 OBJ += $(addprefix $(BUILD)/, $(SRC_C:.c=.o))
 OBJ += $(addprefix $(BUILD)/, $(SRC_S:.S=.o))
 OBJ += $(addprefix $(BUILD)/, $(SRC_CXX:.cpp=.o))
@@ -99,9 +163,9 @@ else
 all: $(BUILD)/firmware.elf
 endif
 
-$(BUILD)/_frozen_mpy.c: $(TOP)/tests/frozen/frozentest.mpy $(BUILD)/genhdr/qstrdefs.generated.h
-	$(ECHO) "MISC freezing bytecode"
-	$(Q)$(TOP)/tools/mpy-tool.py -f -q $(BUILD)/genhdr/qstrdefs.preprocessed.h -mlongint-impl=none $< > $@
+# Print build configuration
+$(info Building MicroPython port in MODE=$(MODE))
+
 
 $(BUILD)/firmware.elf: $(OBJ)
 	$(ECHO) "LINK $@"

advanced/micropython/port-riscv-emu.py/main.c

@@ -5,6 +5,7 @@
 #include "py/objlist.h"
 #include "shared/runtime/pyexec.h"
 #include "shared/runtime/gchelper.h"
+#include "mpconfigport.h"
 
 extern uint8_t _gc_heap_start, _gc_heap_end;
 
@@ -19,9 +20,21 @@ int main(int argc, char *argv[]) {
 		mp_obj_list_append(mp_sys_argv, mp_obj_new_str(argv[i], strlen(argv[i])));
     }
 
+#if (MICROPY_PORT_MODE == MODE_REPL_SYSCALL)
+    // Welcome message for syscall REPL mode
     mp_printf(&mp_plat_print, "Welcome to MicroPython on RISC-V!\n");
+#endif
 
+#ifdef FROZEN_MODULE_NAME
+    // Execute frozen script (module name set by Makefile)
+    pyexec_frozen_module(FROZEN_MODULE_NAME, false);
+#endif
+
+#if (MICROPY_PORT_MODE == MODE_REPL_SYSCALL) || \
+    (MICROPY_PORT_MODE == MODE_UART)
+    // Start REPL
 	pyexec_friendly_repl();
+#endif
 
     gc_sweep_all();
     mp_deinit();

advanced/micropython/port-riscv-emu.py/manifest.py

@@ -0,0 +1,6 @@
+# Manifest for freezing Python scripts into firmware
+# This file defines which Python modules should be compiled and frozen into the firmware
+
+# Freeze startup.py (the default embedded script)
+# To freeze a different script, modify this file or specify FROZEN_SCRIPT in your Makefile
+freeze("$(PORT_DIR)", "startup.py")

advanced/micropython/port-riscv-emu.py/mpconfigport.h

@@ -1,8 +1,28 @@
 #include <stdint.h>
 
+// Force object representation A (default for 32-bit systems)
+// Use numeric value 0 since MICROPY_OBJ_REPR_A isn't defined yet
+#define MICROPY_OBJ_REPR (0)
+
 // options to control how MicroPython is built
 
-#define MICROPY_CONFIG_ROM_LEVEL (MICROPY_CONFIG_ROM_LEVEL_EXTRA_FEATURES)
+// Mode definitions (set via Makefile)
+#define MODE_REPL_SYSCALL    1  // Interactive REPL with syscalls
+#define MODE_HEADLESS        2  // Frozen script execution, no stdio
+#define MODE_UART            3  // Frozen init script + UART REPL
+
+#ifndef MICROPY_PORT_MODE
+#define MICROPY_PORT_MODE MODE_REPL_SYSCALL
+#endif
+
+// Use CORE_FEATURES ROM level as base, then explicitly enable what we need
+#define MICROPY_CONFIG_ROM_LEVEL (MICROPY_CONFIG_ROM_LEVEL_CORE_FEATURES)
+
+// Float support enabled for all modes
+#define MICROPY_PY_BUILTINS_FLOAT         (1)
+#define MICROPY_FLOAT_IMPL                (MICROPY_FLOAT_IMPL_FLOAT)
+#define MICROPY_PY_MATH                   (1)
+#define MICROPY_PY_CMATH                  (0)
 
 #define MICROPY_ENABLE_COMPILER     (1)
 #define MICROPY_ENAVLE_REPL	        (1)
@@ -12,30 +32,40 @@
 #define MICROPY_ENABLE_GC                 (1)
 #define MICROPY_HELPER_REPL               (1)
 #define MICROPY_ENABLE_REPL_HELPERS       (1)
-#define MICROPY_MODULE_FROZEN_MPY         (0)
+
 #define MICROPY_ENABLE_EXTERNAL_IMPORT    (0)
 #define MICROPY_KBD_EXCEPTION             (1)
 
+// MICROPY_MODULE_FROZEN_MPY is automatically defined by the manifest system, when needed
+
 // Enable core modules
 #define MICROPY_PY_MICROPYTHON            (1)
 #define MICROPY_PY_BUILTINS_HELP          (1)
 #define MICROPY_PY_BUILTINS_HELP_MODULES  (1)
 #define MICROPY_PY_GC                     (1)
 #define MICROPY_PY_BUILTINS_STR_UNICODE   (1)
-#define MICROPY_PY_BUILTINS_FLOAT         (1)
+
 #define MICROPY_LONGINT_IMPL              (MICROPY_LONGINT_IMPL_LONGLONG)
-#define MICROPY_FLOAT_IMPL                (MICROPY_FLOAT_IMPL_FLOAT)
 #define MICROPY_PY_BUILTINS_COMPLEX       (0)
 #define MICROPY_PY_IO                     (0)  // no file system or streams
+
+// Explicitly enable modules we need (some may not be in CORE_FEATURES)
 #define MICROPY_PY_ARRAY                  (1)
 #define MICROPY_PY_COLLECTIONS            (1)
-#define MICROPY_PY_MATH                   (1)
+#define MICROPY_PY_COLLECTIONS_DEQUE      (1)
+#define MICROPY_PY_COLLECTIONS_ORDEREDDICT (1)
 #define MICROPY_PY_URANDOM                (1)
+#define MICROPY_PY_URANDOM_SEED_INIT_FUNC (0)
 #define MICROPY_PY_STRUCT                 (1)
 #define MICROPY_PY_ERRNO                  (1)
 #define MICROPY_PY_BINASCII               (1)
 #define MICROPY_PY_RE                     (1)
+#define MICROPY_PY_HEAPQ                  (1)
+#define MICROPY_PY_HASHLIB                (0)
+#define MICROPY_PY_JSON                   (1)
 #define MICROPY_PY_UCTYPES                (1)
+
+// Enable machine module for MMIO access (mem8, mem16, mem32)
 #define MICROPY_PY_MACHINE                (1)
 #define MICROPY_PY_MACHINE_INCLUDEFILE    "modmachine_port.c"
 #define MICROPY_PY_MACHINE_MEMX           (1)
@@ -50,7 +80,6 @@
 #define MICROPY_PY_SYS_ARGV               (1)
 
 #define MICROPY_PY_BUILTINS_SLICE         (1)
-#define MICROPY_PY_ALL_FEATURES           (1)
 
 #define MICROPY_ALLOC_PATH_MAX            (256)
 

advanced/micropython/port-riscv-emu.py/mphalport_headless.c

@@ -0,0 +1,23 @@
+/*
+ * HAL implementation for HEADLESS mode
+ * Provides no-op stdio functions (print/input have no effect)
+ */
+
+#include "py/mphal.h"
+
+// stdin: Always return immediately with 0
+int mp_hal_stdin_rx_chr(void) {
+    return 0;
+}
+
+// stdout: Discard all output
+mp_uint_t mp_hal_stdout_tx_strn(const char *str, size_t len) {
+    (void)str;
+    (void)len;
+    return len;  // Pretend we wrote everything
+}
+
+void mp_hal_delay_ms(mp_uint_t ms) {
+    // No-op for headless mode
+    (void)ms;
+}