Port specific definitions for port of Microvium to CHERIoT RTOS. More...

#include <assert.h>
#include <cheri-builtins.h>
#include <compartment.h>
#include <stdbool.h>
#include <stdint.h>
#include <string.h>

Macros
#define	MVM_PORT_VERSION 1
	The version of the port interface that this file is implementing.
#define	MVM_STACK_SIZE 256
	Number of bytes to use for the stack.
#define	MVM_ALLOCATION_BUCKET_SIZE 256
	When more space is needed for the VM heap, the VM will malloc blocks with a minimum of this size from the host.
#define	MVM_MAX_HEAP_SIZE 1024
	The maximum size of the virtual heap before an MVM_E_OUT_OF_MEMORY error is given.
#define	MVM_NATIVE_POINTER_IS_16_BIT 0
	Set to 1 if a void* pointer is natively 16-bit (e.g.
#define	MVM_SUPPORT_FLOAT 0
	Set to 1 to compile in support for floating point operations (64-bit).
#define	MVM_SAFE_MODE 0
	Set to 1 to enable additional internal consistency checks, or 0 to disable them.
#define	MVM_DONT_TRUST_BYTECODE 1
	Set to 1 to enable extra validation checks of bytecode while executing.
#define	MVM_VERY_EXPENSIVE_MEMORY_CHECKS 0
	Not recommended!
#define	MVM_LONG_PTR_TYPE void *
	A long pointer is a type that can refer to either ROM or RAM.
#define	MVM_LONG_PTR_NEW(p)
	Convert a normal pointer to a long pointer.
#define	MVM_LONG_PTR_TRUNCATE(p)
	Truncate a long pointer to a normal pointer.
#define	MVM_LONG_PTR_ADD(p, s)
	Add an offset s in bytes onto a long pointer p.
#define	MVM_LONG_PTR_SUB(p2, p1)
	Subtract two long pointers to get an offset.
#define	MVM_READ_LONG_PTR_1(lpSource)
#define	MVM_READ_LONG_PTR_2(lpSource)
#define	MVM_LONG_MEM_CMP(p1, p2, size)
	Reference to an implementation of memcmp where p1 and p2 are LONG_PTR.
#define	MVM_LONG_MEM_CPY(target, source, size)
	Reference to an implementation of memcpy where source is a LONG_PTR.
#define	MVM_FATAL_ERROR(vm, e)
	This is invoked when the virtual machine encounters a critical internal error and execution of the VM should halt.
#define	MVM_ALL_ERRORS_FATAL 0
	Set MVM_ALL_ERRORS_FATAL to 1 to have the MVM_FATAL_ERROR handler called eagerly when a new error is encountered, rather than returning an error code from mvm_call.
#define	MVM_SWITCH(tag, upper)
#define	MVM_CASE(value)
#define	MVM_CHECK_CRC16_CCITT(lpData, size, expected)
	Macro that evaluates to true if the CRC of the given data matches the expected value.
#define	MVM_INCLUDE_SNAPSHOT_CAPABILITY 0
	Set to 1 to compile in the ability to generate snapshots (mvm_createSnapshot).
#define	MVM_INCLUDE_DEBUG_CAPABILITY 0
	Set to 1 to compile support for the debug API (mvm_dbg_*).
#define	MVM_USE_SINGLE_RAM_PAGE 0
	On architectures like small ARM MCUs where there is a large address space (e.g.
#define	MVM_EXPORT __cheri_libcall
	All public functions are exported from the library.
#define	MVM_CONTEXTUAL_MALLOC(size, context)
	Implementation of malloc and free to use.
#define	MVM_CONTEXTUAL_FREE(ptr, context)
#define	MVM_GAS_COUNTER
	Expose the timeout APIs.
#define	MVM_INT32TOSTRING(buffer, i)
#define	MVM_POINTER_SET_BOUNDS(ptr, bounds)
	Apply bounds to the buffer.
#define	MVM_POINTER_MAKE_IMMUTABLE(ptr)
	Remove all permissions except load and global.

Functions
static uint16_t	crc16 (MVM_LONG_PTR_TYPE lp, uint16_t size)
static int	mvm_int_to_string_helper (char buffer[12], int32_t value)
	Helper for Microvium to convert strings to integers.

Detailed Description

Port specific definitions for port of Microvium to CHERIoT RTOS.

Definition in file microvium_port.h.

Macro Definition Documentation

◆ MVM_ALL_ERRORS_FATAL

#define MVM_ALL_ERRORS_FATAL 0

Set MVM_ALL_ERRORS_FATAL to 1 to have the MVM_FATAL_ERROR handler called eagerly when a new error is encountered, rather than returning an error code from mvm_call.

This is mainly for debugging the VM itself, since the MVM_FATAL_ERROR handler is called before unwinding the C stack.

Definition at line 218 of file microvium_port.h.

◆ MVM_ALLOCATION_BUCKET_SIZE

#define MVM_ALLOCATION_BUCKET_SIZE 256

When more space is needed for the VM heap, the VM will malloc blocks with a minimum of this size from the host.

Note that the VM can also allocate blocks larger than this. It will do so if it needs a larger contiguous space than will fit in a standard block, and also during heap compaction (runGC) where it defragments the heap into as few mallocd blocks as possible to make access more efficient.

Definition at line 47 of file microvium_port.h.

◆ MVM_CASE

#define MVM_CASE ( value )

Value:

case value

Definition at line 221 of file microvium_port.h.

◆ MVM_CHECK_CRC16_CCITT

#define MVM_CHECK_CRC16_CCITT	(	lpData,
		size,
		expected )

Value:

(crc16(lpData, size) == expected)

Macro that evaluates to true if the CRC of the given data matches the expected value.

Note that this is evaluated against the bytecode, so lpData needs to be a long pointer type. If you don't want the overhead of validating the CRC, just return true.

Definition at line 229 of file microvium_port.h.

◆ MVM_CONTEXTUAL_FREE

#define MVM_CONTEXTUAL_FREE	(		ptr,
			context )

