182 lines
5.1 KiB
Groff
182 lines
5.1 KiB
Groff
.\" $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 .
|