Repository navigation
Port NuttX
MicroCS as a NuttX application: the NSH command mcs (REPL, script runner, device shell on the
NuttX console) plus the MicroCS library, and optional real C# threads on NuttX pthreads
(Thread.Run, RunOn(cpu, …), Every, Worker, Channel; see docs/THREADS.md).
This port is the NuttX counterpart of the other optional OS backends (FreeRTOS, Zephyr, POSIX):
modules/os/mcs_os.c has an MCS_OS_NUTTX backend, selected automatically by the app
(-DMCS_OS=MCS_OS_NUTTX) and also by MCS_OS_AUTO when __NuttX__ is defined.
| Verified | 🧪 NuttX 12.11.0 simulator, single-core and SMP: CMake app, thread suite and bounded native-stack regression (make nuttx-test); single-core native GPIO simulator test; Make-built app and GPIO smoke test; minimal simulator with pthreads disabled |
| Not verified | physical boards, NuttX older than 12, and other NuttX configurations |
| Not there yet | 🗓️ Native GPIO interrupts, I2C, SPI, UART and other peripheral drivers; native networking |
# 1. put the app in the NuttX apps tree (a symlink is enough)
ln -s /path/to/MicroCS/ports/nuttx apps/interpreters/microcs
# 2. enable it: Application Configuration > Interpreters > MicroCS C# interpreter
# (and "Real threads on NuttX pthreads" for C# threads)
cd nuttx
tools/configure.sh sim:nsh # or your board:config
kconfig-tweak --enable CONFIG_INTERPRETERS_MICROCS
kconfig-tweak --enable CONFIG_INTERPRETERS_MICROCS_THREADS
make olddefconfig && make # or: cmake -B build -DBOARD_CONFIG=sim:nsh -GNinja && cmake --build build
# 3. on the NuttX shell
nsh> mcs --version
nsh> mcs -e "Console.WriteLine(Thread.Os);"
nsh> mcs /data/hello.cs
nsh> mcs # REPL / shell on the consolemcs takes the same arguments as the host CLI (ports/unix/main.c): --fs <dir> sets the root of
the C# File API (default: the current directory), -e evaluates a snippet, and so on.
Files come from the NuttX VFS: LittleFS, FAT, SmartFS, ROMFS, hostfs on the simulator, …
| Option | Default | |
|---|---|---|
INTERPRETERS_MICROCS_PROGNAME |
mcs |
NSH built-in name |
INTERPRETERS_MICROCS_PRIORITY |
100 | task priority of mcs
|
INTERPRETERS_MICROCS_STACKSIZE |
16384 | stack of the mcs task; stack needs depend on script and board (see below) |
| profile | full |
embedded, mcu, lowram, min = MCS_PROFILE_* (docs/CONFIGURATION.md) |
INTERPRETERS_MICROCS_USER_CONFIG_FILE |
– | path of a mcs_user_config.h that sets any MCS_* option |
INTERPRETERS_MICROCS_THREADS |
off | C# threads on pthreads (needs !DISABLE_PTHREAD) |
INTERPRETERS_MICROCS_GPIO |
off | 🧪 Enable native GPIO character devices (needs DEV_GPIO) |
Requirements: floating point and long long printf support (selected automatically) and a full
math library — the C# Math class uses hypot, fma, remainder, cbrt, log2, … NuttX's small
built-in libm does not have all of them; use the toolchain's libm, newlib or OpenLibm
(Library Routines > Math library).
NuttX printf limits double output to 15 significant digits. MCS_OWN_DTOA=1 (the NuttX
default) supplies exact digits for shortest-round-trip double formatting and explicit fixed,
number, percent, scientific and custom decimal formats. These use extra computation and stack;
the existing output buffer limits still apply to unusually large precision requests. Networking
APIs are disabled by default on NuttX and native networking has not been validated.
For a simulator build with CONFIG_DISABLE_PTHREAD=y, NuttX 12.11.0 also needed parent/child
scheduling, NSH pipelines and ostest disabled to avoid unrelated NuttX build errors. In this
configuration the nested-callback native stack guard below is unavailable.
Enable CONFIG_DEV_GPIO and CONFIG_INTERPRETERS_MICROCS_GPIO. The board must register and
configure /dev/gpioN itself; MicroCS pin N refers to that device, not necessarily a physical
pin number. Gpio.Mode validates the device's existing type and rejects mismatches; it does not
configure pin mux or direction. Reads and writes open the device and use NuttX GPIO ioctls, so they
are not interrupt-safe. Interrupts and rotary encoders are not provided by this backend. With
--sim, the simulated HAL is used instead. Test and validate the device permissions, wiring and
modes on the target board.
The compiler and native calls use the task stack; the 16 KB default is not a guarantee for arbitrary
scripts. Increase INTERPRETERS_MICROCS_STACKSIZE and measure on the target. When NuttX pthread
stack bounds are available, a best-effort guard checks stack space on nested interpreter callbacks
and raises StackOverflowException before the configured reserve is exhausted. Set
MCS_NUTTX_STACK_RESERVE in the user config (default 16384 bytes, capped at half the reported
stack size; 0 disables it). The guard can limit recursion earlier on small stacks; it does not cover
compiler recursion or all native calls, and cannot protect a task if stack bounds are unavailable.
On the 12.11.0 simulator, the focused nested-callback regression catches the exception and continues
with the default configuration. Previously, tests/t26_robustness.cs crashed with the 16 KB
default and repeated XIP runs could crash with 64 KB; source, image and ten repeated XIP runs passed
with 256 KB. These measurements are simulator-specific, not a recommended stack size or a guarantee
for a board.
- Each C# thread is a pthread with its own VM and heap. Stacks and heaps come from the NuttX heap:
budget
MCS_THREADS_MAX × (MCS_THREAD_STACK + MCS_THREAD_HEAP). -
RunOn(cpu, …)pins the thread with the pthread CPU affinity onCONFIG_SMP=ybuilds; with one CPUThread.Coresis 1 andRunOn(0, …)works, other cores raiseArgumentOutOfRangeException. - Thread priorities are relative to the creating thread (
+nis n levels more urgent), clamped to the range the scheduler policy allows (sched_get_priority_min/max). -
Scheduling: NuttX schedules threads FIFO unless
CONFIG_RR_INTERVALis set, so a script that spins would starve the shell at the same priority. Without round-robin the defaultMCS_THREAD_PRIORITYis therefore -1 on NuttX (workers run one level below the creator); withCONFIG_RR_INTERVAL > 0they useSCHED_RRat the creator's priority. Override withMCS_THREAD_PRIORITYin the user config. - The HAL event queue lock is NuttX's
enter_critical_section()(nested up to 8 deep), so it may be used from interrupt handlers as well.
make nuttx-test # sim:nsh, 1 CPU
NUTTX_SMP=1 make nuttx-test # plus an SMP simulator: Thread.Cores > 1, RunOn pinningtools/nuttx_check.sh downloads NuttX and apps (NUTTX_REF, default nuttx-12.11.0) into
build/nuttx, links this folder as apps/interpreters/microcs, builds sim:nsh with MicroCS and
threads, mounts tests/ through hostfs and runs tests/threads/t_threads.cs, comparing the output
with tests/threads/t_threads.out (excluding the interleaved thread exception diagnostics). The
single-core run also checks GPIO character devices and the nested-callback stack guard in source,
image and XIP modes. It needs git, cmake, ninja, genromfs, xxd and
pip install kconfiglib. The same job runs in CI.
By hand, on any simulator build that has CONFIG_FS_HOSTFS=y:
nsh> mount -t hostfs -o fs=/path/to/MicroCS/tests /host
nsh> mcs --fs /host/threads /host/threads/t_threads.cs
| File | |
|---|---|
Kconfig |
options above |
Make.defs, Makefile
|
NuttX Make build: src/*.c + modules/*/*.c of the repo, ports/unix/main.c as the mcs main |
CMakeLists.txt |
the same for the NuttX CMake build (ports/unix/main.c is the first source so its main becomes the built-in entry) |
mcs_port_nuttx.c, .h
|
opt-in GPIO character-device HAL |
Nothing is copied: the app builds the repository's sources in place, so a git pull of MicroCS
is all an update takes.
-
modules/os/mcs_os.cMCS_OS_NUTTX: pthreads (pthread_attr_setstacksize, explicit scheduling attributes,pthread_attr_setaffinity_np,pthread_setname_npwhen task names are enabled), pthread mutexes,sem_tsemaphores withsem_clockwaitonCLOCK_MONOTONIC,malloc/free,clock_gettimeticks. -
modules/fs/mcs_vfs_posix.cis the file system backend (NuttX has the POSIX file API). - NuttX defines a
CODEmacro in<nuttx/compiler.h>; the shell module's internal constants areSC_*for that reason. - NuttX's
mainof an app is renamed per built-in;ports/unix/main.cis shared, withgetcwd()as the default--fsroot because"."does not resolve inside a NuttX task.
Generated from the MicroCS repository (source branch · revision 37bd1f1). Edit the source files, not the wiki.
Start here
Step-by-step guides
- Guides
- Guide PC Simulator
- Guide ESP32
- Guide ESP32 C3 OLED
- Guide Raspberry Pi Pico
- Guide STM32
- Guide Arduino
- Guide Zephyr
- Guide Peripheral Settings
- Guide DMA
Hardware
- Hardware API
- Power Management
- Bluetooth LE
- CAN Bus
- Rotary Encoders
- Peripheral Configuration
- DMA
- Device Drivers
- Wi Fi and Networking
- U8g2 Displays
- LVGL Graphics
- Filesystem
- Threads
- Scheduler
Ports
- Porting and Build Systems
- Port ESP32
- Port RP2040 RP2350
- Port STM32
- Port STM32 Firmware
- Port Zephyr
- Port NuttX
- Port Arduino
C# and the runtime
- Language
- Standard Library
- JSON
- Standalone Firmware
- MicroCS Studio
- Web Flasher
- Studio Template Authoring
- Examples
- LVGL Examples
Embedding and tuning
- Embedding
- Configuration
- Small MCUs
- Memory Budgets
- Low RAM Firmware Example
- Performance
- Runtime Benchmark Comparison
- Lua Host Benchmark
Internals
Project