.\"	$NetBSD: klua_lock.9,v 1.5 2017/04/16 06:36:03 wiz Exp $
.\"
.\" 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
.In 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.
.Pp
The kernel structure
.Ft klua_State
is defined as follows:
.Bd -literal
typedef struct _klua_State {
        lua_State       *L;
        kmutex_t         ks_lock;
        bool             ks_user;       /* state created by user (ioctl) */
} klua_State;
.Ed
.Pp
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 userland.
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 userland for example.
.Pp
The kernel Lua API is designed after the userland Lua API.
.Ss List of Functions
.Bl -column "kluaL_newstateX" "luaL_newstateX" "create a Lua state with custom allocatorX"
.It Sy kernel API Ta Sy userland API Ta Sy Description
.It Xr klua_lock 3 Ta lua_lock Ta lock a Lua state
.It Xr klua_unlock 3 Ta lua_unlock Ta unlock a Lua state
.It Xr klua_close 3 Ta lua_close Ta destroy a Lua state
.It Xr klua_newstate 3 Ta lua_newstate Ta create a Lua state with custom allocator
.It Xr kluaL_newstate 3 Ta luaL_newstate Ta create a Lua state
.El
.Pp
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 .
.Pp
The
.Fn klua_close
function destroys the kernel Lua state.
.Pp
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.
.Pp
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
.Pa 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 .