Value:

(void)heap_free((AllocatorCapability)context, ptr)

Definition at line 315 of file microvium_port.h.

◆ MVM_CONTEXTUAL_MALLOC

#define MVM_CONTEXTUAL_MALLOC	(		size,
			context )

Value:

({                                                                         \
    Timeout t   = {0, MALLOC_WAIT_TICKS};                                  \
    void   *ret = heap_allocate(&t,                                        \
                              (AllocatorCapability)context,              \
                              size,                                      \
                              AllocateWaitRevocationNeeded);             \
    if (!__builtin_cheri_tag_get(ret))                                     \
    {                                                                      \
        ret = NULL;                                                        \
    }                                                                      \
    ret;                                                                   \
})

Implementation of malloc and free to use.

Note that MVM_CONTEXTUAL_FREE needs to accept null pointers as well.

If MVM_USE_SINGLE_RAM_PAGE is set, pointers returned by MVM_CONTEXTUAL_MALLOC must always be within 64kB of MVM_RAM_PAGE_ADDR.

The context passed to these macros is whatever value that the host passes to mvm_restore. It can be any value that fits in a pointer.

Similarly to malloc and calloc, this will only ever block to wait for the quarantine to be processed.

Definition at line 302 of file microvium_port.h.

◆ MVM_DONT_TRUST_BYTECODE

#define MVM_DONT_TRUST_BYTECODE 1

Set to 1 to enable extra validation checks of bytecode while executing.

This is beyond the basic version and CRC checks that are done upon loading, and should only be enabled if you expect bugs in the bytecode compiler.

Definition at line 116 of file microvium_port.h.

◆ MVM_EXPORT

#define MVM_EXPORT __cheri_libcall

