Module Name: src
Committed By: kamil
Date: Sat Apr 15 03:33:05 UTC 2017
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: klua_lock.9 klua_mod_register.9
Log Message:
Add new documentation for klua_mod_register(9) and klua_lock(9)
Lua kernel bindings.
To generate a diff of this commit:
cvs rdiff -u -r1.2121 -r1.2122 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.407 -r1.408 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/klua_lock.9 \
src/share/man/man9/klua_mod_register.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2121 src/distrib/sets/lists/comp/mi:1.2122
--- src/distrib/sets/lists/comp/mi:1.2121 Fri Apr 14 15:20:39 2017
+++ src/distrib/sets/lists/comp/mi Sat Apr 15 03:33:05 2017
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2121 2017/04/14 15:20:39 riastradh Exp $
+# $NetBSD: mi,v 1.2122 2017/04/15 03:33:05 kamil Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -10578,6 +10578,8 @@
./usr/share/man/cat9/kfilter_register.0 comp-sys-catman .cat
./usr/share/man/cat9/kfilter_unregister.0 comp-sys-catman .cat
./usr/share/man/cat9/killproc.0 comp-sys-catman .cat
+./usr/share/man/cat9/klua_lock.0 comp-sys-catman .cat
+./usr/share/man/cat9/klua_mod_register.0 comp-sys-catman .cat
./usr/share/man/cat9/kmem.0 comp-sys-catman .cat
./usr/share/man/cat9/kmem_alloc.0 comp-sys-catman .cat
./usr/share/man/cat9/kmem_asprintf.0 comp-sys-catman .cat
@@ -17892,6 +17894,8 @@
./usr/share/man/html9/kfilter_register.html comp-sys-htmlman html
./usr/share/man/html9/kfilter_unregister.html comp-sys-htmlman html
./usr/share/man/html9/killproc.html comp-sys-htmlman html
+./usr/share/man/html9/klua_lock.html comp-sys-htmlman html
+./usr/share/man/html9/klua_mod_register.html comp-sys-htmlman html
./usr/share/man/html9/kmem.html comp-sys-htmlman html
./usr/share/man/html9/kmem_alloc.html comp-sys-htmlman html
./usr/share/man/html9/kmem_asprintf.html comp-sys-htmlman html
@@ -25358,6 +25362,8 @@
./usr/share/man/man9/kfilter_register.9 comp-sys-man .man
./usr/share/man/man9/kfilter_unregister.9 comp-sys-man .man
./usr/share/man/man9/killproc.9 comp-sys-man .man
+./usr/share/man/man9/klua_lock.9 comp-sys-man .man
+./usr/share/man/man9/klua_mod_register.9 comp-sys-man .man
./usr/share/man/man9/kmem.9 comp-sys-man .man
./usr/share/man/man9/kmem_alloc.9 comp-sys-man .man
./usr/share/man/man9/kmem_asprintf.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.407 src/share/man/man9/Makefile:1.408
--- src/share/man/man9/Makefile:1.407 Thu Apr 6 10:46:52 2017
+++ src/share/man/man9/Makefile Sat Apr 15 03:33:05 2017
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.407 2017/04/06 10:46:52 abhinav Exp $
+# $NetBSD: Makefile,v 1.408 2017/04/15 03:33:05 kamil Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -29,7 +29,7 @@ MAN= accept_filter.9 accf_data.9 accf_ht
in_getifa.9 \
in4_cksum.9 inittodr.9 interrupt_distribute.9 intro.9 ioasic.9 \
ioctl.9 ipkdb.9 ipi.9 isa.9 isapnp.9 itimerfix.9 kauth.9 kcopy.9 \
- kcpuset.9 kernhist.9 kmem.9 kpause.9 \
+ kcpuset.9 kernhist.9 klua_lock.9 klua_mod_register.9 kmem.9 kpause.9 \
kfilter_register.9 knote.9 \
kprintf.9 kthread.9 linedisc.9 lock.9 log.9 ltsleep.9 \
LWP_CACHE_CREDS.9 \
Added files:
Index: src/share/man/man9/klua_lock.9
diff -u /dev/null src/share/man/man9/klua_lock.9:1.1
--- /dev/null Sat Apr 15 03:33:05 2017
+++ src/share/man/man9/klua_lock.9 Sat Apr 15 03:33:05 2017
@@ -0,0 +1,182 @@
+.\" $NetBSD: klua_lock.9,v 1.1 2017/04/15 03:33:05 kamil 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 May 14, 2015
+.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
+to be 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
+.Ft ks_lock
+is used to protect the integrity in cross-thread access to the Lua state.
+The third one
+.Ft ks_user
+points whether the structure was created from the kernel space or userland.
+This parameter is used in the logic of
+.Xr luactl 8 ,
+prohibiting the case of creating a state from kernel and destroying it in
+the userland.
+.Pp
+The kernel Lua API is designed after ther userland Lua API.
+.Ss List of Functions
+.Bl -column "copysignX" "gammaX3XX" "inverse trigonometric funcX"
+.It Sy kernel API Sy userland API 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 cusom 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 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.
+It should be used after prior creation.
+.Pp
+The
+.Fn klua_newstate
+and
+.Fn kluaL_newstate
+functions are used to create and register new kernel Lua state.
+.Fn klua_newstate
+takes 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 and must not
+begin with the
+.Dq _
+character and must be unique for the
+.Xr lua 9
+device.
+The
+.Ft desc
+parameter optionally describes the Lua state with plain text.
+The
+.Ft ipl
+argument is used to define the type of
+.Xr mutex 9
+by the system interrupt priority level.
+.Sh RETURN FUNCTIONS
+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
Index: src/share/man/man9/klua_mod_register.9
diff -u /dev/null src/share/man/man9/klua_mod_register.9:1.1
--- /dev/null Sat Apr 15 03:33:05 2017
+++ src/share/man/man9/klua_mod_register.9 Sat Apr 15 03:33:05 2017
@@ -0,0 +1,113 @@
+.\" $NetBSD: klua_mod_register.9,v 1.1 2017/04/15 03:33:05 kamil 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 May 14, 2015
+.Dt KLUA_MOD_REGISTER 9
+.Os
+.Sh NAME
+.Nm klua_mod_register ,
+.Nm klua_mod_unregister
+.Nd Lua kernel bindings
+.Sh SYNOPSIS
+.In sys/lua.h
+.Ft void
+.Fn klua_mod_register "const char *name" "lua_CFunction open"
+.Ft void
+.Fn klua_mod_unregister "const char *name"
+.Sh DESCRIPTION
+The Lua kernel bindings are designed to provide functionality to Lua scripts
+not available in the language itself, e.g. to access core kernel functionality.
+This mechanism is utilizing the lua_modules functionality.
+.Pp
+The lua_module structure is declared as follows:
+.Bd -literal
+struct lua_module {
+ char mod_name[LUA_MAX_MODNAME];
+ lua_CFunction open;
+ int refcount;
+ LIST_ENTRY(lua_module) mod_next;
+};
+.Ed
+.Pp
+The
+.Ft mod_name
+defines the unique name of a module.
+A C function must use the standard Lua protocol in order to communicate with
+Lua, this is part is maintained with the
+.Ft open
+element in the standard Lua way.
+.Ft refcount
+protects the module from unplogging it when in use.
+The last parameter
+.Ft mod_next
+is used for the standard container
+.Xr LIST 3 .
+.Pp
+The
+.Fn klua_mod_register
+function registers new function available to the
+.Xr lua 9
+device and possible to be used in a Lua code by the
+.Dv require
+directive.
+.Dv require
+might be used by
+.Xr luactl 8
+or by the special meaning of the
+.Dv require
+in the kernel Lua version.
+The
+.Fa name
+parameter is a unique identifier of the kernel Lua module.
+.Fa open
+points to a function used in the C and Lua cooperation,
+defined with the appropriate standard Lua API.
+.Pp
+Once registered a C function must be deregistered with the
+.Fn klua_mod_unregister
+function.
+This function takes as its parameter the unique literal identifier of the
+extending module.
+.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_close 9 ,
+.Xr klua_lock 9 ,
+.Xr klua_newstate 9 ,
+.Xr klua_unlock 9 ,
+.Xr kluaL_newstate 9 ,
+.Xr intro 9lua
+.Sh AUTHORS
+.An Kamil Rytarowski
