KLUA_LOCK(9) Kernel Developer's Manual KLUA_LOCK(9)

klua_lock, klua_unlock, klua_close, klua_newstate, kluaL_newstate — Lua kernel bindings

#include <sys/lua.h>

void
klua_lock(klua_State *K);

void
klua_unlock(klua_State *K);

void
klua_close(klua_State *K);

klua_State *
klua_newstate(lua_Alloc f, void *ud, const char *name, const char *desc, int ipl);

klua_State *
kluaL_newstate(void *ud, const char *name, const char *desc, int ipl);

The Lua kernel bindings are designed to provide functionality to reuse Lua scripts maintained by the lua(9) driver. A driver(9) can be extended with dynamically managed Lua code with optional functionality injected from userland with the luactl(8) utility.

The kernel structure klua_State is defined as follows:

typedef struct _klua_State {
        lua_State       *L;
        kmutex_t         ks_lock;
        bool             ks_user;       /* state created by user (ioctl) */
} klua_State;

The first element L of the structure points to a standard Lua state structure. The second element ks_lock is used to protect integrity during cross-thread access to the Lua state. The third element ks_user indicates whether the structure was created from the kernel space or userland. This parameter is used in the logic of luactl(8), to prohibit the destruction of state from an opposing side. Destroying kernel state from userland for example.

The kernel Lua API is designed after the userland Lua API.

klua_lock(3) lua_lock lock a Lua state
klua_unlock(3) lua_unlock unlock a Lua state
klua_close(3) lua_close destroy a Lua state
klua_newstate(3) lua_newstate create a Lua state with custom allocator
kluaL_newstate(3) luaL_newstate create a Lua state

The () and () functions must be used before and after the use of the klua_State structure. The Lua state is not thread safe and this is the standard mechanism to overcome this limitation. These functions are also used by the luactl(8) utility when accessing K.

The () function destroys the kernel Lua state.

The () and () functions are used to create and register a new kernel Lua state. klua_newstate() takes an additional standard parameter of type f, defined by the proper Lua release and an opaque pointer ud that Lua passes to the allocator in every call. The name parameter identifies the kernel Lua state with a text literal. It must not begin with the “_” character and must be unique for the lua(9) device. The desc parameter describes the Lua state in plain text. The ipl argument is used to define the type of mutex(9) by the system interrupt priority level.

The klua_lock(), klua_unlock(), and klua_close() functions do not return anything upon completion.

The klua_newstate() and kluaL_newstate() functions return a pointer to newly created to the klua_State structure or otherwise in case of failure the NULL value.

A set of example modules is available in the src/sys/modules/examples directory hierarchy.

lua(1), luac(1), intro(3lua), lua(4), klua_mod_register(9), klua_mod_unregister(9), intro(9lua)

Kamil Rytarowski <kamil@NetBSD.org>.

April 15, 2017 NetBSD 11.0