All public functions are exported from the library.

Definition at line 286 of file microvium_port.h.

◆ MVM_FATAL_ERROR

#define MVM_FATAL_ERROR	(		vm,
			e )

Value:

panic()

This is invoked when the virtual machine encounters a critical internal error and execution of the VM should halt.

Note that API-level errors are communicated via returned error codes from each of the API functions and will not trigger a fatal error.

Note: if malloc fails, this is considered a fatal error since many embedded systems cannot safely continue when they run out of memory.

If you need to halt the VM without halting the host, consider running the VM in a separate RTOS thread, or using setjmp/longjmp to escape the VM without returning to it. Either way, the VM should NOT be allowed to continue executing after MVM_FATAL_ERROR (control should not return).

Definition at line 210 of file microvium_port.h.

◆ MVM_GAS_COUNTER

#define MVM_GAS_COUNTER

Expose the timeout APIs.

Definition at line 321 of file microvium_port.h.

◆ MVM_INCLUDE_DEBUG_CAPABILITY

#define MVM_INCLUDE_DEBUG_CAPABILITY 0

Set to 1 to compile support for the debug API (mvm_dbg_*).

Definition at line 255 of file microvium_port.h.

◆ MVM_INCLUDE_SNAPSHOT_CAPABILITY

#define MVM_INCLUDE_SNAPSHOT_CAPABILITY 0

Set to 1 to compile in the ability to generate snapshots (mvm_createSnapshot).

Definition at line 250 of file microvium_port.h.

◆ MVM_INT32TOSTRING

#define MVM_INT32TOSTRING	(		buffer,
			i )

Value:

mvm_int_to_string_helper(buffer, i)

mvm_int_to_string_helper

static int mvm_int_to_string_helper(char buffer[12], int32_t value)

Helper for Microvium to convert strings to integers.

Definition microvium_port.h:329

Definition at line 367 of file microvium_port.h.

◆ MVM_LONG_MEM_CMP

#define MVM_LONG_MEM_CMP	(	p1,
		p2,
		size )

Value:

memcmp(p1, p2, size)

Reference to an implementation of memcmp where p1 and p2 are LONG_PTR.

Definition at line 188 of file microvium_port.h.

◆ MVM_LONG_MEM_CPY

#define MVM_LONG_MEM_CPY	(	target,
		source,
		size )

Value:

memcpy(target, source, size)

Reference to an implementation of memcpy where source is a LONG_PTR.

Definition at line 193 of file microvium_port.h.

◆ MVM_LONG_PTR_ADD

#define MVM_LONG_PTR_ADD	(		p,
			s )

Value:

((MVM_LONG_PTR_TYPE)((uint8_t *)p + (ptrdiff_t)s))

MVM_LONG_PTR_TYPE

#define MVM_LONG_PTR_TYPE

A long pointer is a type that can refer to either ROM or RAM.

Definition microvium_port.h:148

Add an offset s in bytes onto a long pointer p.

The result must be a MVM_LONG_PTR_TYPE.

The maximum offset that will be passed is 16-bit.

Offset may be negative

Definition at line 170 of file microvium_port.h.

◆ MVM_LONG_PTR_NEW

#define MVM_LONG_PTR_NEW ( p )

Value:

((MVM_LONG_PTR_TYPE)p)

Convert a normal pointer to a long pointer.

Definition at line 153 of file microvium_port.h.

◆ MVM_LONG_PTR_SUB

#define MVM_LONG_PTR_SUB	(		p2,
			p1 )

Value:

((int16_t)((uint8_t *)p2 - (uint8_t *)p1))

Subtract two long pointers to get an offset.

The result must be a signed 16-bit integer of p2 - p1 (where p2 is the FIRST param).

Definition at line 177 of file microvium_port.h.

◆ MVM_LONG_PTR_TRUNCATE

#define MVM_LONG_PTR_TRUNCATE ( p )

