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/metadata.py ADDED
@@ -0,0 +1,134 @@
1
+ # Copyright 2026 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
+ Per-instance load metadata recorded by kerf load.
17
+
18
+ The kernel's /proc/kimage table only knows about loaded segments, not the
19
+ source image file, so kerf load records the kernel image provenance here
20
+ for kerf show to display.
21
+ """
22
+
23
+ import hashlib
24
+ import json
25
+ import os
26
+ import struct
27
+ from pathlib import Path
28
+ from typing import Optional
29
+
30
+ from .vmlinuz import (
31
+ ELF_MAGIC,
32
+ VmlinuzError,
33
+ compression_format,
34
+ is_bzimage,
35
+ payload_compression,
36
+ )
37
+
38
+ KERF_INSTANCES_DIR = "/var/lib/kerf/instances"
39
+
40
+ # Setup header field holding a pointer to the version string, less 0x200
41
+ BZIMAGE_KERNEL_VERSION = 0x20E
42
+
43
+
44
+ def _metadata_path(name: str) -> Path:
45
+ return Path(KERF_INSTANCES_DIR) / f"{name}.json"
46
+
47
+
48
+ def save_instance_metadata(name: str, metadata: dict) -> None:
49
+ """Persist load metadata for an instance, replacing any previous record."""
50
+ path = _metadata_path(name)
51
+ path.parent.mkdir(parents=True, exist_ok=True)
52
+ tmp = path.with_suffix(".tmp")
53
+ tmp.write_text(json.dumps(metadata, indent=2), encoding="utf-8")
54
+ os.replace(tmp, path)
55
+
56
+
57
+ def load_instance_metadata(name: str) -> Optional[dict]:
58
+ """Read load metadata for an instance, or None if absent or unreadable."""
59
+ try:
60
+ return json.loads(_metadata_path(name).read_text(encoding="utf-8"))
61
+ except (OSError, ValueError):
62
+ return None
63
+
64
+
65
+ def delete_instance_metadata(name: str) -> None:
66
+ _metadata_path(name).unlink(missing_ok=True)
67
+
68
+
69
+ def _bzimage_version(data: bytes) -> Optional[str]:
70
+ ptr = struct.unpack_from("<H", data, BZIMAGE_KERNEL_VERSION)[0]
71
+ if not ptr:
72
+ return None
73
+ start = ptr + 0x200
74
+ end = data.find(b"\x00", start)
75
+ if end <= start:
76
+ return None
77
+ return data[start:end].decode("ascii", errors="replace")
78
+
79
+
80
+ def _vmlinux_version(data: bytes) -> Optional[str]:
81
+ banner = b"Linux version "
82
+ idx = data.find(banner)
83
+ if idx == -1:
84
+ return None
85
+ start = idx + len(banner)
86
+ end = len(data)
87
+ for terminator in (b"\n", b"\x00"):
88
+ pos = data.find(terminator, start)
89
+ if pos != -1:
90
+ end = min(end, pos)
91
+ return data[start:end].decode("ascii", errors="replace") or None
92
+
93
+
94
+ def inspect_kernel_image(path) -> dict:
95
+ """Describe a kernel image file for the instance metadata record."""
96
+ data = Path(path).read_bytes()
97
+ info = {
98
+ "path": str(path),
99
+ "size": len(data),
100
+ "sha256": hashlib.sha256(data).hexdigest(),
101
+ "format": "unknown",
102
+ "compression": None,
103
+ "version": None,
104
+ }
105
+ if is_bzimage(data):
106
+ info["format"] = "bzImage"
107
+ try:
108
+ info["compression"] = payload_compression(data)
109
+ except VmlinuzError:
110
+ pass
111
+ info["version"] = _bzimage_version(data)
112
+ elif data.startswith(ELF_MAGIC):
113
+ info["format"] = "vmlinux"
114
+ info["version"] = _vmlinux_version(data)
115
+ return info
116
+
117
+
118
+ # newc, crc, and odc cpio archive magics
119
+ _CPIO_MAGICS = (b"070701", b"070702", b"070707")
120
+
121
+
122
+ def inspect_initrd_image(path) -> dict:
123
+ """Describe an initrd file for the instance metadata record."""
124
+ data = Path(path).read_bytes()
125
+ if data.startswith(_CPIO_MAGICS):
126
+ compression = "cpio"
127
+ else:
128
+ compression = compression_format(data)
129
+ return {
130
+ "path": str(path),
131
+ "size": len(data),
132
+ "sha256": hashlib.sha256(data).hexdigest(),
133
+ "compression": compression,
134
+ }
kerf/models.py ADDED
@@ -0,0 +1,241 @@
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
+ Data models for multikernel device tree representation.
17
+ """
18
+
19
+ from dataclasses import dataclass
20
+ from typing import List, Dict, Optional, Set, Tuple
21
+ from enum import Enum
22
+
23
+
24
+ class WorkloadType(Enum):
25
+ """Types of workloads for kernel instances."""
26
+
27
+ WEB_SERVER = "web-server"
28
+ DATABASE_OLTP = "database-oltp"
29
+ COMPUTE = "compute"
30
+ STORAGE = "storage"
31
+ NETWORK = "network"
32
+
33
+
34
+ class InstanceState(Enum):
35
+ """
36
+ Instance state enum matching kernel mk_instance_state.
37
+
38
+ States:
39
+ - EMPTY: Instance directory exists but no DTB
40
+ - READY: DTB loaded, resources reserved
41
+ - LOADED: Kernel loaded, ready to start
42
+ - ACTIVE: Kernel running
43
+ - FAILED: Error occurred
44
+ """
45
+
46
+ EMPTY = "empty"
47
+ READY = "ready"
48
+ LOADED = "loaded"
49
+ ACTIVE = "active"
50
+ FAILED = "failed"
51
+
52
+
53
+ @dataclass
54
+ class InstanceConfig:
55
+ """Configuration for a kernel instance."""
56
+
57
+ workload_type: WorkloadType
58
+ priority: Optional[int] = None
59
+ timeout: Optional[int] = None
60
+ enable_pgo: Optional[bool] = None
61
+ pgo_profile: Optional[str] = None
62
+ enable_numa: Optional[bool] = None
63
+
64
+
65
+ @dataclass
66
+ class CPUTopology:
67
+ """CPU topology information."""
68
+
69
+ cpu_id: int
70
+ numa_node: int
71
+ core_id: int
72
+ thread_id: int
73
+ socket_id: int
74
+ cache_levels: List[int] # Cache sizes at each level
75
+ flags: List[str] # CPU flags like "smt", "ht", etc.
76
+
77
+
78
+ @dataclass
79
+ class NUMANode:
80
+ """NUMA node information."""
81
+
82
+ node_id: int
83
+ memory_base: int
84
+ memory_size: int
85
+ cpus: List[int]
86
+ distance_matrix: Dict[int, int] # Distance to other NUMA nodes
87
+ memory_type: str # "dram", "hbm", "cxl", etc.
88
+
89
+
90
+ @dataclass
91
+ class CPUAllocation:
92
+ """CPU allocation information."""
93
+
94
+ total: int
95
+ host_reserved: List[int]
96
+ available: List[int]
97
+ topology: Optional[Dict[int, CPUTopology]] = None # CPU ID -> topology info
98
+
99
+ def get_allocated_cpus(self) -> Set[int]:
100
+ """Get set of CPUs allocated to instances."""
101
+ return set(self.available) - set(self.host_reserved)
102
+
103
+
104
+ @dataclass
105
+ class MemoryAllocation:
106
+ """Memory allocation information."""
107
+
108
+ total_bytes: int
109
+ host_reserved_bytes: int
110
+ memory_pool_base: int
111
+ memory_pool_bytes: int
112
+
113
+ @property
114
+ def memory_pool_end(self) -> int:
115
+ """End address of memory pool."""
116
+ return self.memory_pool_base + self.memory_pool_bytes
117
+
118
+
119
+ @dataclass
120
+ class DeviceInfo:
121
+ """Device information from hardware inventory."""
122
+
123
+ name: str
124
+ compatible: str
125
+ device_type: Optional[str] = None # "pci", "platform", etc.
126
+ device_name: Optional[str] = None # For platform devices (e.g., "serial8250")
127
+ pci_id: Optional[str] = None
128
+ vendor_id: Optional[int] = None
129
+ device_id: Optional[int] = None
130
+ sriov_vfs: Optional[int] = None
131
+ host_reserved_vf: Optional[int] = None
132
+ available_vfs: Optional[List[int]] = None
133
+ namespaces: Optional[int] = None
134
+ host_reserved_ns: Optional[int] = None
135
+ available_ns: Optional[List[int]] = None
136
+
137
+
138
+ @dataclass
139
+ class InstanceResources:
140
+ """Resource allocation for a kernel instance."""
141
+
142
+ cpus: List[int]
143
+ memory_base: int
144
+ memory_bytes: int
145
+ devices: List[str] # List of device references
146
+ numa_nodes: Optional[List[int]] = None # Preferred NUMA nodes
147
+ cpu_affinity: Optional[str] = None # "compact", "spread", "local"
148
+ memory_policy: Optional[str] = None # "local", "interleave", "bind"
149
+ uring: bool = False # Enable io_uring shared ring
150
+ uring_sq_entries: Optional[int] = None # SQ entries (default: 256)
151
+ uring_cq_entries: Optional[int] = None # CQ entries (default: 256)
152
+ uring_shim_pages: Optional[int] = None # Shim data pages (default: 64)
153
+
154
+
155
+ @dataclass
156
+ class Instance:
157
+ """A kernel instance definition."""
158
+
159
+ name: str
160
+ id: Optional[int] # None means kernel should auto-assign
161
+ resources: InstanceResources
162
+ config: Optional[InstanceConfig] = None
163
+ options: Optional[Dict[str, bool]] = None
164
+
165
+
166
+ @dataclass
167
+ class TopologySection:
168
+ """Generic topology section containing all topology types."""
169
+
170
+ numa_nodes: Optional[Dict[int, NUMANode]] = None # NUMA node ID -> node info
171
+
172
+ def get_cpus_in_numa_node(self, numa_node: int) -> List[int]:
173
+ """Get all CPUs in a specific NUMA node."""
174
+ if not self.numa_nodes or numa_node not in self.numa_nodes:
175
+ return []
176
+ return self.numa_nodes[numa_node].cpus
177
+
178
+ def get_numa_node_for_cpu(self, cpu_id: int) -> Optional[int]:
179
+ """Get NUMA node ID for a specific CPU."""
180
+ if not self.numa_nodes:
181
+ return None
182
+ for node_id, node in self.numa_nodes.items():
183
+ if cpu_id in node.cpus:
184
+ return node_id
185
+ return None
186
+
187
+ def get_memory_region_for_numa_node(self, numa_node: int) -> Optional[Tuple[int, int]]:
188
+ """Get memory region (base, size) for a specific NUMA node."""
189
+ if not self.numa_nodes or numa_node not in self.numa_nodes:
190
+ return None
191
+ node = self.numa_nodes[numa_node]
192
+ return (node.memory_base, node.memory_size)
193
+
194
+
195
+ @dataclass
196
+ class HardwareInventory:
197
+ """Complete hardware inventory."""
198
+
199
+ cpus: CPUAllocation
200
+ memory: MemoryAllocation
201
+ topology: Optional[TopologySection] = None
202
+ devices: Dict[str, DeviceInfo] = None
203
+
204
+
205
+ @dataclass
206
+ class OverlayInstanceData:
207
+ """Instance data parsed from an overlay (both creates and removals)."""
208
+
209
+ instances: Dict[str, Instance]
210
+ removals: Set[str]
211
+
212
+
213
+ @dataclass
214
+ class GlobalDeviceTree:
215
+ """Global device tree representation."""
216
+
217
+ hardware: HardwareInventory
218
+ instances: Dict[str, Instance]
219
+ device_references: Dict[str, Dict] # phandle references
220
+
221
+
222
+ @dataclass
223
+ class ValidationResult:
224
+ """Result of validation process."""
225
+
226
+ is_valid: bool
227
+ errors: List[str]
228
+ warnings: List[str]
229
+ suggestions: List[str]
230
+
231
+
232
+ @dataclass
233
+ class ResourceUsage:
234
+ """Resource usage summary."""
235
+
236
+ cpus_allocated: int
237
+ cpus_total: int
238
+ memory_allocated: int
239
+ memory_total: int
240
+ devices_allocated: int
241
+ devices_total: int