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/delete/main.py ADDED
@@ -0,0 +1,238 @@
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
+ Delete kernel instance command.
17
+
18
+ This command removes a kernel instance by generating an instance-remove overlay
19
+ and applying it to /sys/fs/multikernel/overlays/new. The instance must not have
20
+ a kernel loaded (must be in EMPTY or READY state).
21
+ """
22
+
23
+ import sys
24
+ from typing import Optional
25
+ import click
26
+
27
+ from ..runtime import DeviceTreeManager
28
+ from ..models import InstanceState
29
+ from ..exceptions import ResourceError, ValidationError, KernelInterfaceError, ParseError
30
+ from ..utils import get_instance_id_from_name, get_instance_name_from_id, get_instance_status
31
+
32
+
33
+ @click.command(name="delete")
34
+ @click.argument("name", required=False)
35
+ @click.option("--id", type=int, help="Multikernel instance ID to delete (alternative to name)")
36
+ @click.option("--verbose", "-v", is_flag=True, help="Verbose output")
37
+ @click.option("--dry-run", is_flag=True, help="Validate without applying to kernel")
38
+ @click.pass_context
39
+ def delete(
40
+ ctx: click.Context, name: Optional[str], id: Optional[int], verbose: bool, dry_run: bool
41
+ ):
42
+ """
43
+ Delete a kernel instance from the device tree.
44
+
45
+ This command generates an instance-remove overlay and applies it to the kernel,
46
+ which handles deletion via mk_instance_destroy(). The instance must not have a
47
+ kernel loaded (must be in EMPTY or READY state). If a kernel is loaded, use
48
+ 'kerf unload' first.
49
+
50
+ Examples:
51
+
52
+ kerf delete web-server
53
+ kerf delete --id=1
54
+ kerf delete web-server --verbose
55
+ kerf delete web-server --dry-run
56
+ """
57
+ try:
58
+ if not name and id is None:
59
+ click.echo("Error: Either instance name or --id must be provided", err=True)
60
+ click.echo("Usage: kerf delete <name> or kerf delete --id=<id>", err=True)
61
+ sys.exit(2)
62
+
63
+ debug = ctx.obj.get("debug", False) if ctx and ctx.obj else False
64
+
65
+ manager = DeviceTreeManager()
66
+ instance_name = None
67
+ instance_id = None
68
+
69
+ if name:
70
+ instance_name = name
71
+ if not manager.has_instance(name):
72
+ click.echo(f"Error: Instance '{name}' does not exist", err=True)
73
+ click.echo("Check available instances in /sys/fs/multikernel/instances/", err=True)
74
+ sys.exit(1)
75
+
76
+ instance_id = get_instance_id_from_name(name)
77
+ if instance_id is None:
78
+ click.echo(f"Error: Could not read instance ID for '{name}'", err=True)
79
+ sys.exit(1)
80
+
81
+ if verbose:
82
+ click.echo(f"Instance name: {name} (ID: {instance_id})")
83
+ else:
84
+ instance_id = id
85
+ if instance_id < 1 or instance_id > 511:
86
+ click.echo(f"Error: --id must be between 1 and 511 (got {instance_id})", err=True)
87
+ sys.exit(2)
88
+
89
+ instance_name = get_instance_name_from_id(instance_id)
90
+ if not instance_name:
91
+ click.echo(f"Error: Instance with ID {instance_id} not found", err=True)
92
+ click.echo("Check available instances in /sys/fs/multikernel/instances/", err=True)
93
+ sys.exit(1)
94
+
95
+ if verbose:
96
+ click.echo(f"Instance name: {instance_name} (ID: {instance_id})")
97
+
98
+ status = get_instance_status(instance_name)
99
+
100
+ if status is None:
101
+ if verbose:
102
+ click.echo(f"Warning: Status file not found for instance '{instance_name}'")
103
+ else:
104
+ status_lower = status.lower()
105
+
106
+ if status_lower == InstanceState.LOADED.value:
107
+ click.echo(
108
+ f"Error: Cannot delete instance '{instance_name}' (ID: {instance_id})", err=True
109
+ )
110
+ click.echo(f"Instance has a kernel loaded (status: {status}).", err=True)
111
+ click.echo(
112
+ f"Please unload the kernel first using: kerf unload {instance_name}", err=True
113
+ )
114
+ sys.exit(1)
115
+
116
+ if status_lower == InstanceState.ACTIVE.value:
117
+ click.echo(
118
+ f"Error: Cannot delete instance '{instance_name}' (ID: {instance_id})", err=True
119
+ )
120
+ click.echo(f"Instance is currently ACTIVE (running, status: {status}).", err=True)
121
+ click.echo("Please stop and unload the kernel first.", err=True)
122
+ sys.exit(1)
123
+
124
+ if verbose:
125
+ click.echo(f"Instance status: '{status}' (OK to delete)")
126
+
127
+ if dry_run:
128
+ try:
129
+ click.echo(f"✓ Validation passed for deletion of instance '{instance_name}'")
130
+ click.echo(f" Instance ID: {instance_id}")
131
+
132
+ if debug:
133
+ try:
134
+ from ..dtc.parser import DeviceTreeParser
135
+ import libfdt
136
+
137
+ dtbo_data = manager.overlay_gen.generate_removal_overlay(instance_name)
138
+ fdt = libfdt.Fdt(dtbo_data)
139
+ parser = DeviceTreeParser()
140
+ parser.fdt = fdt
141
+ dts_lines = parser._fdt_to_dts_recursive(0, 0) # pylint: disable=protected-access
142
+ dts_content = "\n".join(dts_lines)
143
+
144
+ click.echo(
145
+ f"\nDebug: Overlay DTS source for deletion of '{instance_name}' (dry-run):"
146
+ )
147
+ click.echo("─" * 70)
148
+ click.echo(dts_content)
149
+ click.echo("─" * 70)
150
+ except Exception as e:
151
+ click.echo(f"Debug: Failed to generate DTS output: {e}", err=True)
152
+ if verbose:
153
+ import traceback
154
+
155
+ traceback.print_exc()
156
+
157
+ click.echo("\n✓ Instance would be deleted (dry-run mode)")
158
+ click.echo(" Remove --dry-run to apply overlay to kernel")
159
+ except (ResourceError, ValidationError) as e:
160
+ click.echo(f"Error: {e}", err=True)
161
+ sys.exit(1)
162
+ except (KernelInterfaceError, ParseError) as e:
163
+ click.echo(f"Error: {e}", err=True)
164
+ sys.exit(1)
165
+ return
166
+
167
+ try:
168
+ if debug:
169
+ try:
170
+ from ..dtc.parser import DeviceTreeParser
171
+ import libfdt
172
+
173
+ dtbo_data = manager.overlay_gen.generate_removal_overlay(instance_name)
174
+ fdt = libfdt.Fdt(dtbo_data)
175
+ parser = DeviceTreeParser()
176
+ parser.fdt = fdt
177
+ dts_lines = parser._fdt_to_dts_recursive(0, 0) # pylint: disable=protected-access
178
+ dts_content = "\n".join(dts_lines)
179
+
180
+ click.echo(f"\nDebug: Overlay DTS source for deletion of '{instance_name}':")
181
+ click.echo("─" * 70)
182
+ click.echo(dts_content)
183
+ click.echo("─" * 70)
184
+ except Exception as e:
185
+ click.echo(f"Debug: Failed to generate DTS output: {e}", err=True)
186
+ if verbose:
187
+ import traceback
188
+
189
+ traceback.print_exc()
190
+
191
+ tx_id = manager.apply_removal_overlay(instance_name)
192
+
193
+ try:
194
+ from ..metadata import delete_instance_metadata
195
+
196
+ delete_instance_metadata(instance_name)
197
+ except OSError:
198
+ pass
199
+
200
+ click.echo(f"✓ Deleted instance '{instance_name}' (transaction {tx_id})")
201
+ if verbose:
202
+ click.echo(f" Instance ID: {instance_id}")
203
+ except ResourceError as e:
204
+ click.echo(f"Error: {e}", err=True)
205
+ if verbose:
206
+ import traceback
207
+
208
+ traceback.print_exc()
209
+ sys.exit(1)
210
+ except ValidationError as e:
211
+ click.echo(f"Error: Validation failed: {e}", err=True)
212
+ if verbose:
213
+ import traceback
214
+
215
+ traceback.print_exc()
216
+ sys.exit(1)
217
+ except KernelInterfaceError as e:
218
+ click.echo(f"Error: Kernel interface error: {e}", err=True)
219
+ if verbose:
220
+ import traceback
221
+
222
+ traceback.print_exc()
223
+ sys.exit(1)
224
+
225
+ except KeyboardInterrupt:
226
+ click.echo("\nOperation cancelled", err=True)
227
+ sys.exit(130)
228
+ except Exception as e:
229
+ click.echo(f"Unexpected error: {e}", err=True)
230
+ if verbose:
231
+ import traceback
232
+
233
+ traceback.print_exc()
234
+ sys.exit(1)
235
+
236
+
237
+ if __name__ == "__main__":
238
+ delete()
@@ -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
+ Docker image extraction module for kerf.
17
+ """
18
+
19
+ from .image import extract_image, get_image_entrypoint
20
+
21
+ __all__ = ["extract_image", "get_image_entrypoint"]
kerf/docker/image.py ADDED
@@ -0,0 +1,234 @@
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
+ OCI image extraction and configuration parsing via the Docker daemon API.
17
+ """
18
+
19
+ import hashlib
20
+ import http.client
21
+ import json
22
+ import shutil
23
+ import socket
24
+ import tarfile
25
+ import tempfile
26
+ import urllib.parse
27
+ from pathlib import Path
28
+ from typing import List, Tuple
29
+
30
+ KERF_ROOTFS_DIR = "/var/lib/kerf/rootfs"
31
+ DOCKER_SOCKET = "/var/run/docker.sock"
32
+
33
+
34
+ class DockerError(Exception):
35
+ """Exception raised for image extraction errors."""
36
+
37
+
38
+ class _UnixSocketConnection(http.client.HTTPConnection):
39
+ """HTTP connection over the Docker daemon's Unix socket."""
40
+
41
+ def __init__(self, socket_path: str):
42
+ super().__init__("localhost")
43
+ self._socket_path = socket_path
44
+
45
+ def connect(self):
46
+ sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
47
+ sock.connect(self._socket_path)
48
+ self.sock = sock
49
+
50
+
51
+ def _docker_request(method: str, path: str) -> http.client.HTTPResponse:
52
+ """Send a request to the Docker daemon and return the response.
53
+
54
+ The caller owns the response and must read it fully; closing the
55
+ response also closes the underlying connection.
56
+ """
57
+ conn = _UnixSocketConnection(DOCKER_SOCKET)
58
+ try:
59
+ conn.request(method, path)
60
+ return conn.getresponse()
61
+ except (FileNotFoundError, ConnectionRefusedError, PermissionError) as e:
62
+ conn.close()
63
+ raise DockerError(
64
+ f"Cannot connect to Docker daemon at {DOCKER_SOCKET}. "
65
+ "Is the Docker daemon running?"
66
+ ) from e
67
+
68
+
69
+ def _split_ref(image_ref: str) -> Tuple[str, str]:
70
+ """Split an image reference into (name, tag-or-digest)."""
71
+ if "@" in image_ref:
72
+ name, _, digest = image_ref.partition("@")
73
+ return name, digest
74
+ name, sep, tag = image_ref.rpartition(":")
75
+ # A ':' inside the registry host part (e.g. localhost:5000/img) is not a tag
76
+ if sep and "/" not in tag:
77
+ return name, tag
78
+ return image_ref, "latest"
79
+
80
+
81
+ def _error_message(body: str) -> str:
82
+ """Extract the human-readable message from a daemon error body."""
83
+ try:
84
+ return json.loads(body)["message"]
85
+ except (json.JSONDecodeError, KeyError, TypeError):
86
+ return body.strip()
87
+
88
+
89
+ def _pull_image(image_ref: str) -> None:
90
+ """Pull an image through the Docker daemon."""
91
+ name, tag = _split_ref(image_ref)
92
+ query = urllib.parse.urlencode({"fromImage": name, "tag": tag})
93
+ resp = _docker_request("POST", f"/images/create?{query}")
94
+ with resp:
95
+ if resp.status != 200:
96
+ body = resp.read().decode(errors="replace")
97
+ raise DockerError(
98
+ f"Failed to pull image '{image_ref}': {_error_message(body)}"
99
+ )
100
+ # The daemon streams progress as JSON lines; a mid-stream failure
101
+ # still comes back with status 200 and an "error" message.
102
+ for line in resp:
103
+ line = line.strip()
104
+ if not line:
105
+ continue
106
+ try:
107
+ message = json.loads(line)
108
+ except json.JSONDecodeError:
109
+ continue
110
+ if "error" in message:
111
+ raise DockerError(
112
+ f"Failed to pull image '{image_ref}': {message['error']}"
113
+ )
114
+
115
+
116
+ def _image_request_with_pull(method: str, path_template: str, image_ref: str
117
+ ) -> http.client.HTTPResponse:
118
+ """Send an image request, pulling the image first if not present locally."""
119
+ path = path_template.format(name=urllib.parse.quote(image_ref, safe="/:"))
120
+ resp = _docker_request(method, path)
121
+ if resp.status == 404:
122
+ resp.read()
123
+ resp.close()
124
+ _pull_image(image_ref)
125
+ resp = _docker_request(method, path)
126
+ if resp.status != 200:
127
+ status = resp.status
128
+ with resp:
129
+ body = resp.read().decode(errors="replace")
130
+ raise DockerError(
131
+ f"Docker daemon returned status {status} for image "
132
+ f"'{image_ref}': {_error_message(body)}"
133
+ )
134
+ return resp
135
+
136
+
137
+ def extract_image(image_ref: str, instance_name: str) -> Tuple[str, List[str], str]:
138
+ """
139
+ Extract an image filesystem to a directory via the Docker daemon.
140
+
141
+ Args:
142
+ image_ref: Docker image reference (e.g., "nginx:latest")
143
+ instance_name: Instance name for directory naming
144
+
145
+ Returns:
146
+ Tuple of (rootfs_path, entrypoint_cmd, image_id), where image_id
147
+ is the sha256 digest of the image config blob, or None if the
148
+ image tar has no config
149
+
150
+ Raises:
151
+ DockerError: If extraction fails
152
+ """
153
+ rootfs_path = Path(KERF_ROOTFS_DIR) / instance_name
154
+ if rootfs_path.exists():
155
+ shutil.rmtree(rootfs_path)
156
+ rootfs_path.mkdir(parents=True, exist_ok=True)
157
+
158
+ with tempfile.TemporaryDirectory() as tmpdir:
159
+ tar_path = Path(tmpdir) / "image.tar"
160
+
161
+ resp = _image_request_with_pull("GET", "/images/{name}/get", image_ref)
162
+ with resp, open(tar_path, "wb") as f:
163
+ shutil.copyfileobj(resp, f)
164
+
165
+ entrypoint = []
166
+ cmd = []
167
+ image_id = None
168
+
169
+ with tarfile.open(tar_path, 'r') as tar:
170
+ manifest_data = None
171
+ for member in tar.getmembers():
172
+ if member.name == "manifest.json":
173
+ f = tar.extractfile(member)
174
+ if f:
175
+ manifest_data = json.load(f)
176
+ break
177
+
178
+ if manifest_data and len(manifest_data) > 0:
179
+ config_file = manifest_data[0].get("Config", "")
180
+ if config_file:
181
+ for member in tar.getmembers():
182
+ if member.name == config_file:
183
+ f = tar.extractfile(member)
184
+ if f:
185
+ raw_config = f.read()
186
+ # The image ID is the digest of the config blob
187
+ image_id = "sha256:" + hashlib.sha256(raw_config).hexdigest()
188
+ config = json.loads(raw_config)
189
+ oci_config = config.get("config", {})
190
+ entrypoint = oci_config.get("Entrypoint") or []
191
+ cmd = oci_config.get("Cmd") or []
192
+ break
193
+
194
+ layers = manifest_data[0].get("Layers", [])
195
+ for layer_name in layers:
196
+ for member in tar.getmembers():
197
+ if member.name == layer_name:
198
+ layer_file = tar.extractfile(member)
199
+ if layer_file:
200
+ with tarfile.open(fileobj=layer_file, mode='r:*') as layer_tar:
201
+ # A rootfs needs full metadata (setuid bits,
202
+ # device nodes, absolute symlinks), which the
203
+ # Python 3.14 default 'data' filter rejects
204
+ layer_tar.extractall(
205
+ path=rootfs_path, filter="fully_trusted"
206
+ )
207
+ break
208
+
209
+ return str(rootfs_path), entrypoint + cmd, image_id
210
+
211
+
212
+ def get_image_entrypoint(image_ref: str) -> List[str]:
213
+ """
214
+ Get ENTRYPOINT + CMD from image without extracting.
215
+
216
+ Args:
217
+ image_ref: Docker image reference (e.g., "nginx:latest")
218
+
219
+ Returns:
220
+ List of command components (ENTRYPOINT + CMD)
221
+
222
+ Raises:
223
+ DockerError: If image info cannot be retrieved
224
+ """
225
+ resp = _image_request_with_pull("GET", "/images/{name}/json", image_ref)
226
+ with resp:
227
+ try:
228
+ config = json.load(resp)
229
+ except json.JSONDecodeError as e:
230
+ raise DockerError(f"Failed to parse image config: {e}") from e
231
+ oci_config = config.get("Config") or {}
232
+ entrypoint = oci_config.get("Entrypoint") or []
233
+ cmd = oci_config.get("Cmd") or []
234
+ return entrypoint + cmd
kerf/dtc/__init__.py ADDED
@@ -0,0 +1,27 @@
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
+ Device Tree Compiler module for kerf CLI tool.
17
+
18
+ Internal module providing device tree compilation, validation, and instance extraction
19
+ capabilities.
20
+ """
21
+
22
+ from .parser import DeviceTreeParser
23
+ from .validator import MultikernelValidator
24
+ from .extractor import InstanceExtractor
25
+ from .reporter import ValidationReporter
26
+
27
+ __all__ = ["DeviceTreeParser", "MultikernelValidator", "InstanceExtractor", "ValidationReporter"]
kerf/dtc/cells.py ADDED
@@ -0,0 +1,51 @@
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
+ Device tree cell encoding for physical CPU IDs.
17
+
18
+ The kernel's multikernel core identifies CPUs by their physical ID (APIC
19
+ ID on x86, MPIDR on arm64, hartid on riscv), which is a sparse 64-bit
20
+ value. All "cpus" properties and cpu@N reg cells therefore use 64-bit
21
+ cells; 32-bit cells are still accepted on the parse side for device
22
+ trees written before the widening.
23
+ """
24
+
25
+ import struct
26
+ from typing import List, Sequence
27
+
28
+
29
+ def pack_cpu_ids(cpu_ids: Sequence[int]) -> bytes:
30
+ """Encode physical CPU IDs as an array of 64-bit device tree cells."""
31
+ return struct.pack(">" + "Q" * len(cpu_ids), *cpu_ids)
32
+
33
+
34
+ def pack_cpu_id(cpu_id: int) -> bytes:
35
+ """Encode a single physical CPU ID as one 64-bit device tree cell."""
36
+ return struct.pack(">Q", cpu_id)
37
+
38
+
39
+ def unpack_cpu_ids(data: bytes) -> List[int]:
40
+ """Decode a "cpus" property into a list of physical CPU IDs.
41
+
42
+ Arrays whose length is a multiple of 8 are decoded as 64-bit cells
43
+ (the current format); otherwise a multiple of 4 is decoded as legacy
44
+ 32-bit cells.
45
+ """
46
+ raw = bytes(data)
47
+ if len(raw) % 8 == 0:
48
+ return list(struct.unpack(f">{len(raw) // 8}Q", raw))
49
+ if len(raw) % 4 == 0:
50
+ return list(struct.unpack(f">{len(raw) // 4}I", raw))
51
+ raise ValueError(f"Invalid cpus property length: {len(raw)} bytes")