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/__init__.py ADDED
@@ -0,0 +1,74 @@
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
+ kerf: Multikernel Management System
17
+
18
+ A comprehensive multikernel management system designed to orchestrate
19
+ and manage multiple kernel instances on a single host.
20
+ """
21
+
22
+ __version__ = "0.1.0"
23
+ __author__ = "Cong Wang"
24
+
25
+ # Export main runtime components for easy access
26
+ from .runtime import DeviceTreeManager
27
+ from .baseline import BaselineManager
28
+ from .dtc.overlay import OverlayGenerator
29
+ from .models import InstanceState
30
+ from .exceptions import (
31
+ KerfError,
32
+ ValidationError,
33
+ ParseError,
34
+ ResourceConflictError,
35
+ ResourceExhaustionError,
36
+ InvalidReferenceError,
37
+ KernelInterfaceError,
38
+ ResourceError,
39
+ )
40
+ from .resources import (
41
+ get_available_cpus,
42
+ get_allocated_cpus,
43
+ get_allocated_memory_regions,
44
+ find_available_memory_base,
45
+ validate_cpu_allocation,
46
+ validate_memory_allocation,
47
+ find_next_instance_id,
48
+ )
49
+
50
+ __all__ = [
51
+ # Core classes
52
+ "DeviceTreeManager",
53
+ "BaselineManager",
54
+ "OverlayGenerator",
55
+ # Models
56
+ "InstanceState",
57
+ # Exceptions
58
+ "KerfError",
59
+ "ValidationError",
60
+ "ParseError",
61
+ "ResourceConflictError",
62
+ "ResourceExhaustionError",
63
+ "InvalidReferenceError",
64
+ "KernelInterfaceError",
65
+ "ResourceError",
66
+ # Resource utilities
67
+ "get_available_cpus",
68
+ "get_allocated_cpus",
69
+ "get_allocated_memory_regions",
70
+ "find_available_memory_base",
71
+ "validate_cpu_allocation",
72
+ "validate_memory_allocation",
73
+ "find_next_instance_id",
74
+ ]
kerf/baseline.py ADDED
@@ -0,0 +1,187 @@
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
+ Baseline device tree management.
17
+
18
+ This module provides the BaselineManager class for managing the baseline device tree,
19
+ which contains only hardware resources and is set during system initialization.
20
+ """
21
+
22
+ import os
23
+ from pathlib import Path
24
+ from typing import Optional
25
+
26
+ from .dtc.parser import DeviceTreeParser
27
+ from .dtc.extractor import InstanceExtractor
28
+ from .dtc.validator import MultikernelValidator
29
+ from .models import GlobalDeviceTree
30
+ from .exceptions import ValidationError, ParseError, KernelInterfaceError
31
+
32
+
33
+ class BaselineManager:
34
+ """
35
+ Manages root device tree in kernel.
36
+
37
+ The root device_tree path serves dual purposes:
38
+ - Writing (via write_baseline): Used during initialization to write a
39
+ resources-only baseline. Must contain only hardware resources, no instances.
40
+ - Reading (via read_baseline): Returns complete current state including
41
+ both resources and instances. The kernel keeps this up-to-date by
42
+ automatically merging all applied overlays.
43
+
44
+ Attributes:
45
+ baseline_path: Path to root device tree in kernel
46
+ parser: DeviceTreeParser instance for reading state
47
+ extractor: InstanceExtractor instance for generating DTB
48
+ validator: MultikernelValidator instance for validation
49
+ """
50
+
51
+ DEFAULT_BASELINE_PATH = "/sys/fs/multikernel/device_tree"
52
+
53
+ def __init__(self, baseline_path: Optional[str] = None):
54
+ """
55
+ Initialize BaselineManager.
56
+
57
+ Args:
58
+ baseline_path: Path to baseline device tree. Defaults to
59
+ /sys/fs/multikernel/device_tree
60
+ """
61
+ self.baseline_path = Path(baseline_path or self.DEFAULT_BASELINE_PATH)
62
+
63
+ self.parser = DeviceTreeParser()
64
+ self.extractor = InstanceExtractor()
65
+ self.validator = MultikernelValidator()
66
+
67
+ def validate_baseline(self, tree: GlobalDeviceTree) -> None:
68
+ """
69
+ Validate that tree is a valid baseline (resources only, no instances).
70
+
71
+ Args:
72
+ tree: GlobalDeviceTree to validate
73
+
74
+ Raises:
75
+ ValidationError: If tree is not a valid baseline
76
+ """
77
+ # Baseline must not contain instances
78
+ if tree.instances:
79
+ instance_names = ", ".join(tree.instances.keys())
80
+ raise ValidationError(
81
+ f"Baseline device tree must not contain instances. "
82
+ f"Found instances: {instance_names}. "
83
+ f"Instances should be created via overlays using 'kerf create'."
84
+ )
85
+
86
+ # Baseline must contain resources
87
+ if not tree.hardware:
88
+ raise ValidationError("Baseline device tree must contain hardware resources section.")
89
+
90
+ # Validate resources structure
91
+ if not tree.hardware.cpus:
92
+ raise ValidationError("Baseline must contain CPU allocation information")
93
+
94
+ if not tree.hardware.memory:
95
+ raise ValidationError("Baseline must contain memory allocation information")
96
+
97
+ def write_baseline(self, tree: GlobalDeviceTree) -> None:
98
+ """
99
+ Write baseline device tree to kernel.
100
+
101
+ Validates that the tree contains only resources (no instances) before writing.
102
+ This is used for initial system setup via 'kerf init'.
103
+
104
+ Args:
105
+ tree: GlobalDeviceTree containing only resources (no instances)
106
+
107
+ Raises:
108
+ ValidationError: If tree contains instances or invalid resources
109
+ KernelInterfaceError: If write operation fails
110
+ """
111
+ # Validate baseline structure (no instances)
112
+ self.validate_baseline(tree)
113
+
114
+ # Validate resources are valid
115
+ validation_result = self.validator.validate(tree)
116
+ if not validation_result.is_valid:
117
+ error_msg = "Cannot write invalid baseline:\n"
118
+ error_msg += "\n".join(f" - {err}" for err in validation_result.errors)
119
+ raise ValidationError(error_msg)
120
+
121
+ # Generate DTB from model
122
+ try:
123
+ dtb_data = self.extractor.generate_global_dtb(tree)
124
+ except Exception as e:
125
+ raise KernelInterfaceError(f"Failed to generate baseline device tree blob: {e}") from e
126
+
127
+ # The kernfs write operation is handled atomically by the kernel
128
+ try:
129
+ with open(self.baseline_path, "wb") as f:
130
+ f.write(dtb_data)
131
+ f.flush()
132
+ os.fsync(f.fileno())
133
+
134
+ if not self.baseline_path.exists():
135
+ raise KernelInterfaceError(
136
+ f"Baseline DTB write completed but file does not exist at "
137
+ f"{self.baseline_path}. "
138
+ "Kernel may have rejected the write operation."
139
+ )
140
+ file_size = self.baseline_path.stat().st_size
141
+ if file_size == 0:
142
+ raise KernelInterfaceError(
143
+ "Baseline DTB written but file is empty. "
144
+ "Kernel may have rejected the DTB format."
145
+ )
146
+
147
+ except OSError as e:
148
+ raise KernelInterfaceError(
149
+ f"Failed to write baseline to {self.baseline_path}: {e}"
150
+ ) from e
151
+
152
+ def read_baseline(self) -> GlobalDeviceTree:
153
+ """
154
+ Read root device tree from kernel.
155
+
156
+ Returns:
157
+ GlobalDeviceTree model representing current complete state
158
+
159
+ Raises:
160
+ KernelInterfaceError: If kernel interface is inaccessible
161
+ ParseError: If device tree cannot be parsed
162
+ """
163
+ try:
164
+ if not self.baseline_path.exists():
165
+ raise KernelInterfaceError(
166
+ f"Root device tree not found: {self.baseline_path}. "
167
+ "Initialize it first with 'kerf init'."
168
+ )
169
+
170
+ with open(self.baseline_path, "rb") as f:
171
+ dtb_data = f.read()
172
+
173
+ if not dtb_data:
174
+ raise KernelInterfaceError(
175
+ "Root device tree is empty. Initialize it first with 'kerf init'."
176
+ )
177
+
178
+ tree = self.parser.parse_dtb_from_bytes(dtb_data)
179
+
180
+ return tree
181
+
182
+ except OSError as e:
183
+ raise KernelInterfaceError(
184
+ f"Failed to read root device tree from {self.baseline_path}: {e}"
185
+ ) from e
186
+ except ParseError as e:
187
+ raise ParseError(f"Failed to parse root device tree: {e}") from e
kerf/cli.py ADDED
@@ -0,0 +1,56 @@
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
+ Command-line interface for kerf.
17
+ """
18
+
19
+ import click
20
+ from .load.main import load
21
+ from .init.main import init
22
+ from .create.main import create
23
+ from .update.main import update
24
+ from .exec.main import exec_cmd
25
+ from .kill.main import kill_cmd
26
+ from .unload.main import unload
27
+ from .delete.main import delete
28
+ from .show.main import show
29
+ from .console.main import console
30
+
31
+
32
+ @click.group()
33
+ @click.version_option(version="0.1.0", prog_name="kerf")
34
+ @click.option("--debug", is_flag=True, help="Enable debug mode")
35
+ @click.pass_context
36
+ def main(ctx, debug):
37
+ """kerf: Multikernel Management System - Device Tree Foundation."""
38
+ ctx.ensure_object(dict)
39
+ ctx.obj["debug"] = debug
40
+
41
+
42
+ # Add subcommands
43
+ main.add_command(init)
44
+ main.add_command(load)
45
+ main.add_command(create)
46
+ main.add_command(update)
47
+ main.add_command(exec_cmd)
48
+ main.add_command(kill_cmd)
49
+ main.add_command(unload)
50
+ main.add_command(delete)
51
+ main.add_command(show)
52
+ main.add_command(console)
53
+
54
+
55
+ if __name__ == "__main__":
56
+ main()
@@ -0,0 +1,21 @@
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
+ Console attachment subcommand implementation.
17
+ """
18
+
19
+ from .main import console, run_console
20
+
21
+ __all__ = ["console", "run_console"]
kerf/console/main.py ADDED
@@ -0,0 +1,252 @@
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
+ Console attachment subcommand implementation for mktty device.
17
+ """
18
+
19
+ import os
20
+ import select
21
+ import sys
22
+ import termios
23
+ import tty
24
+ from pathlib import Path
25
+ from typing import Optional
26
+
27
+ import click
28
+
29
+ from ..models import InstanceState
30
+ from ..utils import get_instance_id_from_name, get_instance_name_from_id, get_instance_status
31
+
32
+
33
+ MKTTY_DEVICE = "/dev/mktty"
34
+ CTRL_CLOSE_BRACKET = 0x1D # Ctrl+]
35
+
36
+
37
+ def run_console(instance_id: int, instance_name: str, verbose: bool = False) -> int: # pylint: disable=unused-argument
38
+ """
39
+ Attach to a running instance's console via mktty device.
40
+
41
+ Args:
42
+ instance_id: The instance ID to attach to
43
+ instance_name: The instance name (for display purposes)
44
+ verbose: Enable verbose output
45
+
46
+ Returns:
47
+ 0 on success, non-zero on error
48
+ """
49
+ # Check if mktty device exists
50
+ if not Path(MKTTY_DEVICE).exists():
51
+ click.echo(f"Error: Console device {MKTTY_DEVICE} not found", err=True)
52
+ click.echo("Make sure the mktty kernel module is loaded", err=True)
53
+ return 1
54
+
55
+ # Check if stdin is a tty
56
+ if not sys.stdin.isatty():
57
+ click.echo("Error: stdin is not a terminal", err=True)
58
+ return 1
59
+
60
+ click.echo(f"Connecting to console for instance '{instance_name}' (ID: {instance_id})...")
61
+ click.echo("Escape sequence: Ctrl+] followed by . to detach")
62
+ click.echo("")
63
+
64
+ # Open mktty device
65
+ try:
66
+ mktty_fd = os.open(MKTTY_DEVICE, os.O_RDWR)
67
+ except OSError as e:
68
+ click.echo(f"Error: Failed to open {MKTTY_DEVICE}: {e}", err=True)
69
+ if e.errno == 13: # EACCES
70
+ click.echo("Note: This operation may require root privileges", err=True)
71
+ return 1
72
+
73
+ try:
74
+ # Write instance ID to mktty device to initiate connection
75
+ instance_id_str = f"{instance_id}\n"
76
+ os.write(mktty_fd, instance_id_str.encode("utf-8"))
77
+
78
+ # Save terminal settings
79
+ stdin_fd = sys.stdin.fileno()
80
+ stdout_fd = sys.stdout.fileno()
81
+ old_settings = termios.tcgetattr(stdin_fd)
82
+
83
+ try:
84
+ # Enter raw mode
85
+ tty.setraw(stdin_fd)
86
+
87
+ # State for detach sequence detection
88
+ saw_ctrl_bracket = False
89
+ idle_polls = 0
90
+
91
+ # I/O loop
92
+ while True:
93
+ readable, _, _ = select.select([stdin_fd, mktty_fd], [], [], 0.1)
94
+
95
+ if not readable:
96
+ # Idle: periodically check that the instance is still
97
+ # active so the console exits when the spawn halts.
98
+ idle_polls += 1
99
+ if idle_polls >= 10:
100
+ idle_polls = 0
101
+ status = get_instance_status(instance_name)
102
+ if status is None or status.lower() != InstanceState.ACTIVE.value:
103
+ os.write(
104
+ stdout_fd,
105
+ f"\r\nInstance '{instance_name}' is no longer active "
106
+ f"(status: {status}).\r\n".encode("utf-8"),
107
+ )
108
+ return 0
109
+ continue
110
+
111
+ idle_polls = 0
112
+ for fd in readable:
113
+ if fd == stdin_fd:
114
+ # Read from stdin
115
+ data = os.read(stdin_fd, 1)
116
+ if not data:
117
+ # EOF on stdin
118
+ return 0
119
+
120
+ byte = data[0]
121
+
122
+ # Check for detach sequence: Ctrl+] followed by .
123
+ if saw_ctrl_bracket:
124
+ if byte == ord('.'):
125
+ # Detach sequence complete
126
+ return 0
127
+ # Not a detach sequence, send the buffered Ctrl+]
128
+ os.write(mktty_fd, bytes([CTRL_CLOSE_BRACKET]))
129
+ saw_ctrl_bracket = False
130
+ # Fall through to send current byte
131
+
132
+ if byte == CTRL_CLOSE_BRACKET:
133
+ # Start of potential detach sequence
134
+ saw_ctrl_bracket = True
135
+ else:
136
+ # Send to mktty device
137
+ os.write(mktty_fd, data)
138
+
139
+ elif fd == mktty_fd:
140
+ # Read from mktty device
141
+ try:
142
+ data = os.read(mktty_fd, 4096)
143
+ if data:
144
+ # Translate \n to \r\n for proper terminal display
145
+ # in raw mode (kernel outputs \n, terminal needs \r\n)
146
+ # First normalize any existing \r\n to \n, then convert
147
+ data = data.replace(b'\r\n', b'\n').replace(b'\n', b'\r\n')
148
+ os.write(stdout_fd, data)
149
+ except OSError:
150
+ # Device closed or error
151
+ return 0
152
+
153
+ finally:
154
+ # Restore terminal settings
155
+ termios.tcsetattr(stdin_fd, termios.TCSADRAIN, old_settings)
156
+ click.echo("")
157
+ click.echo("Disconnected from console.")
158
+
159
+ finally:
160
+ os.close(mktty_fd)
161
+
162
+ return 0
163
+
164
+
165
+ @click.command(name="console")
166
+ @click.argument("name", required=False)
167
+ @click.option("--id", type=int, help="Instance ID (alternative to name)")
168
+ @click.option("--verbose", "-v", is_flag=True, help="Verbose output")
169
+ def console(name: Optional[str], id: Optional[int], verbose: bool):
170
+ """
171
+ Attach to a running instance's console.
172
+
173
+ Connect to the console of a running multikernel instance via the mktty
174
+ device. All input including Ctrl+C is passed through to the spawn kernel.
175
+
176
+ To detach from the console, press Ctrl+] followed by . (period).
177
+
178
+ Examples:
179
+
180
+ kerf console web-server
181
+ kerf console --id=1
182
+ """
183
+ try:
184
+ if not name and id is None:
185
+ click.echo("Error: Either instance name or --id must be provided", err=True)
186
+ click.echo("Usage: kerf console <name> or kerf console --id=<id>", err=True)
187
+ sys.exit(2)
188
+
189
+ instance_name = None
190
+ instance_id = None
191
+
192
+ if name:
193
+ # Use name, convert to ID
194
+ instance_name = name
195
+ instance_id = get_instance_id_from_name(name)
196
+
197
+ if instance_id is None:
198
+ click.echo(f"Error: Instance '{name}' not found", err=True)
199
+ click.echo("Check available instances in /sys/fs/multikernel/instances/", err=True)
200
+ sys.exit(1)
201
+
202
+ if verbose:
203
+ click.echo(f"Instance name: {name} (ID: {instance_id})")
204
+ else:
205
+ # Use ID directly, need to find name
206
+ instance_id = id
207
+
208
+ if instance_id < 1 or instance_id > 511:
209
+ click.echo(f"Error: --id must be between 1 and 511 (got {instance_id})", err=True)
210
+ sys.exit(2)
211
+
212
+ instance_name = get_instance_name_from_id(instance_id)
213
+ if not instance_name:
214
+ click.echo(f"Error: Instance with ID {instance_id} not found", err=True)
215
+ click.echo("Check available instances in /sys/fs/multikernel/instances/", err=True)
216
+ sys.exit(1)
217
+
218
+ if verbose:
219
+ click.echo(f"Instance name: {instance_name} (ID: {instance_id})")
220
+
221
+ # Check instance status - must be active
222
+ status = get_instance_status(instance_name)
223
+ if status is None:
224
+ click.echo(f"Error: Failed to read status for instance '{instance_name}'", err=True)
225
+ sys.exit(1)
226
+
227
+ if status.lower() != InstanceState.ACTIVE.value:
228
+ click.echo(
229
+ f"Error: Instance '{instance_name}' is not active (status: '{status}')",
230
+ err=True,
231
+ )
232
+ click.echo(
233
+ f"Console attachment requires the instance to be in '{InstanceState.ACTIVE.value}' state.",
234
+ err=True,
235
+ )
236
+ click.echo(f"Start the instance with: kerf exec {instance_name}", err=True)
237
+ sys.exit(1)
238
+
239
+ if verbose:
240
+ click.echo(f"Instance status: {status}")
241
+
242
+ # Run the console
243
+ result = run_console(instance_id, instance_name, verbose)
244
+ sys.exit(result)
245
+
246
+ except Exception as e:
247
+ click.echo(f"Unexpected error: {e}", err=True)
248
+ if verbose:
249
+ import traceback
250
+
251
+ traceback.print_exc()
252
+ sys.exit(1)
@@ -0,0 +1,17 @@
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
+ Create kernel instance command.
17
+ """