1.\" $NetBSD: klua_lock.9,v 1.5 2017/04/16 06:36:03 wiz Exp $ 2.\" 3.\" Copyright (c) 2015 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Kamil Rytarowski. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 15, 2017 31.Dt KLUA_LOCK 9 32.Os 33.Sh NAME 34.Nm klua_lock , 35.Nm klua_unlock , 36.Nm klua_close , 37.Nm klua_newstate , 38.Nm kluaL_newstate 39.Nd Lua kernel bindings 40.Sh SYNOPSIS 41.In sys/lua.h 42.Ft void 43.Fn klua_lock "klua_State *K" 44.Ft void 45.Fn klua_unlock "klua_State *K" 46.Ft void 47.Fn klua_close "klua_State *K" 48.Ft "klua_State *" 49.Fo klua_newstate 50.Fa "lua_Alloc f" 51.Fa "void *ud" 52.Fa "const char *name" 53.Fa "const char *desc" 54.Fa "int ipl" 55.Fc 56.Ft "klua_State *" 57.Fn kluaL_newstate "void *ud" "const char *name" "const char *desc" "int ipl" 58.Sh DESCRIPTION 59The Lua kernel bindings are designed to provide functionality to reuse Lua 60scripts maintained by the 61.Xr lua 9 62driver. 63A 64.Xr driver 9 65can be extended with dynamically managed Lua code with optional functionality 66injected from userland with the 67.Xr luactl 8 68utility. 69.Pp 70The kernel structure 71.Ft klua_State 72is defined as follows: 73.Bd -literal 74typedef struct _klua_State { 75 lua_State *L; 76 kmutex_t ks_lock; 77 bool ks_user; /* state created by user (ioctl) */ 78} klua_State; 79.Ed 80.Pp 81The first element 82.Ft L 83of the structure points to a standard Lua state structure. 84The second element 85.Ft ks_lock 86is used to protect integrity during cross-thread access to the Lua state. 87The third element 88.Ft ks_user 89indicates whether the structure was created from the kernel space or userland. 90This parameter is used in the logic of 91.Xr luactl 8 , 92to prohibit the destruction of state from an opposing side. 93Destroying kernel state from userland for example. 94.Pp 95The kernel Lua API is designed after the userland Lua API. 96.Ss List of Functions 97.Bl -column "kluaL_newstateX" "luaL_newstateX" "create a Lua state with custom allocatorX" 98.It Sy kernel API Ta Sy userland API Ta Sy Description 99.It Xr klua_lock 3 Ta lua_lock Ta lock a Lua state 100.It Xr klua_unlock 3 Ta lua_unlock Ta unlock a Lua state 101.It Xr klua_close 3 Ta lua_close Ta destroy a Lua state 102.It Xr klua_newstate 3 Ta lua_newstate Ta create a Lua state with custom allocator 103.It Xr kluaL_newstate 3 Ta luaL_newstate Ta create a Lua state 104.El 105.Pp 106The 107.Fn klua_lock 108and 109.Fn klua_unlock 110functions must be used before and after the use of the 111.Ft klua_State 112structure. 113The Lua state is not thread safe and this is the standard mechanism to overcome 114this limitation. 115These functions are also used by the 116.Xr luactl 8 117utility when accessing 118.Fa K . 119.Pp 120The 121.Fn klua_close 122function destroys the kernel Lua state. 123.Pp 124The 125.Fn klua_newstate 126and 127.Fn kluaL_newstate 128functions are used to create and register a new kernel Lua state. 129.Fn klua_newstate 130takes an additional standard parameter of type 131.Fa f , 132defined by the proper Lua release and an opaque pointer 133.Fa ud 134that Lua passes to the allocator in every call. 135The 136.Ft name 137parameter identifies the kernel Lua state with a text literal. 138It must not begin with the 139.Dq _ 140character and must be unique for the 141.Xr lua 9 142device. 143The 144.Ft desc 145parameter describes the Lua state in plain text. 146The 147.Ft ipl 148argument is used to define the type of 149.Xr mutex 9 150by the system interrupt priority level. 151.Sh RETURN VALUES 152The 153.Fn klua_lock , 154.Fn klua_unlock , 155and 156.Fn klua_close 157functions do not return anything upon completion. 158.Pp 159The 160.Fn klua_newstate 161and 162.Fn kluaL_newstate 163functions return a pointer to newly created to the 164.Ft klua_State 165structure or otherwise in case of failure the 166.Dv NULL 167value. 168.Sh EXAMPLES 169A set of example modules is available in the 170.Pa src/sys/modules/examples 171directory hierarchy. 172.Sh SEE ALSO 173.Xr lua 1 , 174.Xr luac 1 , 175.Xr intro 3lua , 176.Xr lua 4 , 177.Xr klua_mod_register 9 , 178.Xr klua_mod_unregister 9 , 179.Xr intro 9lua 180.Sh AUTHORS 181.An Kamil Rytarowski Aq Mt kamil@NetBSD.org . 182