From f8f7627eb80a39d418419da10a7a41fa75bd5b48 Mon Sep 17 00:00:00 2001 From: Toby Jaffey Date: Fri, 12 Dec 2025 21:50:33 +0000 Subject: [PATCH] Update README. Add license --- README.md | 29 ++++++++++++++++++++++++++--- uvm32/uvm32.c | 26 ++++++++++++++++++++++++++ uvm32/uvm32.h | 6 +++--- 3 files changed, 55 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ca31cfa..62fcd0f 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ uvm32 is a minimalist, dependency-free virtual machine sandbox designed for micr On an [STM32L0](https://www.st.com/en/microcontrollers-microprocessors/stm32l0-series.html) (ARM Cortex-M0+) the required footprint is under 4KB flash/1KB RAM. +uvm32 is a RISC-V emulator, wrapped in a management interface and provided with tools to build efficient code to run in it. + ## What is it for? * As a no-frills alternative to embedded script engines ([Lua](https://www.lua.org/), [Duktape](https://duktape.org/), [MicroPython](https://micropython.org/), etc) @@ -11,6 +13,25 @@ On an [STM32L0](https://www.st.com/en/microcontrollers-microprocessors/stm32l0-s * As a way to allow development in modern systems programming languages where a compiler for the target may not be available ([rust-hello](apps/rust-hello)) * As a way to [write once, run anywhere](https://en.wikipedia.org/wiki/Write_once,_run_anywhere) and avoid maintaining multiple software variants +## How does it compare to the alternatives? + +Many scripting languages and virtual machines are available for embedding in small systems and they all make tradeoffs in different dimensions. + +uvm32 aims for: + +* Small footprint (suitable for embedded devices, games and apps) +* Support well-known programming languages for VM code (with high quality dev tools) +* Ease of integration into existing software +* Flexibility of paradigm (event driven, polling, multi-processor) +* Robustness against misbehaving VM code + +uvm32 does not aim for: + +* Frictionless [FFI](https://en.wikipedia.org/wiki/Foreign_function_interface) (no direct function calls between host and VM code) +* Maximum possible efficiency +* The simplest scripting experience for VM code (a develop-compile-run cycle is expected) +* "Batteries included" libraries to do stdio, networking, etc + ## Features * Bytecode example apps written in C, Zig, Rust and assembly @@ -29,7 +50,7 @@ uvm32 is a tiny virtual machine, all of the code is in [uvm32](uvm32). A minimal example of a host to run code in is at [host-mini](hosts/host-mini). -Everything else is a more advanced host, or a sample application which could be run. +Everything else is a more advanced host example, or a sample application which could be run in a host. ## Example @@ -66,10 +87,10 @@ int main(int argc, char *argv[]) { case UVM32_EVT_SYSCALL: // vm has paused to handle UVM32_SYSCALL switch(evt.data.syscall.code) { case UVM32_SYSCALL_PUTC: - printf("%c", uvm32_getval(&vmst, &evt, ARG0)); + printf("%c", uvm32_arg_getval(&vmst, &evt, ARG0)); break; case UVM32_SYSCALL_PRINTLN: { - const char *str = uvm32_getcstr(&vmst, &evt, ARG0); + const char *str = uvm32_arg_getcstr(&vmst, &evt, ARG0); printf("%s\n", str); } break; case UVM32_SYSCALL_YIELD: @@ -120,6 +141,8 @@ int main(int argc, char *argv[]) { ## Quickstart (docker) +The code in [uvm32](uvm32) to build a VM host is very portable and requires only a C compiler. However, many of the examples provided show how to build target code with different languages and tools. A Dockerfile is provided to set up the required environment. + make dockerbuild make dockershell diff --git a/uvm32/uvm32.c b/uvm32/uvm32.c index 536a7b7..3e5ba3c 100644 --- a/uvm32/uvm32.c +++ b/uvm32/uvm32.c @@ -1,3 +1,29 @@ +/*! +https://github.com/ringtailsoftware/uvm32 + +MIT License + +Copyright (c) 2025 Toby Jaffey + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +*/ + #define MINIRV32_IMPLEMENTATION #include "uvm32.h" diff --git a/uvm32/uvm32.h b/uvm32/uvm32.h index 51a207e..6f8f3e5 100644 --- a/uvm32/uvm32.h +++ b/uvm32/uvm32.h @@ -1,6 +1,3 @@ -#ifndef UVM32_H -#define UVM32_H 1 - /*! https://github.com/ringtailsoftware/uvm32 @@ -27,6 +24,9 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +#ifndef UVM32_H +#define UVM32_H 1 + /*! To use uvm32 in an environment without standard library headers, define CUSTOM_STDLIB_H to the name of header providing the equivalent types to stdint.h and stdbool.h */ #ifndef CUSTOM_STDLIB_H #include