kerf-multikernel 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
kerf/unload/main.py ADDED
@@ -0,0 +1,310 @@
1
+ # Copyright 2025 Multikernel Technologies, Inc.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """
16
+ Kernel unloading subcommand implementation using kexec_file_load syscall with KEXEC_FILE_UNLOAD flag.
17
+ """
18
+
19
+ import ctypes
20
+ import os
21
+ import platform
22
+ import sys
23
+ from pathlib import Path
24
+ from typing import Optional
25
+
26
+ import click
27
+
28
+ from ..models import InstanceState
29
+ from ..utils import get_instance_id_from_name
30
+
31
+
32
+ def _cleanup_load_resources(instance_name: str, _instance_id: int, verbose: bool) -> None:
33
+ """Clean up resources created by kerf load --image."""
34
+ import shutil
35
+
36
+ from ..daxfs import unmount_daxfs, DaxfsError
37
+ from ..metadata import delete_instance_metadata
38
+
39
+ try:
40
+ delete_instance_metadata(instance_name)
41
+ except OSError as e:
42
+ click.echo(f"Warning: Failed to remove instance metadata: {e}", err=True)
43
+
44
+ # Unmount the daxfs image, releasing its memory back to the pool
45
+ try:
46
+ unmount_daxfs(instance_name)
47
+ if verbose:
48
+ click.echo(f"✓ Unmounted daxfs image for '{instance_name}'")
49
+ except DaxfsError as e:
50
+ click.echo(f"Warning: {e}", err=True)
51
+
52
+ # Clean up extracted rootfs
53
+ rootfs_path = Path("/var/lib/kerf/rootfs") / instance_name
54
+ if rootfs_path.exists():
55
+ try:
56
+ shutil.rmtree(rootfs_path)
57
+ if verbose:
58
+ click.echo(f"✓ Cleaned up rootfs: {rootfs_path}")
59
+ except Exception as e:
60
+ if verbose:
61
+ click.echo(f"Warning: Failed to clean up rootfs: {e}", err=True)
62
+
63
+
64
+ # KEXEC flags definitions
65
+ KEXEC_FILE_UNLOAD = 0x00000001
66
+ KEXEC_MULTIKERNEL = 0x00000010
67
+ KEXEC_MK_ID_MASK = 0x0000FFE0
68
+ KEXEC_MK_ID_SHIFT = 5
69
+
70
+
71
+ def KEXEC_MK_ID(id: int) -> int: # pylint: disable=invalid-name
72
+ """Generate KEXEC_MK_ID flag value from kernel ID."""
73
+ return (id << KEXEC_MK_ID_SHIFT) & KEXEC_MK_ID_MASK
74
+
75
+
76
+ # Syscall numbers (architecture-dependent)
77
+ # Same syscall number as kexec_file_load
78
+ # For x86_64: 320, for x86: 320, for ARM64: 294, for ARM: 382
79
+ SYS_KEXEC_FILE_LOAD_X86_64 = 320
80
+ SYS_KEXEC_FILE_LOAD_ARM64 = 294
81
+ SYS_KEXEC_FILE_LOAD_ARM = 382
82
+ SYS_KEXEC_FILE_LOAD_X86 = 320
83
+
84
+
85
+ def get_kexec_file_load_syscall():
86
+ """Get the kexec_file_load syscall number for current architecture."""
87
+ arch = platform.machine().lower()
88
+ if arch in ("x86_64", "amd64"):
89
+ return SYS_KEXEC_FILE_LOAD_X86_64
90
+ if arch in ("aarch64", "arm64"):
91
+ return SYS_KEXEC_FILE_LOAD_ARM64
92
+ if arch.startswith("arm"):
93
+ return SYS_KEXEC_FILE_LOAD_ARM
94
+ if arch in ("i386", "i686", "x86"):
95
+ return SYS_KEXEC_FILE_LOAD_X86
96
+ # Default to x86_64, but warn
97
+ click.echo(
98
+ f"Warning: Unknown architecture '{arch}', assuming x86_64 syscall number", err=True
99
+ )
100
+ return SYS_KEXEC_FILE_LOAD_X86_64
101
+
102
+
103
+ def kexec_file_unload(flags: int, debug: bool = False) -> int:
104
+ libc = ctypes.CDLL(None, use_errno=True)
105
+ syscall_fn = libc.syscall
106
+
107
+ syscall_num = get_kexec_file_load_syscall()
108
+
109
+ # For unload: kernel_fd = -1, initrd_fd = -1, cmdline = NULL
110
+ kernel_fd = -1
111
+ initrd_fd = -1
112
+ cmdline_len = 0
113
+ cmdline_ptr = None
114
+
115
+ # syscall signature: long syscall(long number, ...)
116
+ # kexec_file_load: long kexec_file_load(int kernel_fd, int initrd_fd,
117
+ # unsigned long cmdline_len,
118
+ # const char *cmdline,
119
+ # unsigned long flags)
120
+ syscall_fn.argtypes = [
121
+ ctypes.c_long, # syscall number
122
+ ctypes.c_int, # kernel_fd (-1 for unload)
123
+ ctypes.c_int, # initrd_fd (-1 for unload)
124
+ ctypes.c_ulong, # cmdline_len (0 for unload)
125
+ ctypes.c_char_p, # cmdline (NULL for unload)
126
+ ctypes.c_ulong, # flags
127
+ ]
128
+ syscall_fn.restype = ctypes.c_long
129
+
130
+ if debug:
131
+ click.echo(
132
+ f"DEBUG: syscall_num={syscall_num}, kernel_fd={kernel_fd}, initrd_fd={initrd_fd}, cmdline_len={cmdline_len}, flags=0x{flags:x}",
133
+ err=True,
134
+ )
135
+ click.echo(
136
+ f"DEBUG: KEXEC_FILE_UNLOAD=0x{KEXEC_FILE_UNLOAD:x}, KEXEC_MULTIKERNEL=0x{KEXEC_MULTIKERNEL:x}, KEXEC_MK_ID_MASK=0x{KEXEC_MK_ID_MASK:x}, KEXEC_MK_ID_SHIFT={KEXEC_MK_ID_SHIFT}",
137
+ err=True,
138
+ )
139
+ click.echo("DEBUG: cmdline_ptr=NULL (unload operation)", err=True)
140
+
141
+ result = syscall_fn(syscall_num, kernel_fd, initrd_fd, cmdline_len, cmdline_ptr, flags)
142
+
143
+ if debug:
144
+ click.echo(f"DEBUG: syscall returned: {result}", err=True)
145
+
146
+ if result < 0:
147
+ # Get errno
148
+ errno_value = ctypes.get_errno()
149
+ if errno_value == 0:
150
+ # If errno is 0 but result is negative, use -result as errno
151
+ # This handles cases where the syscall returns -errno directly
152
+ errno_value = -result
153
+ raise OSError(errno_value, os.strerror(errno_value))
154
+
155
+ return result
156
+
157
+
158
+ @click.command(name="unload")
159
+ @click.argument("name", required=False)
160
+ @click.option("--id", type=int, help="Multikernel instance ID to unload (alternative to name)")
161
+ @click.option("--verbose", "-v", is_flag=True, help="Verbose output")
162
+ @click.pass_context
163
+ def unload(ctx: click.Context, name: Optional[str], id: Optional[int], verbose: bool):
164
+ """
165
+ Unload a kernel image from a multikernel instance using kexec_file_load with KEXEC_FILE_UNLOAD flag.
166
+
167
+ This command unloads a previously loaded kernel image from memory for the specified
168
+ multikernel instance. The instance must be in LOADED state (not ACTIVE).
169
+
170
+ Examples:
171
+
172
+ kerf unload web-server
173
+ kerf unload --id=1
174
+ kerf unload --id=1 --verbose
175
+ """
176
+ try:
177
+ if not name and id is None:
178
+ click.echo("Error: Either instance name or --id must be provided", err=True)
179
+ click.echo("Usage: kerf unload <name> or kerf unload --id=<id>", err=True)
180
+ sys.exit(2)
181
+
182
+ instance_name = None
183
+ instance_id = None
184
+
185
+ if name:
186
+ # Use name, convert to ID
187
+ instance_name = name
188
+ instance_id = get_instance_id_from_name(name)
189
+
190
+ if instance_id is None:
191
+ click.echo(f"Error: Instance '{name}' not found", err=True)
192
+ click.echo("Check available instances in /sys/fs/multikernel/instances/", err=True)
193
+ sys.exit(1)
194
+
195
+ if verbose:
196
+ click.echo(f"Instance name: {name} (ID: {instance_id})")
197
+ else:
198
+ # Use ID directly, need to find name for status check
199
+ instance_id = id
200
+
201
+ if instance_id < 1 or instance_id > 511:
202
+ click.echo(f"Error: --id must be between 1 and 511 (got {instance_id})", err=True)
203
+ sys.exit(2)
204
+
205
+ instances_dir = Path("/sys/fs/multikernel/instances")
206
+ if instances_dir.exists():
207
+ for inst_dir in instances_dir.iterdir():
208
+ if inst_dir.is_dir():
209
+ found_id = get_instance_id_from_name(inst_dir.name)
210
+ if found_id == instance_id:
211
+ instance_name = inst_dir.name
212
+ break
213
+
214
+ if not instance_name:
215
+ click.echo(f"Error: Instance with ID {instance_id} not found", err=True)
216
+ click.echo("Check available instances in /sys/fs/multikernel/instances/", err=True)
217
+ sys.exit(1)
218
+
219
+ status_path = Path(f"/sys/fs/multikernel/instances/{instance_name}/status")
220
+ if verbose:
221
+ click.echo(f"Checking instance status for '{instance_name}'...")
222
+ click.echo(f"Status file: {status_path}")
223
+
224
+ if not status_path.exists():
225
+ click.echo(f"Error: Instance '{instance_name}' status file not found", err=True)
226
+ click.echo("Please ensure the instance exists", err=True)
227
+ sys.exit(1)
228
+
229
+ try:
230
+ with open(status_path, "r", encoding="utf-8") as f:
231
+ status = f.read().strip()
232
+
233
+ status_lower = status.lower()
234
+
235
+ if status_lower == InstanceState.ACTIVE.value:
236
+ click.echo(
237
+ f"Error: Cannot unload kernel for instance '{instance_name}' (ID: {instance_id})",
238
+ err=True,
239
+ )
240
+ click.echo(
241
+ "Instance is currently ACTIVE (running). Stop the instance first.", err=True
242
+ )
243
+ sys.exit(1)
244
+ elif status_lower != InstanceState.LOADED.value:
245
+ click.echo(
246
+ f"Error: Cannot unload kernel for instance '{instance_name}' (ID: {instance_id})",
247
+ err=True,
248
+ )
249
+ click.echo(
250
+ f"Current status: '{status}' (expected: '{InstanceState.LOADED.value}')",
251
+ err=True,
252
+ )
253
+ click.echo("Only kernels in LOADED state can be unloaded.", err=True)
254
+ sys.exit(1)
255
+
256
+ if verbose:
257
+ click.echo(f"Instance status: '{status}' (OK to unload)")
258
+ except (OSError, IOError) as e:
259
+ click.echo(f"Error: Failed to read status file: {e}", err=True)
260
+ click.echo("Please ensure the instance exists", err=True)
261
+ sys.exit(1)
262
+
263
+ mk_id_flags = KEXEC_MK_ID(instance_id)
264
+ flags = KEXEC_FILE_UNLOAD | KEXEC_MULTIKERNEL | mk_id_flags
265
+
266
+ if verbose:
267
+ click.echo(f"Unloading kernel for instance '{instance_name}' (ID: {instance_id})...")
268
+ click.echo(
269
+ f"Flags: KEXEC_FILE_UNLOAD=0x{KEXEC_FILE_UNLOAD:x}, KEXEC_MULTIKERNEL=0x{KEXEC_MULTIKERNEL:x}, KEXEC_MK_ID({instance_id})=0x{mk_id_flags:x}, combined=0x{flags:x}"
270
+ )
271
+ click.echo("Calling kexec_file_load syscall with KEXEC_FILE_UNLOAD flag...")
272
+ else:
273
+ click.echo(f"Unloading kernel for instance '{instance_name}' (ID: {instance_id})...")
274
+
275
+ try:
276
+ debug = ctx.obj.get("debug", False) if ctx and ctx.obj else False
277
+ result = kexec_file_unload(flags, debug=debug)
278
+
279
+ if verbose:
280
+ click.echo(f"✓ Kernel unloaded successfully (result: {result})")
281
+ else:
282
+ click.echo("✓ Kernel unloaded successfully")
283
+
284
+ # Clean up resources created by kerf load --image
285
+ _cleanup_load_resources(instance_name, instance_id, verbose)
286
+
287
+ except OSError as e:
288
+ click.echo(f"Error: kexec_file_unload failed: {e}", err=True)
289
+ if e.errno == 1: # EPERM
290
+ click.echo("Note: This operation requires root privileges", err=True)
291
+ elif e.errno == 22: # EINVAL
292
+ click.echo(
293
+ f"Error: Invalid arguments for instance '{instance_name}' (ID: {instance_id})",
294
+ err=True,
295
+ )
296
+ click.echo(
297
+ "The kernel may not support KEXEC_FILE_UNLOAD, or the instance ID is invalid.",
298
+ err=True,
299
+ )
300
+ elif e.errno == 3: # ESRCH
301
+ click.echo("Note: Multikernel instance not found or no kernel loaded.", err=True)
302
+ sys.exit(1)
303
+
304
+ except Exception as e:
305
+ click.echo(f"Unexpected error: {e}", err=True)
306
+ if verbose:
307
+ import traceback
308
+
309
+ traceback.print_exc()
310
+ sys.exit(1)
@@ -0,0 +1,15 @@
1
+ # Copyright 2025 Multikernel Technologies, Inc.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Update kernel instance resources."""