Copyright (c) 2015 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Kamil Rytarowski.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd April 15, 2017 .Dt KLUA_LOCK 9 .Os .Sh NAME .Nm klua_lock , .Nm klua_unlock , .Nm klua_close , .Nm klua_newstate , .Nm kluaL_newstate .Nd Lua kernel bindings .Sh SYNOPSIS n sys/lua.h .Ft void .Fn klua_lock "klua_State *K" .Ft void .Fn klua_unlock "klua_State *K" .Ft void .Fn klua_close "klua_State *K" .Ft "klua_State *" .Fo klua_newstate .Fa "lua_Alloc f" .Fa "void *ud" .Fa "const char *name" .Fa "const char *desc" .Fa "int ipl" .Fc .Ft "klua_State *" .Fn kluaL_newstate "void *ud" "const char *name" "const char *desc" "int ipl" .Sh DESCRIPTION The Lua kernel bindings are designed to provide functionality to reuse Lua scripts maintained by the .Xr lua 9 driver. A .Xr driver 9 can be extended with dynamically managed Lua code with optional functionality injected from userland with the .Xr luactl 8 utility.
p The kernel structure .Ft klua_State is defined as follows: d -literal typedef struct _klua_State { lua_State *L; kmutex_t ks_lock; bool ks_user; /* state created by user (ioctl) */ } klua_State; .Ed
p The first element .Ft L of the structure points to a standard Lua state structure. The second element .Ft ks_lock is used to protect integrity during cross-thread access to the Lua state. The third element .Ft ks_user indicates whether the structure was created from the kernel space or user land. This parameter is used in the logic of .Xr luactl 8 , to prohibit the destruction of state from an opposing side. Destroying kernel state from user land for example.
p The kernel Lua API is designed after the user land Lua API. .Ss List of Functions l -column "kluaL_newstateX" "luaL_newstateX" "create a Lua state with custom allocatorX" t Sy kernel API Ta Sy userland API Ta Sy Description t Xr klua_lock 3 Ta lua_lock Ta lock a Lua state t Xr klua_unlock 3 Ta lua_unlock Ta unlock a Lua state t Xr klua_close 3 Ta lua_close Ta destroy a Lua state t Xr klua_newstate 3 Ta lua_newstate Ta create a Lua state with custom allocator t Xr kluaL_newstate 3 Ta luaL_newstate Ta create a Lua state .El
p The .Fn klua_lock and .Fn klua_unlock functions must be used before and after the use of the .Ft 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 .Xr luactl 8 utility when accessing .Fa K .
p The .Fn klua_close function destroys the kernel Lua state.
p The .Fn klua_newstate and .Fn kluaL_newstate functions are used to create and register a new kernel Lua state. .Fn klua_newstate takes an additional standard parameter of type .Fa f , defined by the proper Lua release and an opaque pointer .Fa ud that Lua passes to the allocator in every call. The .Ft name parameter identifies the kernel Lua state with a text literal. It must not begin with the .Dq _ character and must be unique for the .Xr lua 9 device. The .Ft desc parameter describes the Lua state in plain text. The .Ft ipl argument is used to define the type of .Xr mutex 9 by the system interrupt priority level. .Sh RETURN VALUES The .Fn klua_lock , .Fn klua_unlock , and .Fn klua_close functions do not return anything upon completion.
p The .Fn klua_newstate and .Fn kluaL_newstate functions return a pointer to newly created to the .Ft klua_State structure or otherwise in case of failure the .Dv NULL value. .Sh EXAMPLES A set of example modules is available in the
a src/sys/modules/examples directory hierarchy. .Sh SEE ALSO .Xr lua 1 , .Xr luac 1 , .Xr intro 3lua , .Xr lua 4 , .Xr klua_mod_register 9 , .Xr klua_mod_unregister 9 , .Xr intro 9lua .Sh AUTHORS .An Kamil Rytarowski Aq Mt kamil@NetBSD.org .