Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Add new documentation for klua_mod_register(9) and klua_lock(9)
details: https://anonhg.NetBSD.org/src/rev/6a45a7bd1bfa
branches: trunk
changeset: 823181:6a45a7bd1bfa
user: kamil <kamil%NetBSD.org@localhost>
date: Sat Apr 15 03:33:05 2017 +0000
description:
Add new documentation for klua_mod_register(9) and klua_lock(9)
Lua kernel bindings.
diffstat:
distrib/sets/lists/comp/mi | 8 +-
share/man/man9/Makefile | 4 +-
share/man/man9/klua_lock.9 | 182 +++++++++++++++++++++++++++++++++++++
share/man/man9/klua_mod_register.9 | 113 ++++++++++++++++++++++
4 files changed, 304 insertions(+), 3 deletions(-)
diffs (truncated from 357 to 300 lines):
diff -r 7a7800bceda3 -r 6a45a7bd1bfa distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Sat Apr 15 00:35:12 2017 +0000
+++ b/distrib/sets/lists/comp/mi Sat Apr 15 03:33:05 2017 +0000
@@ -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
diff -r 7a7800bceda3 -r 6a45a7bd1bfa share/man/man9/Makefile
--- a/share/man/man9/Makefile Sat Apr 15 00:35:12 2017 +0000
+++ b/share/man/man9/Makefile Sat Apr 15 03:33:05 2017 +0000
@@ -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 @@
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 \
diff -r 7a7800bceda3 -r 6a45a7bd1bfa share/man/man9/klua_lock.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/klua_lock.9 Sat Apr 15 03:33:05 2017 +0000
@@ -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
diff -r 7a7800bceda3 -r 6a45a7bd1bfa share/man/man9/klua_mod_register.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/klua_mod_register.9 Sat Apr 15 03:33:05 2017 +0000
@@ -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
Home |
Main Index |
Thread Index |
Old Index