Value:

((void *)p)

Truncate a long pointer to a normal pointer.

This will only be invoked on pointers to VM RAM data.

Definition at line 160 of file microvium_port.h.

◆ MVM_LONG_PTR_TYPE

#define MVM_LONG_PTR_TYPE void *

A long pointer is a type that can refer to either ROM or RAM.

It is not size restricted.

On architectures where bytecode is directly addressable with a normal pointer, this can just be void* (e.g. 32-bit architectures). On architectures where bytecode can be addressed with a special pointer, this might be something like __data20 void* (MSP430). On Harvard architectures such as AVR8 where ROM and RAM are in different address spaces, MVM_LONG_PTR_TYPE can be some integer type such as uint32_t, where you use part of the value to distinguish which address space and part of the value as the actual pointer value.

The chosen representation/encoding of MVM_LONG_PTR_TYPE must be an integer or pointer type, such that 0/NULL represents the null pointer.

Microvium doesn't access data through pointers of this type directly – it does so through macro operations in this port file.

Definition at line 148 of file microvium_port.h.

◆ MVM_MAX_HEAP_SIZE

#define MVM_MAX_HEAP_SIZE 1024

The maximum size of the virtual heap before an MVM_E_OUT_OF_MEMORY error is given.

When the VM reaches this level, it will first try to perform a garbage collection cycle. If a GC cycle does not free enough memory, a fatal MVM_E_OUT_OF_MEMORY error is given.

Note: this is the space in the virtual heap (the amount consumed by allocations in the VM), not the physical space malloc'd from the host, the latter of which can peak at roughly twice the virtual space during a garbage collection cycle in the worst case.

Definition at line 62 of file microvium_port.h.

◆ MVM_NATIVE_POINTER_IS_16_BIT

#define MVM_NATIVE_POINTER_IS_16_BIT 0

Set to 1 if a void* pointer is natively 16-bit (e.g.

if compiling for 16-bit architectures). This allows some optimizations since then a native pointer can fit in a Microvium value slot.

Definition at line 69 of file microvium_port.h.

◆ MVM_POINTER_MAKE_IMMUTABLE

#define MVM_POINTER_MAKE_IMMUTABLE ( ptr )

Value:

__builtin_cheri_perms_and(ptr, CHERI_PERM_GLOBAL | CHERI_PERM_LOAD)

Remove all permissions except load and global.

Definition at line 378 of file microvium_port.h.

◆ MVM_POINTER_SET_BOUNDS

#define MVM_POINTER_SET_BOUNDS	(		ptr,
			bounds )

Value:

__builtin_cheri_bounds_set(ptr, bounds)

Apply bounds to the buffer.

Definition at line 372 of file microvium_port.h.

◆ MVM_PORT_VERSION

#define MVM_PORT_VERSION 1

The version of the port interface that this file is implementing.

Definition at line 28 of file microvium_port.h.

◆ MVM_READ_LONG_PTR_1

#define MVM_READ_LONG_PTR_1 ( lpSource )

Value:

(*((uint8_t *)lpSource))

Definition at line 182 of file microvium_port.h.

◆ MVM_READ_LONG_PTR_2

#define MVM_READ_LONG_PTR_2 ( lpSource )

Value:

(*((uint16_t *)lpSource))

Definition at line 183 of file microvium_port.h.

◆ MVM_SAFE_MODE

#define MVM_SAFE_MODE 0

Set to 1 to enable additional internal consistency checks, or 0 to disable them.

Note that consistency at the API boundary is always checked, regardless of this setting. Consistency checks make the VM significantly bigger and slower, and are really only intended for testing.

Definition at line 109 of file microvium_port.h.

◆ MVM_STACK_SIZE

#define MVM_STACK_SIZE 256

Number of bytes to use for the stack.

Note: the that stack is fixed-size, even though the heap grows dynamically as-needed.

