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 May 14, 2015 .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 to be 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 .Ft ks_lock is used to protect the integrity in cross-thread access to the Lua state. The third one .Ft ks_user points whether the structure was created from the kernel space or userland. This parameter is used in the logic of .Xr luactl 8 , prohibiting the case of creating a state from kernel and destroying it in the userland.
p The kernel Lua API is designed after ther userland Lua API. .Ss List of Functions l -column "copysignX" "gammaX3XX" "inverse trigonometric funcX" t Sy kernel API Sy userland API 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 cusom 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 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. It should be used after prior creation.
p The .Fn klua_newstate and .Fn kluaL_newstate functions are used to create and register new kernel Lua state. .Fn klua_newstate takes 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 and must not begin with the .Dq _ character and must be unique for the .Xr lua 9 device. The .Ft desc parameter optionally describes the Lua state with plain text. The .Ft ipl argument is used to define the type of .Xr mutex 9 by the system interrupt priority level. .Sh RETURN FUNCTIONS 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