Skip to content
masa002Public

About

Run Kotlin® on bare-metal microcontrollers: the official Kotlin/Native compiler's output on a Cortex-M4 with no OS and a small runtime of its own

Topics

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

kmicro: Kotlin® on bare-metal microcontrollers

CI Release License: Apache-2.0 Kotlin/Native 2.4.21 Target: Cortex-M RAM: 64 KB Status: experimental

Running Kotlin® on bare-metal microcontrollers, built by the official compiler.

kmicro runs the output of the unmodified Kotlin/Native 2.4.21 compiler on a Cortex-M with no operating system and 64 KB of RAM. It replaces the Kotlin/Native runtime with one written for a single thread and a heap of a few kilobytes: a precise garbage collector, exceptions, coroutines, strings, and cinterop to call C.

// hello.kt
fun main() {
    val names = List(3) { "Kotlin #${it + 1}" }
    println("Hello from ${names.joinToString()} on a bare Cortex-M")
}
$ python tools/kbuild.py build/hello hello.kt
kotlinc-native: compiling 1 file...
single-core: 113 init-state loads made plain
build\hello\k.o
$ python tools/qbuild.py build/hello/hello.elf targets/common/kotlin_main.c build/hello/k.o --run
qbuild: hello.elf  text 72996  data 80  bss 18740  stack 40960
Hello from Kotlin #1, Kotlin #2, Kotlin #3 on a bare Cortex-M
qemu: exit 0

kbuild compiles the Kotlin code for the Cortex-M4F, the default core; qbuild links it with the kmicro runtime and runs it on QEMU's emulated STM32L475. --cpu on both chooses another core, from the Cortex-M0 to the Cortex-M85, a Cortex-A or a Cortex-R core: docs/roadmap.md lists them with what was checked on each. examples/hello does the same from a C main, the way a firmware written in C starts calling Kotlin.

Status

kmicro is experimental. It grew out of a real device firmware (Origin): 24 modules written in Kotlin on an STM32L431 with 64 KB of RAM and 256 KB of flash. That firmware is not part of this repository; the examples, tests and the board run of the self-test are.

Most of the language and the standard library behave exactly as on stock Kotlin/Native: tools/difftest.py builds the same program for the host and for kmicro and compares the output byte for byte. The full list, feature by feature, is in docs/kotlin-support.md.

Works Notes
classes, interfaces, generics, lambdas, objects, data/sealed/enum/value classes, delegation
a Kotlin-only program with fun main(), or Kotlin functions called from a C main C names through --c-api or @CName
garbage collection precise mark-sweep in a fixed arena (KM_HEAP_BYTES), non-moving
strings, StringBuilder, println, readln UTF-16; text goes out through your kmicro_puts and comes in through kmicro_getc
exceptions, try/catch/finally, cause chains, runCatching, setUnhandledExceptionHook ARM EHABI unwinding; the uncaught-exception report prints the causes and the suppressed exceptions
coroutines (kotlin.coroutines) suspend, resume, sequence builders, your own event loop
collections, sequences, Regex, number formatting and parsing output byte-identical to stock Kotlin/Native; Regex needs a large heap (below)
kotlin.random, kotlin.time, Uuid, Platform, exitProcess clocks and entropy come from board hooks; the QEMU targets provide the clocks
atomics, including the atomic arrays atomic against interrupt handlers
cinterop: scalars, pointers, strings, globals, enums, structs by value, staticCFunction callbacks, varargs, StableRef kbuild runs cinterop for you (--def)
interrupt handlers in Kotlin they must not allocate; they may store references and use the atomics: docs/writing-kotlin.md, examples/irq

Every standard-library function that calls into the runtime is implemented, or stops the program with "... is not supported on kmicro" where it needs threads or an OS (python tools/missing_natives.py -v lists them).

Known gaps

