lunatik: replace boolean sleep with context string in runtime()

runtime(script, "softirq") for interrupt context (GFP_ATOMIC, spinlock);
runtime(script) or runtime(script, "process") for process context
(GFP_KERNEL, mutex). Mirrors data.new(size, "single"/"shared") style.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: lneto

README.md

@@ -95,7 +95,7 @@ usage: lunatik [load|unload|reload|status|test|list] [run|spawn|stop <script>]
 * `status`: show which Lunatik kernel modules are currently loaded
 * `test [suite]`: run installed test suites (see [Testing](#testing))
 * `list`: show which runtime environments are currently running
-* `run`: create a new runtime environment to run the script `/lib/modules/lua/<script>.lua`
+* `run [softirq]`: create a new runtime environment to run the script `/lib/modules/lua/<script>.lua`; pass `softirq` for hooks that fire in atomic context (netfilter, XDP)
 * `spawn`: create a new runtime environment and spawn a thread to run the script `/lib/modules/lua/<script>.lua`
 * `stop`: stop the runtime environment created to run the script `<script>`
 * `default`: start a _REPL (Read–Eval–Print Loop)_
@@ -320,7 +320,7 @@ sudo make btf_install                        # needed to export the 'bpf_luaxdp_
 sudo make examples_install                   # installs examples
 make ebpf                                    # builds the XDP/eBPF program
 sudo make ebpf_install                       # installs the XDP/eBPF program
-sudo lunatik run examples/filter/sni false   # runs the Lua kernel script
+sudo lunatik run examples/filter/sni softirq   # runs the Lua kernel script
 sudo xdp-loader load -m skb <ifname> https.o # loads the XDP/eBPF program
 ```
 
@@ -353,7 +353,7 @@ This script drops any outbound DNS packet with question matching the blacklist p
 
 ```
 sudo make examples_install              # installs examples
-sudo lunatik run examples/dnsblock/nf_dnsblock false	# runs the Lua kernel script
+sudo lunatik run examples/dnsblock/nf_dnsblock softirq	# runs the Lua kernel script
 ```
 
 ### dnsdoctor
@@ -372,7 +372,7 @@ examples/dnsdoctor/setup.sh             # sets up the environment
 dig lunatik.com
 
 # run the Lua kernel script
-sudo lunatik run examples/dnsdoctor/nf_dnsdoctor false
+sudo lunatik run examples/dnsdoctor/nf_dnsdoctor softirq
 
 # test the setup, a response with IP 10.1.2.3 should be returned
 dig lunatik.com
@@ -434,7 +434,7 @@ It supports gestures: swiping right locks the mouse, and swiping left unlocks it
 
 ```
 sudo make examples_install 			# installs examples
-sudo lunatik run examples/gesture false 	# runs gesture
+sudo lunatik run examples/gesture softirq 	# runs gesture
 # In QEMU window:
 # Drag right to lock the mouse
 # Drag left to unlock the mouse
@@ -450,7 +450,7 @@ It fixes the report descriptor for the device (`0x2717`:`0x5014`).
 
 ```
 sudo make examples_install 		# installs examples
-sudo lunatik run examples/xiaomi false 	# runs xiaomi driver
+sudo lunatik run examples/xiaomi softirq 	# runs xiaomi driver
 ```
 
 Then insert the Xiaomi Silent Mouse with bluetooth mode on and it should work properly.

bin/lunatik

@@ -157,7 +157,7 @@ if #arg >= 1 then
 		os.exit(false)
 	end
 	ensure_loaded()
-	local parm  = arg[3] and ("," .. arg[3]) or ""
+	local parm  = arg[3] and (', "' .. arg[3] .. '"') or ""
 	local ret   = token == "list" and "return" or ""
 	local chunk = string.format("%s lunatik.runner.%s('%s'%s)", ret, token, script, parm)
 	print(dostring(chunk))

examples/tcpreject/setup.sh

@@ -53,7 +53,7 @@ nft add rule ip6 tcpreject forward \
 	ip6 daddr $DNS6 tcp dport 443 mark set $MARK
 
 # load the Lua hook
-lunatik run examples/tcpreject/nf_tcpreject false
+lunatik run examples/tcpreject/nf_tcpreject softirq
 
 echo "setup done"
 echo "test IPv4: ip netns exec $NETNS curl --connect-timeout 2 https://$DNS4"

lib/lunatik/runner.lua

@@ -1,5 +1,5 @@
 --
--- SPDX-FileCopyrightText: (c) 2023-2024 Ring Zero Desenvolvimento de Software LTDA
+-- SPDX-FileCopyrightText: (c) 2023-2026 Ring Zero Desenvolvimento de Software LTDA
 -- SPDX-License-Identifier: MIT OR GPL-2.0-only
 --
 
@@ -32,7 +32,7 @@ end
 -- Creates a new Lunatik runtime for the given script and registers it.
 -- Throws an error if a script with the same name is already running.
 -- @tparam string script The path or name of the Lua script to run. The ".lua" extension will be trimmed.
--- @param ... Additional arguments to pass to the script's main function.
+-- @tparam[opt] string context Execution context: `"process"` (default) or `"softirq"` (for netfilter/XDP hooks).
 -- @treturn table The created Lunatik runtime object.
 -- @raise error if the script is already running.
 function runner.run(script, ...)
@@ -50,7 +50,6 @@ end
 -- to execute the runtime. The thread is named based on the script's filename.
 -- The spawned script is expected to return a function, which will then be executed in the new thread.
 -- @tparam string script The path or name of the Lua script to spawn.
--- @param ... Additional arguments to pass to the script's main function.
 -- @treturn userdata The kernel thread object.
 function runner.spawn(script, ...)
 	local runtime = runner.run(script, ...)
@@ -91,8 +90,6 @@ function runner.list()
 	rcu.map(env.runtimes, function (script)
 		table.insert(list, script)
 	end)
-	-- The original code `table.concat(list, ', ')` correctly returns an empty string
-	-- if `list` is empty, so no change to the code logic is needed or made here.
 	return table.concat(list, ', ')
 end
 

lunatik_core.c

@@ -51,13 +51,7 @@ static inline void lunatik_setversion(lua_State *L)
 	(((f) == GFP_ATOMIC || (n) <= PAGE_SIZE) && (!is_vmalloc_addr(p) || (p) == NULL))
 
 /***
-* Represents a Lunatik runtime environment.
-* This is a userdata object returned by `lunatik.runtime()`. It encapsulates an
-* isolated Lua state running within the Linux kernel. Each runtime can be
-* configured as sleepable (allowing blocking operations, using `GFP_KERNEL`
-* for allocations and mutexes for synchronization) or non-sleepable/atomic
-* (prohibiting blocking operations, using `GFP_ATOMIC` for allocations and
-* spinlocks for synchronization).
+* Isolated Lua state running within the Linux kernel.
 * @type runtime
 */
 static void *lunatik_alloc(void *ud, void *optr, size_t osize, size_t nsize)
@@ -306,33 +300,22 @@ int lunatik_runtime(lunatik_object_t **pruntime, const char *script, lunatik_opt
 EXPORT_SYMBOL(lunatik_runtime);
 
 /***
-* Creates and starts a new Lunatik runtime environment.
-* A Lunatik runtime is an isolated Lua state that can execute Lua scripts
-* within the kernel. Each runtime operates independently.
-*
-* The userdata object returned by `lunatik.runtime()` encapsulates an
-* isolated Lua state running within the Linux kernel. Each runtime can be
-* configured as sleepable (allowing blocking operations, using `GFP_KERNEL`
-* for allocations and mutexes for synchronization) or non-sleepable/atomic
-* (prohibiting blocking operations, using `GFP_ATOMIC` for allocations and
-* spinlocks for synchronization).
-
+* Creates a new Lunatik runtime executing the given script.
 * @function runtime
-* @tparam string script The name of the Lua script to load and execute (e.g., "myscript").
-*   The system will look for "myscript.lua" in the Lua root path.
-* @tparam[opt=true] boolean sleep If `true` (default),
-*   the runtime can sleep (e.g., for I/O operations) and uses `GFP_KERNEL` for allocations.
-*   If `false`, the runtime operates in an atomic context, cannot sleep, and uses `GFP_ATOMIC` for allocations.
-*   This is crucial for runtimes used in contexts that cannot sleep, like Netfilter hooks.
-* @treturn runtime A Lunatik runtime object. This object can be used to interact with the runtime, for example,
-*   to resume it if it yields or to stop it.
-* @raise Error if the Lua state or runtime cannot be allocated, or if the script fails to load or execute.
+* @tparam string script script name (e.g., `"mymod"` loads `/lib/modules/lua/mymod.lua`)
+* @tparam[opt="process"] string context execution context: `"process"` (sleepable,
+*   GFP\_KERNEL, mutex) or `"softirq"` (atomic, GFP\_ATOMIC, spinlock).
+*   Use `"softirq"` for hooks that fire in interrupt context (netfilter, XDP).
+* @treturn runtime
+* @raise if allocation fails or the script errors on load
 * @within lunatik
 */
 static int lunatik_lruntime(lua_State *L)
 {
+	static const char *const contexts[] = {"process", "softirq", NULL};
 	const char *script = luaL_checkstring(L, 1);
-	lunatik_opt_t opt = (lua_gettop(L) >= 2 && !lua_toboolean(L, 2)) ? LUNATIK_OPT_SOFTIRQ : LUNATIK_OPT_NONE;
+	int context = luaL_checkoption(L, 2, "process", contexts);
+	lunatik_opt_t opt = context == 1 ? LUNATIK_OPT_SOFTIRQ : LUNATIK_OPT_NONE;
 
 	lunatik_object_t **pruntime = lunatik_newpobject(L, 1);
 	if (lunatik_newruntime(pruntime, L, script, opt) != 0)

tests/runtime/opt_guards.sh

@@ -22,13 +22,7 @@ ktap_plan 1
 
 mark_dmesg
 
-output=$(lunatik run "$SCRIPT")
-if echo "$output" | grep -qE "\.lua:[0-9]+:"; then
-	ktap_fail "Lua error in script"
-	echo "# $output"
-	ktap_totals
-	exit 1
-fi
+run_script "$SCRIPT"
 
 check_dmesg || { ktap_totals; exit 1; }
 ktap_pass "opt guards: SINGLE rejected, MONITOR/NONE accepted"

tests/runtime/opt_skb_single.sh

@@ -30,7 +30,8 @@ cat /sys/module/$MODULE/refcnt > /dev/null 2>&1 || {
 
 mark_dmesg
 
-lunatik run "$SCRIPT" false
+run_script "$SCRIPT" softirq
+
 ping -c 1 -W 1 127.0.0.1 > /dev/null 2>&1 || true
 
 check_dmesg || { ktap_totals; exit 1; }

tests/runtime/refcnt_leak.sh

@@ -33,7 +33,7 @@ mark_dmesg
 
 # run the script in a non-sleepable runtime (required for netfilter hooks);
 # it is expected to fail — ignore the error
-lunatik run "$SCRIPT" false 2>/dev/null || true
+lunatik run "$SCRIPT" softirq 2>/dev/null || true
 
 check_dmesg || { ktap_totals; exit 1; }