mirror/uvm32
1
Fork 0
mirror of https://github.com/ringtailsoftware/uvm32.git synced 2026-06-05 22:43:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update README.

Browse source 
Add license
This commit is contained in:
Toby Jaffey 2025-12-12 21:50:33 +00:00
parent 789cd74516
commit f8f7627eb8
3 changed files with 55 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

29
README.md
View file

@ -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

26
uvm32/uvm32.c
View file

@ -1,3 +1,29 @@
/*!
https://github.com/ringtailsoftware/uvm32
MIT License
Copyright (c) 2025 Toby Jaffey <toby@ringtailsoftware.co.uk>
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"

6
uvm32/uvm32.h
View file

@ -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 <stdint.h>