The short list; docs/kotlin-support.md has every case.

  • Regex is big: the first pattern keeps 11.5 KB of the heap, three small patterns need a 20 KB heap, and a program that creates about 30 patterns in one function runs out of memory even at 64 KB. A program that uses Regex is about 369 KB of flash (243 KB with --size), against the STM32L431's 256 KB (what features cost). Deep backtracking over long input overflows the stack. RegexOption.CANON_EQ throws IllegalArgumentException.
  • Running out of memory stops the program: heap exhaustion ends with an out-of-memory report, not a catchable OutOfMemoryError (one request larger than the whole heap does throw). Kotlin/Native puts constant-size local arrays on the stack; kbuild warns about those above 512 bytes.
  • Faults are not exceptions: a stack overflow or a null-pointer read stops the program with a fault report (exit 99). The QEMU target qemu-l475 catches both with the MPU; the STM32L431 example reports faults but has no stack guard.
  • Board hooks: without them the clocks (measureTime, TimeSource.Monotonic, Clock.System) and Uuid.random() stop the program naming the missing hook, Random.Default repeats its sequence after every reset, and readln() sees the end of the input. runtime/kmicro.h lists the hooks.
  • Stack traces: addresses, at most 12 frames; tools/symbolize.py turns them into function names, with file and line when the code is built with -g. Functions that LTO inlines fold into their callers (reading a stack trace).
  • Smaller limits: kotlin.math results are within 2 ulp of stock (newlib's libm); nativeHeap, memScoped and cstr share a 1 KB arena (KM_INTEROP_BYTES); a public function whose backtick name contains a space cannot be exported to C (make it internal or private); on Windows, a file name with characters outside the ANSI code page fails in the xPack tools.

Limits by design:

  • One compiler version. kmicro reads the IR of Kotlin/Native 2.4.21. It builds on the linux_arm32_hfp target, which JetBrains has deprecated, so a later compiler may not offer it.
  • 32-bit ARM, and mostly Cortex-M. kmicro builds for the cores from the Cortex-M0 to the Cortex-M85, with or without an FPU, and for one core each of the A and the R profile, the Cortex-A7 and the Cortex-R52, which have run on QEMU only (--cpu; the cores and what was checked on each). The other Cortex-R and 32-bit Cortex-A cores are not supported. 64-bit ARM is out of reach: kmicro reads the IR of the compiler's 32-bit ARM target.
  • One thread. Interrupts are fine, with the rules in docs/writing-kotlin.md. There are no threads: Worker is not supported.
  • The standard library only. kotlinx libraries are untested.

Getting started

  1. Install the tools listed in BUILDING.md: Kotlin/Native 2.4.21 and a Java runtime to run it (its first compile downloads LLVM), the xPack Arm GCC (for newlib and libgcc), QEMU for Arm, Python 3.10 or later.
  2. python toolchain/paths.py shows what it found.
  3. python tests/run_all.py builds every test and example and runs them on an emulated STM32L475, and python -m unittest discover -s tests/unit tests the tools. The first run compiles each program with kotlinc-native, about a minute each.

Your own program is the hello world above: kbuild takes Kotlin files or a folder of them, and fun main() can be in any package (--main makes a missing one a build error).

Calling C. Name the C headers in a cinterop .def file. kbuild runs cinterop and also writes a bridges.o, which is linked with k.o:

python tools/kbuild.py build/app app.kt --def sensor.def -I include
python tools/qbuild.py build/app/app.elf targets/common/kotlin_main.c sensor.c build/app/k.o build/app/bridges.o -I include --run
@file:OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)

import sensor.*                 // sensor.def: headers = sensor.h, package = sensor

fun main() {
    val mv = List(sensor_count()) { sensor_read(it) }
    println("sensors: ${mv.joinToString { "$it mV" }}, average ${mv.average()} mV")
}

tests/cinterop_shapes shows structs by value, callbacks, globals, varargs and static inline header functions. examples/irq uses support/hw.def for register access and handles SysTick in Kotlin.

C calling Kotlin. --c-api app.h --package app gives the Kotlin functions of package app the C names of the prototypes in app.h, so a C main can call them after kmicro_init(): examples/hello.