Definition at line 36 of file microvium_port.h.

◆ MVM_SUPPORT_FLOAT

#define MVM_SUPPORT_FLOAT 0

Set to 1 to compile in support for floating point operations (64-bit).

This adds significant cost in smaller devices, but is required if you want the VM to be compliant with the ECMAScript standard.

When float support is disabled, operations on floats will throw.

Definition at line 78 of file microvium_port.h.

◆ MVM_SWITCH

#define MVM_SWITCH	(		tag,
			upper )

Value:

switch (tag)

Definition at line 220 of file microvium_port.h.

◆ MVM_USE_SINGLE_RAM_PAGE

#define MVM_USE_SINGLE_RAM_PAGE 0

On architectures like small ARM MCUs where there is a large address space (e.g.

32-bit) but only a small region of that is used for heap allocations, Microvium is more efficient if you can tell it the high bits of the addresses so it can store the lower 16-bits.

If MVM_USE_SINGLE_RAM_PAGE is set to 1, then MVM_RAM_PAGE_ADDR must be the address of the page.

Definition at line 275 of file microvium_port.h.

◆ MVM_VERY_EXPENSIVE_MEMORY_CHECKS

#define MVM_VERY_EXPENSIVE_MEMORY_CHECKS 0

Not recommended!

Set to 1 to enable extra checks for pointer safety within the engine. In particular, this triggers a GC collection cycle at every new allocation in order to find potential dangling pointer issues, and each GC collection shifts the address space a little to invalidate native pointers early. This option is only intended for testing purposes.

Definition at line 127 of file microvium_port.h.

Function Documentation

◆ crc16()

uint16_t crc16	(	MVM_LONG_PTR_TYPE	lp,
		uint16_t	size )

static

Definition at line 232 of file microvium_port.h.

◆ mvm_int_to_string_helper()

int mvm_int_to_string_helper	(	char	buffer[12],
		int32_t	value )

static

Helper for Microvium to convert strings to integers.

This is used only in the int to string coercion function, so is marked as always inline to ensure that we don't get a function call.

Definition at line 329 of file microvium_port.h.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ MVM_ALL_ERRORS_FATAL

◆ MVM_ALLOCATION_BUCKET_SIZE

◆ MVM_CASE

◆ MVM_CHECK_CRC16_CCITT

◆ MVM_CONTEXTUAL_FREE

◆ MVM_CONTEXTUAL_MALLOC

◆ MVM_DONT_TRUST_BYTECODE

◆ MVM_EXPORT

◆ MVM_FATAL_ERROR

◆ MVM_GAS_COUNTER

◆ MVM_INCLUDE_DEBUG_CAPABILITY

◆ MVM_INCLUDE_SNAPSHOT_CAPABILITY

◆ MVM_INT32TOSTRING

◆ MVM_LONG_MEM_CMP

◆ MVM_LONG_MEM_CPY

◆ MVM_LONG_PTR_ADD

◆ MVM_LONG_PTR_NEW

◆ MVM_LONG_PTR_SUB

◆ MVM_LONG_PTR_TRUNCATE

◆ MVM_LONG_PTR_TYPE

◆ MVM_MAX_HEAP_SIZE

◆ MVM_NATIVE_POINTER_IS_16_BIT

◆ MVM_POINTER_MAKE_IMMUTABLE

◆ MVM_POINTER_SET_BOUNDS

◆ MVM_PORT_VERSION

◆ MVM_READ_LONG_PTR_1

◆ MVM_READ_LONG_PTR_2

◆ MVM_SAFE_MODE

◆ MVM_STACK_SIZE

◆ MVM_SUPPORT_FLOAT

◆ MVM_SWITCH

◆ MVM_USE_SINGLE_RAM_PAGE

◆ MVM_VERY_EXPENSIVE_MEMORY_CHECKS

Function Documentation

◆ crc16()

◆ mvm_int_to_string_helper()