1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
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 .
|
