Lua ported to RIOT

Provides a Lua interpreter for RIOT. More...

Detailed Description

Provides a Lua interpreter for RIOT.

See also
https://github.com/lua/lua
sys_lua

Lua programming language support

Introduction

This package embeds a Lua 5.3 interpreter into RIOT. With a few exceptions, all the APIs mentioned in the official documentation are available in this package too.

Running Lua code.

lua_run.h contains functions that make it easy to setup the interpreter and catch errors in a safe way. The functions from Lua's auxlib can still be used but then you must supply your own allocator and panic routines, load the builtin modules, etc.

To run a chunk of code stored in an array use:

lua_riot_do_buffer(const char *buf, size_t buflen, void *memory,
size_t mem_size, uint16_t modmask, int *retval);

The interpreter will not use the global heap for allocations, instead the user must supply a memory buffer.

To save some memory, some builtin modules can be left out. modmask specifies which builtins to load. Note that if a builtin is not loaded by C code, then it cannot be loaded by Lua code later.

lua_riot_do_buffer takes care of setting up the Lua state, registering a panic handler that does not crash the application, configuring an allocator, loading libraries, etc.

To run a module as a script use lua_riot_do_module. This is roughly equivalent to executing:

require('modulename')

Memory requirements

While generally efficient, the Lua interpreter was not really designed for constrained devices.

A basic interpreter session typically requires about 12kB RAM. The stack but it depends on the functions used (string handling tends to use more stack). It also depends on the platform.

There is currently no easy way to determine the stack needs other than trial and error. Future versions of the package will include instrumentation to this end.

Adding your own modules.

lua_loadlib.c contains two loaders, one for modules written in Lua and another one for C extensions.

An index to the modules is stored in a table (there are two, one for each kind of module). The tables are indexed by the module name and must be sorted in ascending order by this key.

The definitions for the table types are in lua_builtin.h. The loader module contains empty tables, defined as weak symbols so they can be ovewritten by the application. The variables that must be defined are:

Currently, these must be defined manually in the application code. In the future a script will generate this tables, populating them with both RIOT modules and the user modules.

Customizations

The upstream Lua code is used without with the following modifications.

Modifications that affect the API:

Other modifications:

Patches

A version of Lua with the patches applied is available at GitHub It can be downloaded and compiled in desktop computer, and the official test suite can then be run.

Alternatively, the patches in this package can be directly applied to the official distribution.

The updated makefile creates two standalone executables. Tests should be run with the debug executable.

TODO

The following features are missing and will be eventually added:

Files

file  lua_builtin.h
 Definitions for including built-in modules.
 
file  lua_loadlib.h
 Lightweight C interface to the package loader.
 
file  lua_run.h
 Convenience functions for running Lua code.
 
lua_riot_do_buffer
LUALIB_API int lua_riot_do_buffer(const uint8_t *buf, size_t buflen, void *memory, size_t mem_size, uint16_t modmask, int *retval)
Initialize the interpreter and run a user supplied buffer in protected mode.
lua_riot_builtin_lua_table
WEAK const struct lua_riot_builtin_lua *const lua_riot_builtin_lua_table
Table containing all built in pure lua modules.
lua_riot_builtin_c
Entry describing a c lua module built into the application binary.
Definition: lua_builtin.h:60
lua_riot_builtin_lua_table_len
const WEAK size_t lua_riot_builtin_lua_table_len
Number of elements of lua_riot_builtin_lua_table.
lua_riot_builtin_c_table_len
const WEAK size_t lua_riot_builtin_c_table_len
Number of elements of lua_riot_builtin_c_table.
lua_riot_builtin_c_table
WEAK const struct lua_riot_builtin_c *const lua_riot_builtin_c_table
Table containing all built in c lua modules.
lua_riot_builtin_lua
Entry describing a pure lua module whose source is built into the application binary.
Definition: lua_builtin.h:50