LispBM Integration Safety Manual

Document Information

Document Version:	DRAFT
LispBM Version:	0.33.0
Last Updated:	September 2025

Revision History

Future versions of this document will include change logs highlighting modifications to integration requirements, safety considerations, and API changes that may affect existing integrations.

Overview

LispBM is designed to be integrated into larger systems as a sandboxed scripting runtime that interacts with the host system through well-defined, controlled mechanisms. This manual describes how to integrate LispBM correctly to maintain system safety and reliability.

An incorrectly integrated LispBM can compromise sandboxing, cause system instability, memory corruption, or unpredictable behavior. This document provides safety-focused integration guidelines.

Sandboxed runtime system

The LispBM runtime system is designed such that it cannot access or manipulate any memory not explicitly assigned to the runtime system for use as Heap, Arrays memory or image storage.

The programs running on the LispBM runtime system can communicate with the host application through usage of extensions or message-passing (via an events system). Note that extensions are implemented in C and can access, read/write, any memory. The extensions form the interface between the host application and the LispBM applications. The lispBM runtime system can do nothing to ensure that extensions are well behaved in relation to memory.

Integration requirements

LispBM requires the following functionality to be supplied by a HAL or RTOS:

A Thread abstraction.
A Mutex implementation.

If Chibios, FreeRTOS, Zephyr is used, LispBM can use the threading support supplied by these RTOSes. The threading abstraction is used at the border-line between the C application and the LispBM runtime system. The C application will start a thread for running the LispBM runtime system and scheduler.

Mutexes are used on the inside of lispbm (as well as in the C application) to ensure that communication between C and LispBM is safe. As mutexes are used internally, a LispBM mutex abstraction is defined in the platform directory.

The LispBM mutex abstraction consists of:

A type: mutex_t.
Initialization function: bool mutex_init(mutex_t *m).
Lock function: void mutex_lock(mutex_t *m).
Unlock function: void mutex_unlock(mutex_t *m).

Here a FreeRTOS implementation of the LispBM mutex abstraction is shown as an example:

// In header file platform/freertos/include/platform_mutex.h
#include <freertos/FreeRTOS.h>
#include <freertos/semphr.h>
#include <stdbool.h>
 
typedef SemaphoreHandle_t mutex_t;
 
extern bool mutex_init(mutex_t *m);
extern void mutex_lock(mutex_t *m);
extern void mutex_unlock(mutex_t *m);
 
// In source file platform/freertos/src/platform_mutex.c
#include "platform_mutex.h"
 
bool mutex_init(mutex_t *m) {
  *m = xSemaphoreCreateMutex();
  if (*m != NULL)
    return true;
  return false;
}
 
void mutex_lock(mutex_t *m) {
  xSemaphoreTake(*m, portMAX_DELAY);
}
 
void mutex_unlock(mutex_t *m) {
  xSemaphoreGive(*m);
}

Porting LispBM to a different HAL or RTOS, X, requires an implementation of platform/X/include/platform_mutex.h and platform/X/src/platform_mutex.c.

Building the LispBM runtime system

LispBM is compiled into an application by the integrator. While the LispBM runtime system is thoroughly tested, differences in compiler version or libraries could reveal bugs. A final set of integration tests on the system as a whole is strongly recommended.

Practical building instructions can be found here Building LispBM.