On a real board, link k.o (and bridges.o) with runtime/, your startup code and a linker script. docs/porting.md explains each piece: the functions the board provides, the start-up, the runtime's compiler flags (clang, -fexceptions -funwind-tables, without which runtime/eh.c stops the build), the linker-script sections and the libraries. examples/selftest/stm32l431 does this for an STM32L431.

Numbers

examples/selftest on an STM32L431 at 16 MHz, 16 KB Kotlin heap. The times are from the board run recorded on 2026-10-16 (full report), made with earlier versions of the runtime, of board.c and of the build steps, before release 0.1.0. The run has not been repeated with the current runtime:

Check Time on 2026-10-16
runtime start (module initializers) 111 µs
classes, interface, virtual calls 53 µs
garbage collection: 6000+ objects through the 16 KB heap 161 ms
strings: 10 checks, UTF-16, JVM hashCode 1.5 ms
one throw + catch 1.6 ms*
coroutine: 300 suspend/resume cycles 49 ms
one full collection 1.8 ms

* The runtime of that run visited the same frame several times when it walked the stack for a stack trace; #3 stopped that. On QEMU a throw that the same small function catches now executes about 9,450 instructions: 7,150 to create the exception with its message and stack trace, 2,300 from the throw to the catch (more).

Repository layout

Folder Contents
runtime/ the Kotlin runtime, in C and C++; kmicro.h is its contract with the board
toolchain/ the build steps: paths.py finds the tools (tested versions in versions.txt), kn.py runs the pipeline, retarget.py, aapcs.py and bridges.py adapt the compiler's IR, binutils.py runs nm, objdump and the like on an image
support/ hw.h, hw.c, hw.def: volatile register access, barriers, interrupt masks for Kotlin
targets/ startup code and linker scripts for QEMU (qemu-l475 for programs, with a linker script for each machine the cores run on; qemu-an386 through qbuild --target an386 for programs that need more memory), and common/kotlin_main.c for fun main()
tools/ kbuild.py, qbuild.py, gen_regs.py (CMSIS to Kotlin), isr_check.py, symbolize.py, frames.py, insn_check.py, missing_natives.py, difftest.py, measure.py, irstat.py, port_dtoa.py
examples/ hello, irq (a Kotlin SysTick handler on registers), selftest (with its STM32L431 board files)
tests/ run_all.py and one folder per feature, expected/ (the outputs run_all compares), diff/ (the differential tests), unit/ for the tools
docs/ Kotlin support, how it works, writing Kotlin for a microcontroller, porting to a board, roadmap, design notes

Contributing

Bug reports, fixes and tests are welcome: CONTRIBUTING.md says how to build, test and send a change, and docs/roadmap.md where the open work is and how releases are numbered. CHANGELOG.md lists what each release contains. Report a security problem privately, as SECURITY.md describes.

Origin

kmicro started inside its author's own hardware project: a board that the author, Masahiro Obara, designed and built, with firmware the author wrote, first in C and then module by module in Kotlin (24 modules on an STM32L431). kmicro is the runtime and toolchain that made the Kotlin part possible; it was split out of that project and is developed on its own.

That firmware is a separate, unpublished project. It is not part of this repository, and nothing here licenses it; it uses kmicro like any other program. support/hw.h and tools/gen_regs.py were first written for it and are part of kmicro, under the same Apache License 2.0. kmicro and the firmware were made on the author's own time and equipment and are not related to the author's employer.

License

Copyright 2026 Masahiro Obara (masa002) and the kmicro contributors.

Apache License 2.0: LICENSE. Parts follow Kotlin/Native and Apache Harmony sources: NOTICE.

kmicro is an independent project, not affiliated with or endorsed by JetBrains or the Kotlin Foundation. "Kotlin" refers to the Kotlin® programming language.

About

Run Kotlin® on bare-metal microcontrollers: the official Kotlin/Native compiler's output on a Cortex-M4 with no OS and a small runtime of its own

Topics

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages