Lua Language

Categories:

• XWLUA

  3 minute read  

Modern MCUs have sufficient performance to run interpreted languages. XWOS integrates the Lua language — a lightweight, compact scripting language. The port of Lua in XWOS is called XWLUA. XWLUA has the following features:

• Interactive REPL: an independent thread, users can run Lua functions online through a serial terminal, or run scripts in the file system;
• Multithreading: Lua does not natively support multithreading. XWLUA extends Lua to implement multithreading functionality;
• Lock mechanisms: supports mutex, spinlock, and seqlock;
• Synchronization mechanisms: supports semaphore, condition variable, event flag, signal selector, and thread barrier;
• Driver library: encapsulation of some drivers has been completed.
  • GPIO
  • I2C
  • SPI
  • UART

Running the Lua VM requires sufficient memory and a floating-point unit, so Lua can only be enabled on MCUs with relatively rich resources. Among the reference projects included with XWOS, the following projects have Lua enabled:

• EmbedFireStm32H743XWOS: EmbedFire STM32H743-Pro development board
• AtkApolloH743XWOS: ALIENTEK Apollo STM32H743 development board
• FK429M1XWOS: FANKE STM32F429-M1 development board
• WeActMiniStm32H750XWOS: WeAct MiniSTM32H750 development board

Project Structure

• Project path: xwem/vm/lua
• Directory structure
  • src : Official Lua source code
  • xwlua : XWLUA implementation
    • port.h, port.c, prefix.h, readline.c : Porting code for Lua on XWOS
    • lua.c : Interactive REPL running as an XWOS thread
    • xwvm : VM library: data exchange between VMs
    • xwos : XWOS kernel binding library: including thread, semaphore, condition variable, event flag, signal selector, thread barrier, mutex, spinlock, seqlock, power management
    • xwlib : XWOS basic C function binding library
    • xwds : Xuanwu Device Stack binding library
    • xwxt : Global export table for multithreaded shared data
    • mif.h, mif.c : Xuanwu module startup interface, REPL thread is started here
    • xwmo.mk : Xuanwu module compilation rules

XWLUA Extensions

Multithreading

Native Lua does not support multithreading (the thread type in Lua is not a true thread, but a coroutine). Global variables in the script can only be accessed by the thread executing the script. XWLUA implements multithreading functionality at the C level, with each thread having an independent Lua VM.

Global Export Table

To implement multithreaded shared data, XWLUA implements a global export table (xwxt). Data in the global export table is visible to all threads and is thread-safe. The global export table is also an independent Lua VM.

New Metamethod: __copy

The metamethod __copy() is used to deep copy user data from one VM (global export table, thread) to another VM (thread, global export table). Only userdata can define the __copy() metamethod.

The __copy() metamethod takes two parameters: the first is data, the second is the destination VM, and returns no value. The __copy() metamethod runs in protected mode and can throw errors.

When implementing the __copy() metamethod, if the copy fails, a nil should be pushed into the destination VM.

XWLUA objects all provide the __copy() metamethod.

Object Strong Pointer

XWLUA uses object strong pointers to manage objects in the XWOS kernel (thread, semaphore, condition variable, event flag, signal selector, thread barrier, mutex, spinlock, seqlock). An object strong pointer is a type of userdata. An object strong pointer is an encapsulation of XWOS’s object descriptor. With the help of the Lua VM’s GC mechanism, automatic lifecycle management of objects can be achieved:

• Each time the Lua VM references an object strong pointer, the reference count of the associated object is increased;
• Each time the Lua VM “GC"s an object strong pointer, the reference count of the associated object is decreased;
• When the reference count of the associated object reaches 0, the object’s C-level GC function is executed.

The concept of object strong pointer originates from Lua’s strong reference.

LuaAPI Reference Manual