1 files changed, 181 insertions, 0 deletions
diff --git a/static/netbsd/man9/klua_lock.9 b/static/netbsd/man9/klua_lock.9
new file mode 100644
index 00000000..4b3a391c
--- /dev/null
+++ b/static/netbsd/man9/klua_lock.9
@@ -0,0 +1,181 @@
+.\"	$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 .