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 +74 -0
- kerf/baseline.py +187 -0
- kerf/cli.py +56 -0
- kerf/console/__init__.py +21 -0
- kerf/console/main.py +252 -0
- kerf/create/__init__.py +17 -0
- kerf/create/main.py +780 -0
- kerf/data/__init__.py +24 -0
- kerf/data/kerf-init +0 -0
- kerf/daxfs/__init__.py +31 -0
- kerf/daxfs/mkdaxfs.py +597 -0
- kerf/delete/__init__.py +21 -0
- kerf/delete/main.py +238 -0
- kerf/docker/__init__.py +21 -0
- kerf/docker/image.py +234 -0
- kerf/dtc/__init__.py +27 -0
- kerf/dtc/cells.py +51 -0
- kerf/dtc/extractor.py +362 -0
- kerf/dtc/overlay.py +378 -0
- kerf/dtc/parser.py +1548 -0
- kerf/dtc/reporter.py +308 -0
- kerf/dtc/validator.py +792 -0
- kerf/exceptions.py +49 -0
- kerf/exec/__init__.py +21 -0
- kerf/exec/main.py +260 -0
- kerf/init/__init__.py +13 -0
- kerf/init/main.py +696 -0
- kerf/kill/__init__.py +21 -0
- kerf/kill/main.py +275 -0
- kerf/lazy_cma.py +132 -0
- kerf/load/__init__.py +21 -0
- kerf/load/main.py +613 -0
- kerf/metadata.py +134 -0
- kerf/models.py +241 -0
- kerf/resources.py +369 -0
- kerf/runtime.py +527 -0
- kerf/show/__init__.py +21 -0
- kerf/show/main.py +616 -0
- kerf/unload/__init__.py +21 -0
- kerf/unload/main.py +310 -0
- kerf/update/__init__.py +15 -0
- kerf/update/main.py +450 -0
- kerf/utils.py +95 -0
- kerf/vmlinuz.py +213 -0
- kerf_multikernel-0.1.0.dist-info/LICENSE +201 -0
- kerf_multikernel-0.1.0.dist-info/METADATA +382 -0
- kerf_multikernel-0.1.0.dist-info/RECORD +49 -0
- kerf_multikernel-0.1.0.dist-info/WHEEL +4 -0
- kerf_multikernel-0.1.0.dist-info/entry_points.txt +3 -0
kerf/create/main.py
ADDED
|
@@ -0,0 +1,780 @@
|
|
|
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
|
+
|
|
18
|
+
This command creates a new kernel instance with specified resource allocations.
|
|
19
|
+
Resources are validated against the baseline and existing instances before
|
|
20
|
+
creating an overlay and applying it to the kernel.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
import copy
|
|
24
|
+
import sys
|
|
25
|
+
import traceback
|
|
26
|
+
from typing import List, Optional
|
|
27
|
+
import click
|
|
28
|
+
|
|
29
|
+
from ..runtime import DeviceTreeManager
|
|
30
|
+
from ..models import Instance, InstanceResources
|
|
31
|
+
from ..resources import (
|
|
32
|
+
validate_cpu_allocation,
|
|
33
|
+
validate_memory_allocation,
|
|
34
|
+
find_available_memory_base,
|
|
35
|
+
get_available_cpus,
|
|
36
|
+
)
|
|
37
|
+
from ..exceptions import ValidationError, KernelInterfaceError, ResourceError, ParseError
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def parse_cpu_spec(cpu_spec: str) -> List[int]:
|
|
41
|
+
"""
|
|
42
|
+
Parse CPU specification string into explicit CPU IDs.
|
|
43
|
+
|
|
44
|
+
Supports formats:
|
|
45
|
+
- "4" (single CPU ID 4)
|
|
46
|
+
- "4-7" (range of CPUs: 4, 5, 6, 7)
|
|
47
|
+
- "4,5,6,7" (comma-separated list)
|
|
48
|
+
- "4-7,10-12" (mixed ranges and lists)
|
|
49
|
+
|
|
50
|
+
Args:
|
|
51
|
+
cpu_spec: CPU specification string
|
|
52
|
+
|
|
53
|
+
Returns:
|
|
54
|
+
List of explicit CPU IDs (sorted)
|
|
55
|
+
|
|
56
|
+
Raises:
|
|
57
|
+
ValueError: If specification is invalid
|
|
58
|
+
"""
|
|
59
|
+
cpu_spec = cpu_spec.strip()
|
|
60
|
+
|
|
61
|
+
# Explicit CPU specification
|
|
62
|
+
cpus = set()
|
|
63
|
+
|
|
64
|
+
# Split by comma
|
|
65
|
+
parts = [p.strip() for p in cpu_spec.split(",")]
|
|
66
|
+
|
|
67
|
+
for part in parts:
|
|
68
|
+
if "-" in part:
|
|
69
|
+
# Range format: "4-7"
|
|
70
|
+
try:
|
|
71
|
+
start, end = part.split("-", 1)
|
|
72
|
+
start = int(start.strip())
|
|
73
|
+
end = int(end.strip())
|
|
74
|
+
if start > end:
|
|
75
|
+
raise ValueError(f"Invalid CPU range: {start} > {end}")
|
|
76
|
+
cpus.update(range(start, end + 1))
|
|
77
|
+
except ValueError as e:
|
|
78
|
+
raise ValueError(f"Invalid CPU range format '{part}': {e}") from e
|
|
79
|
+
else:
|
|
80
|
+
# Single CPU
|
|
81
|
+
try:
|
|
82
|
+
cpus.add(int(part.strip()))
|
|
83
|
+
except ValueError as e:
|
|
84
|
+
raise ValueError(f"Invalid CPU ID '{part}': {e}") from e
|
|
85
|
+
|
|
86
|
+
if not cpus:
|
|
87
|
+
raise ValueError("CPU specification must include at least one CPU")
|
|
88
|
+
|
|
89
|
+
return sorted(list(cpus))
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _find_consecutive_cpus(cpu_list: List[int], count: int) -> Optional[List[int]]:
|
|
93
|
+
"""Find a consecutive range of CPUs in the list."""
|
|
94
|
+
for i in range(len(cpu_list) - count + 1):
|
|
95
|
+
is_consecutive = all(cpu_list[i + j + 1] == cpu_list[i + j] + 1 for j in range(count - 1))
|
|
96
|
+
if is_consecutive:
|
|
97
|
+
return cpu_list[i : i + count]
|
|
98
|
+
return None
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _allocate_compact(
|
|
102
|
+
tree, available: List[int], count: int, numa_nodes: Optional[List[int]]
|
|
103
|
+
) -> List[int]:
|
|
104
|
+
"""Allocate CPUs with compact affinity policy."""
|
|
105
|
+
if numa_nodes and tree.hardware.topology and tree.hardware.topology.numa_nodes:
|
|
106
|
+
for numa_node_id in numa_nodes:
|
|
107
|
+
numa_cpus = [
|
|
108
|
+
cpu
|
|
109
|
+
for cpu in available
|
|
110
|
+
if tree.hardware.topology.get_numa_node_for_cpu(cpu) == numa_node_id
|
|
111
|
+
]
|
|
112
|
+
if len(numa_cpus) >= count:
|
|
113
|
+
consecutive = _find_consecutive_cpus(numa_cpus, count)
|
|
114
|
+
if consecutive:
|
|
115
|
+
return sorted(consecutive)
|
|
116
|
+
return sorted(numa_cpus[:count])
|
|
117
|
+
|
|
118
|
+
consecutive = _find_consecutive_cpus(available, count)
|
|
119
|
+
if consecutive:
|
|
120
|
+
return consecutive
|
|
121
|
+
return available[:count]
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _allocate_spread(
|
|
125
|
+
tree, available: List[int], count: int, numa_nodes: Optional[List[int]]
|
|
126
|
+
) -> List[int]:
|
|
127
|
+
"""Allocate CPUs with spread affinity policy."""
|
|
128
|
+
if numa_nodes and tree.hardware.topology and tree.hardware.topology.numa_nodes:
|
|
129
|
+
numa_cpu_lists = {}
|
|
130
|
+
for numa_node_id in numa_nodes:
|
|
131
|
+
numa_cpus = [
|
|
132
|
+
cpu
|
|
133
|
+
for cpu in available
|
|
134
|
+
if tree.hardware.topology.get_numa_node_for_cpu(cpu) == numa_node_id
|
|
135
|
+
]
|
|
136
|
+
if numa_cpus:
|
|
137
|
+
numa_cpu_lists[numa_node_id] = sorted(numa_cpus)
|
|
138
|
+
|
|
139
|
+
if not numa_cpu_lists:
|
|
140
|
+
raise ResourceError(f"No available APIC IDs in specified NUMA nodes: {numa_nodes}")
|
|
141
|
+
|
|
142
|
+
allocated = []
|
|
143
|
+
numa_indices = {node_id: 0 for node_id in numa_cpu_lists}
|
|
144
|
+
|
|
145
|
+
for i in range(count):
|
|
146
|
+
numa_idx = i % len(numa_cpu_lists)
|
|
147
|
+
numa_node_id = list(numa_cpu_lists.keys())[numa_idx]
|
|
148
|
+
cpu_list = numa_cpu_lists[numa_node_id]
|
|
149
|
+
|
|
150
|
+
if numa_indices[numa_node_id] < len(cpu_list):
|
|
151
|
+
allocated.append(cpu_list[numa_indices[numa_node_id]])
|
|
152
|
+
numa_indices[numa_node_id] += 1
|
|
153
|
+
else:
|
|
154
|
+
for next_numa_id, next_cpu_list in numa_cpu_lists.items():
|
|
155
|
+
if numa_indices[next_numa_id] < len(next_cpu_list):
|
|
156
|
+
allocated.append(next_cpu_list[numa_indices[next_numa_id]])
|
|
157
|
+
numa_indices[next_numa_id] += 1
|
|
158
|
+
break
|
|
159
|
+
|
|
160
|
+
return sorted(allocated)
|
|
161
|
+
|
|
162
|
+
if count == 1:
|
|
163
|
+
return [available[0]]
|
|
164
|
+
|
|
165
|
+
step = (len(available) - 1) / (count - 1) if count > 1 else 1
|
|
166
|
+
indices = [int(i * step) for i in range(count)]
|
|
167
|
+
return sorted([available[i] for i in indices])
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def _allocate_local(
|
|
171
|
+
tree, available: List[int], count: int, numa_nodes: Optional[List[int]]
|
|
172
|
+
) -> List[int]:
|
|
173
|
+
"""Allocate CPUs with local affinity policy."""
|
|
174
|
+
if not tree.hardware.topology or not tree.hardware.topology.numa_nodes:
|
|
175
|
+
raise ResourceError(
|
|
176
|
+
"CPU affinity 'local' requires NUMA topology information. "
|
|
177
|
+
"Use 'compact' or 'spread' instead, or specify NUMA topology in baseline."
|
|
178
|
+
)
|
|
179
|
+
|
|
180
|
+
if numa_nodes and len(numa_nodes) > 0:
|
|
181
|
+
numa_node_id = numa_nodes[0]
|
|
182
|
+
numa_cpus = [
|
|
183
|
+
cpu
|
|
184
|
+
for cpu in available
|
|
185
|
+
if tree.hardware.topology.get_numa_node_for_cpu(cpu) == numa_node_id
|
|
186
|
+
]
|
|
187
|
+
if len(numa_cpus) >= count:
|
|
188
|
+
return sorted(numa_cpus[:count])
|
|
189
|
+
raise ResourceError(
|
|
190
|
+
f"Not enough APIC IDs in NUMA node {numa_node_id}: "
|
|
191
|
+
f"requested {count}, but only {len(numa_cpus)} available"
|
|
192
|
+
)
|
|
193
|
+
|
|
194
|
+
for numa_node_id in tree.hardware.topology.numa_nodes:
|
|
195
|
+
numa_cpus = [
|
|
196
|
+
cpu
|
|
197
|
+
for cpu in available
|
|
198
|
+
if tree.hardware.topology.get_numa_node_for_cpu(cpu) == numa_node_id
|
|
199
|
+
]
|
|
200
|
+
if len(numa_cpus) >= count:
|
|
201
|
+
return sorted(numa_cpus[:count])
|
|
202
|
+
|
|
203
|
+
raise ResourceError(f"No single NUMA node has {count} available APIC IDs for 'local' affinity")
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def allocate_cpus_from_pool(
|
|
207
|
+
tree, count: int, cpu_affinity: str = "compact", numa_nodes: Optional[List[int]] = None
|
|
208
|
+
) -> List[int]:
|
|
209
|
+
"""
|
|
210
|
+
Allocate specified number of CPUs from available pool with topology awareness.
|
|
211
|
+
|
|
212
|
+
Args:
|
|
213
|
+
tree: GlobalDeviceTree to analyze
|
|
214
|
+
count: Number of CPUs to allocate
|
|
215
|
+
cpu_affinity: CPU affinity policy - "compact", "spread", or "local"
|
|
216
|
+
numa_nodes: Preferred NUMA node IDs (optional). If specified, allocates
|
|
217
|
+
CPUs only from these NUMA nodes
|
|
218
|
+
|
|
219
|
+
Returns:
|
|
220
|
+
List of allocated CPU IDs (sorted)
|
|
221
|
+
|
|
222
|
+
Raises:
|
|
223
|
+
ResourceError: If not enough CPUs available
|
|
224
|
+
"""
|
|
225
|
+
available = sorted(list(get_available_cpus(tree)))
|
|
226
|
+
|
|
227
|
+
# Filter by NUMA nodes if specified
|
|
228
|
+
if numa_nodes and tree.hardware.topology and tree.hardware.topology.numa_nodes:
|
|
229
|
+
numa_filtered = []
|
|
230
|
+
for cpu_id in available:
|
|
231
|
+
cpu_numa = tree.hardware.topology.get_numa_node_for_cpu(cpu_id)
|
|
232
|
+
if cpu_numa is not None and cpu_numa in numa_nodes:
|
|
233
|
+
numa_filtered.append(cpu_id)
|
|
234
|
+
available = numa_filtered
|
|
235
|
+
|
|
236
|
+
if len(available) < count:
|
|
237
|
+
if numa_nodes:
|
|
238
|
+
raise ResourceError(
|
|
239
|
+
f"Not enough APIC IDs available in NUMA nodes {numa_nodes}: "
|
|
240
|
+
f"requested {count}, but only {len(available)} available"
|
|
241
|
+
)
|
|
242
|
+
raise ResourceError(
|
|
243
|
+
f"Not enough APIC IDs available: requested {count}, "
|
|
244
|
+
f"but only {len(available)} available in pool"
|
|
245
|
+
)
|
|
246
|
+
|
|
247
|
+
if cpu_affinity == "compact":
|
|
248
|
+
return _allocate_compact(tree, available, count, numa_nodes)
|
|
249
|
+
if cpu_affinity == "spread":
|
|
250
|
+
return _allocate_spread(tree, available, count, numa_nodes)
|
|
251
|
+
if cpu_affinity == "local":
|
|
252
|
+
return _allocate_local(tree, available, count, numa_nodes)
|
|
253
|
+
raise ValueError(f"Unknown CPU affinity policy: {cpu_affinity}")
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def parse_memory_spec(memory_spec: str) -> int:
|
|
257
|
+
"""
|
|
258
|
+
Parse memory specification string into bytes.
|
|
259
|
+
|
|
260
|
+
Supports formats:
|
|
261
|
+
- "2GB" or "2gb"
|
|
262
|
+
- "2048MB" or "2048mb"
|
|
263
|
+
- "2097152KB" or "2097152kb"
|
|
264
|
+
- "2147483648" (raw bytes)
|
|
265
|
+
|
|
266
|
+
Args:
|
|
267
|
+
memory_spec: Memory specification string
|
|
268
|
+
|
|
269
|
+
Returns:
|
|
270
|
+
Size in bytes
|
|
271
|
+
|
|
272
|
+
Raises:
|
|
273
|
+
ValueError: If specification is invalid
|
|
274
|
+
"""
|
|
275
|
+
memory_spec = memory_spec.strip().upper()
|
|
276
|
+
|
|
277
|
+
# Check for unit suffix
|
|
278
|
+
multipliers = {
|
|
279
|
+
"KB": 1024,
|
|
280
|
+
"MB": 1024**2,
|
|
281
|
+
"GB": 1024**3,
|
|
282
|
+
"TB": 1024**4,
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
for unit, multiplier in multipliers.items():
|
|
286
|
+
if memory_spec.endswith(unit):
|
|
287
|
+
try:
|
|
288
|
+
value = float(memory_spec[: -len(unit)].strip())
|
|
289
|
+
return int(value * multiplier)
|
|
290
|
+
except ValueError as exc:
|
|
291
|
+
raise ValueError(
|
|
292
|
+
f"Invalid memory value '{memory_spec}': " f"expected number before {unit}"
|
|
293
|
+
) from exc
|
|
294
|
+
|
|
295
|
+
# No unit, assume bytes
|
|
296
|
+
try:
|
|
297
|
+
return int(memory_spec)
|
|
298
|
+
except ValueError as exc:
|
|
299
|
+
raise ValueError(
|
|
300
|
+
f"Invalid memory specification '{memory_spec}': "
|
|
301
|
+
"expected size with unit (GB/MB/KB) or bytes"
|
|
302
|
+
) from exc
|
|
303
|
+
|
|
304
|
+
|
|
305
|
+
def parse_memory_base(base_spec: str) -> int:
|
|
306
|
+
"""
|
|
307
|
+
Parse memory base address specification.
|
|
308
|
+
|
|
309
|
+
Supports formats:
|
|
310
|
+
- "0x80000000" (hexadecimal)
|
|
311
|
+
- "2147483648" (decimal)
|
|
312
|
+
|
|
313
|
+
Args:
|
|
314
|
+
base_spec: Base address specification
|
|
315
|
+
|
|
316
|
+
Returns:
|
|
317
|
+
Base address as integer
|
|
318
|
+
|
|
319
|
+
Raises:
|
|
320
|
+
ValueError: If specification is invalid
|
|
321
|
+
"""
|
|
322
|
+
base_spec = base_spec.strip()
|
|
323
|
+
|
|
324
|
+
if base_spec.startswith("0x") or base_spec.startswith("0X"):
|
|
325
|
+
try:
|
|
326
|
+
return int(base_spec, 16)
|
|
327
|
+
except ValueError as exc:
|
|
328
|
+
raise ValueError(f"Invalid hexadecimal base address '{base_spec}'") from exc
|
|
329
|
+
try:
|
|
330
|
+
return int(base_spec)
|
|
331
|
+
except ValueError as exc:
|
|
332
|
+
raise ValueError(f"Invalid base address '{base_spec}'") from exc
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
def parse_device_list(device_spec: Optional[str]) -> List[str]:
|
|
336
|
+
"""
|
|
337
|
+
Parse device specification string into list of device names.
|
|
338
|
+
|
|
339
|
+
Supports formats:
|
|
340
|
+
- "enp9s0_dev" (single device name)
|
|
341
|
+
- "enp9s0_dev,nvme0" (comma-separated device names)
|
|
342
|
+
|
|
343
|
+
Device names must match device node names in the baseline DTB.
|
|
344
|
+
|
|
345
|
+
Args:
|
|
346
|
+
device_spec: Device specification string or None (device names, comma-separated)
|
|
347
|
+
|
|
348
|
+
Returns:
|
|
349
|
+
List of device name strings (e.g., ["enp9s0_dev", "nvme0"])
|
|
350
|
+
"""
|
|
351
|
+
if not device_spec:
|
|
352
|
+
return []
|
|
353
|
+
|
|
354
|
+
devices = [d.strip() for d in device_spec.split(",") if d.strip()]
|
|
355
|
+
return devices
|
|
356
|
+
|
|
357
|
+
|
|
358
|
+
def dump_overlay_for_debug(
|
|
359
|
+
manager: DeviceTreeManager, current, modified, instance_name: str, suffix: str = ""
|
|
360
|
+
) -> None:
|
|
361
|
+
"""
|
|
362
|
+
Dump overlay DTS source to stdout for debugging when --debug is enabled.
|
|
363
|
+
|
|
364
|
+
Args:
|
|
365
|
+
manager: DeviceTreeManager instance
|
|
366
|
+
current: Current device tree state
|
|
367
|
+
modified: Modified device tree state
|
|
368
|
+
instance_name: Name of the instance being created
|
|
369
|
+
suffix: Optional suffix for display (e.g., "_dryrun")
|
|
370
|
+
"""
|
|
371
|
+
dtbo_data = manager.overlay_gen.generate_overlay(current, modified)
|
|
372
|
+
|
|
373
|
+
try:
|
|
374
|
+
# pylint: disable=import-outside-toplevel
|
|
375
|
+
from ..dtc.parser import DeviceTreeParser
|
|
376
|
+
import libfdt # pylint: disable=import-error
|
|
377
|
+
|
|
378
|
+
fdt = libfdt.Fdt(dtbo_data)
|
|
379
|
+
parser = DeviceTreeParser()
|
|
380
|
+
parser.fdt = fdt
|
|
381
|
+
# pylint: disable=protected-access
|
|
382
|
+
dts_lines = parser._fdt_to_dts_recursive(0, 0)
|
|
383
|
+
dts_content = "\n".join(dts_lines)
|
|
384
|
+
|
|
385
|
+
click.echo(f"Debug: Overlay DTS source for '{instance_name}'{suffix}:")
|
|
386
|
+
click.echo("ā" * 70)
|
|
387
|
+
click.echo(dts_content)
|
|
388
|
+
click.echo("ā" * 70)
|
|
389
|
+
except (ImportError, AttributeError, RuntimeError) as e:
|
|
390
|
+
click.echo(f"Debug: Failed to convert overlay to DTS: {e}", err=True)
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
@click.command(context_settings={"allow_extra_args": True})
|
|
394
|
+
@click.pass_context
|
|
395
|
+
@click.argument("name", required=False)
|
|
396
|
+
@click.option(
|
|
397
|
+
"--id", "instance_id", type=int, help="Instance ID (1-511, auto-assigned if not specified)"
|
|
398
|
+
)
|
|
399
|
+
@click.option(
|
|
400
|
+
"--cpus",
|
|
401
|
+
"-c",
|
|
402
|
+
help='Explicit APIC ID allocation (e.g., "128" for APIC ID 128, "128-134" for range, '
|
|
403
|
+
'"128,130,132" for list). Use physical APIC IDs, not logical CPU numbers. '
|
|
404
|
+
'Mutually exclusive with --cpu-count',
|
|
405
|
+
)
|
|
406
|
+
@click.option(
|
|
407
|
+
"--cpu-count",
|
|
408
|
+
type=int,
|
|
409
|
+
help="Auto-allocate specified number of CPUs from available pool. "
|
|
410
|
+
"Mutually exclusive with --cpus",
|
|
411
|
+
)
|
|
412
|
+
@click.option(
|
|
413
|
+
"--cpu-affinity",
|
|
414
|
+
type=click.Choice(["compact", "spread", "local"]),
|
|
415
|
+
default="compact",
|
|
416
|
+
help="CPU affinity policy: compact (same NUMA node, consecutive), "
|
|
417
|
+
"spread (across NUMA nodes), or local (co-locate with memory)",
|
|
418
|
+
)
|
|
419
|
+
@click.option(
|
|
420
|
+
"--numa-nodes",
|
|
421
|
+
help='Preferred NUMA node IDs (comma-separated, e.g., "0" or "0,1"). '
|
|
422
|
+
"CPUs allocated from these nodes only",
|
|
423
|
+
)
|
|
424
|
+
@click.option(
|
|
425
|
+
"--memory-policy",
|
|
426
|
+
type=click.Choice(["local", "interleave", "bind"]),
|
|
427
|
+
help="Memory allocation policy: local (same NUMA as CPUs), "
|
|
428
|
+
"interleave (across NUMA nodes), or bind (specific NUMA nodes)",
|
|
429
|
+
)
|
|
430
|
+
@click.option(
|
|
431
|
+
"--memory", "-m", required=True, help='Memory allocation (e.g., "2GB", "2048MB", or bytes)'
|
|
432
|
+
)
|
|
433
|
+
@click.option(
|
|
434
|
+
"--memory-base",
|
|
435
|
+
help="Memory base address (hex: 0x80000000 or decimal, auto-assigned if not specified)",
|
|
436
|
+
)
|
|
437
|
+
@click.option(
|
|
438
|
+
"--devices",
|
|
439
|
+
"-d",
|
|
440
|
+
help='Device names (comma-separated, e.g., "enp9s0_dev,nvme0"). '
|
|
441
|
+
"Device names must match device node names in the baseline DTB.",
|
|
442
|
+
)
|
|
443
|
+
@click.option(
|
|
444
|
+
"--enable-host-kcore", is_flag=True, help="Enable host kcore access for this instance"
|
|
445
|
+
)
|
|
446
|
+
@click.option("--uring", is_flag=True, default=False, help="Enable io_uring shared ring (sq=256, cq=256, shim=64)")
|
|
447
|
+
@click.option("--uring-sq-entries", type=int, default=None, help="io_uring SQ entries (power of 2, default: 256)")
|
|
448
|
+
@click.option("--uring-cq-entries", type=int, default=None, help="io_uring CQ entries (power of 2, default: 256)")
|
|
449
|
+
@click.option("--uring-shim-pages", type=int, default=None, help="Shim shared data pages (default: 64)")
|
|
450
|
+
@click.option("--dry-run", is_flag=True, help="Validate without applying to kernel")
|
|
451
|
+
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
|
|
452
|
+
def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
|
|
453
|
+
ctx: click.Context,
|
|
454
|
+
name: Optional[str],
|
|
455
|
+
instance_id: Optional[int],
|
|
456
|
+
cpus: Optional[str],
|
|
457
|
+
cpu_count: Optional[int],
|
|
458
|
+
cpu_affinity: str,
|
|
459
|
+
numa_nodes: Optional[str],
|
|
460
|
+
memory_policy: Optional[str],
|
|
461
|
+
memory: str,
|
|
462
|
+
memory_base: Optional[str],
|
|
463
|
+
devices: Optional[str],
|
|
464
|
+
enable_host_kcore: bool,
|
|
465
|
+
uring: bool,
|
|
466
|
+
uring_sq_entries: Optional[int],
|
|
467
|
+
uring_cq_entries: Optional[int],
|
|
468
|
+
uring_shim_pages: Optional[int],
|
|
469
|
+
dry_run: bool,
|
|
470
|
+
verbose: bool,
|
|
471
|
+
):
|
|
472
|
+
"""
|
|
473
|
+
Create a new kernel instance with specified resources.
|
|
474
|
+
|
|
475
|
+
This command creates a new kernel instance and allocates resources to it.
|
|
476
|
+
Resources are validated against the baseline (must be within available pool)
|
|
477
|
+
and existing instances (no overlaps allowed).
|
|
478
|
+
|
|
479
|
+
The instance name is a required positional argument that can appear anywhere
|
|
480
|
+
after the 'create' command.
|
|
481
|
+
|
|
482
|
+
Examples:
|
|
483
|
+
|
|
484
|
+
# Create instance with APIC IDs 128-134 and 2GB memory (auto-assigned base)
|
|
485
|
+
kerf create web-server --cpus=128-134 --memory=2GB
|
|
486
|
+
|
|
487
|
+
# Create instance with name after options
|
|
488
|
+
kerf create --cpus=128,130,132 --memory=8GB web-server
|
|
489
|
+
|
|
490
|
+
# Create instance with specific memory base address
|
|
491
|
+
kerf create database --cpus=128-142 --memory=8GB --memory-base=0x100000000
|
|
492
|
+
|
|
493
|
+
# Create instance with devices
|
|
494
|
+
kerf create compute --cpus=128-142 --memory=4GB --devices=enp9s0_dev
|
|
495
|
+
|
|
496
|
+
# Create instance with explicit single APIC ID
|
|
497
|
+
kerf create web-server --cpus=128 --memory=2GB
|
|
498
|
+
|
|
499
|
+
# Create instance with auto-allocated CPU count
|
|
500
|
+
kerf create web-server --cpu-count=4 --memory=2GB
|
|
501
|
+
|
|
502
|
+
# Create instance with topology-aware allocation (auto-allocated)
|
|
503
|
+
kerf create database --cpu-count=8 --memory=16GB --numa-nodes=0 --cpu-affinity=compact --memory-policy=local
|
|
504
|
+
|
|
505
|
+
# Create instance with spread affinity across multiple NUMA nodes (auto-allocated)
|
|
506
|
+
kerf create compute --cpu-count=16 --memory=32GB --numa-nodes=0,1 --cpu-affinity=spread --memory-policy=interleave
|
|
507
|
+
|
|
508
|
+
# Validate without applying
|
|
509
|
+
kerf create web-server --cpu-count=4 --memory=2GB --dry-run
|
|
510
|
+
"""
|
|
511
|
+
try:
|
|
512
|
+
if name is None and ctx is not None:
|
|
513
|
+
# Get remaining args (ones that don't match options)
|
|
514
|
+
remaining_args = ctx.args
|
|
515
|
+
for arg in remaining_args:
|
|
516
|
+
# First non-option argument is the name
|
|
517
|
+
if not arg.startswith("-") and arg:
|
|
518
|
+
name = arg
|
|
519
|
+
break
|
|
520
|
+
|
|
521
|
+
# Validate name is provided
|
|
522
|
+
if not name:
|
|
523
|
+
click.echo("Error: Instance name is required", err=True)
|
|
524
|
+
click.echo("\nUsage: kerf create <name> [OPTIONS]", err=True)
|
|
525
|
+
click.echo(" kerf create [OPTIONS] <name>", err=True)
|
|
526
|
+
sys.exit(2)
|
|
527
|
+
|
|
528
|
+
# Validate that exactly one of --cpus or --cpu-count is provided
|
|
529
|
+
if cpus and cpu_count is not None:
|
|
530
|
+
click.echo(
|
|
531
|
+
"Error: --cpus and --cpu-count are mutually exclusive. Specify either explicit CPUs (--cpus) or a count (--cpu-count)",
|
|
532
|
+
err=True,
|
|
533
|
+
)
|
|
534
|
+
sys.exit(2)
|
|
535
|
+
|
|
536
|
+
if not cpus and cpu_count is None:
|
|
537
|
+
click.echo("Error: Either --cpus or --cpu-count must be specified", err=True)
|
|
538
|
+
sys.exit(2)
|
|
539
|
+
|
|
540
|
+
# Parse CPU specification
|
|
541
|
+
is_count = cpu_count is not None
|
|
542
|
+
if is_count:
|
|
543
|
+
if cpu_count <= 0:
|
|
544
|
+
click.echo(f"Error: CPU count must be positive, got {cpu_count}", err=True)
|
|
545
|
+
sys.exit(2)
|
|
546
|
+
cpu_spec_value = cpu_count
|
|
547
|
+
else:
|
|
548
|
+
try:
|
|
549
|
+
cpu_spec_value = parse_cpu_spec(cpus)
|
|
550
|
+
except ValueError as e:
|
|
551
|
+
click.echo(f"Error: Invalid APIC ID specification '{cpus}': {e}", err=True)
|
|
552
|
+
sys.exit(2)
|
|
553
|
+
|
|
554
|
+
# Parse memory specification
|
|
555
|
+
try:
|
|
556
|
+
memory_bytes = parse_memory_spec(memory)
|
|
557
|
+
except ValueError as e:
|
|
558
|
+
click.echo(f"Error: Invalid memory specification '{memory}': {e}", err=True)
|
|
559
|
+
sys.exit(2)
|
|
560
|
+
|
|
561
|
+
# Parse memory base (if specified)
|
|
562
|
+
memory_base_addr = None
|
|
563
|
+
if memory_base:
|
|
564
|
+
try:
|
|
565
|
+
memory_base_addr = parse_memory_base(memory_base)
|
|
566
|
+
except ValueError as e:
|
|
567
|
+
click.echo(f"Error: Invalid memory base '{memory_base}': {e}", err=True)
|
|
568
|
+
sys.exit(2)
|
|
569
|
+
|
|
570
|
+
# Parse device list
|
|
571
|
+
device_list = parse_device_list(devices)
|
|
572
|
+
|
|
573
|
+
# Parse NUMA nodes (if specified)
|
|
574
|
+
numa_node_list = None
|
|
575
|
+
if numa_nodes:
|
|
576
|
+
try:
|
|
577
|
+
numa_node_list = [int(n.strip()) for n in numa_nodes.split(",") if n.strip()]
|
|
578
|
+
if not numa_node_list:
|
|
579
|
+
click.echo(f"Error: Invalid NUMA nodes specification '{numa_nodes}'", err=True)
|
|
580
|
+
sys.exit(2)
|
|
581
|
+
except ValueError as e:
|
|
582
|
+
click.echo(f"Error: Invalid NUMA nodes specification '{numa_nodes}': {e}", err=True)
|
|
583
|
+
sys.exit(2)
|
|
584
|
+
|
|
585
|
+
# Validate instance ID if specified
|
|
586
|
+
if instance_id is not None:
|
|
587
|
+
if instance_id < 1 or instance_id > 511:
|
|
588
|
+
click.echo(
|
|
589
|
+
f"Error: Instance ID must be in range 1-511, got {instance_id}", err=True
|
|
590
|
+
)
|
|
591
|
+
sys.exit(2)
|
|
592
|
+
|
|
593
|
+
debug = ctx.obj.get("debug", False) if ctx and ctx.obj else False
|
|
594
|
+
|
|
595
|
+
# Initialize manager
|
|
596
|
+
manager = DeviceTreeManager()
|
|
597
|
+
|
|
598
|
+
# Define operation to create instance
|
|
599
|
+
def create_instance_operation(current):
|
|
600
|
+
"""Operation function to create instance in device tree."""
|
|
601
|
+
nonlocal memory_base_addr # Allow modification of outer scope variable
|
|
602
|
+
|
|
603
|
+
if manager.has_instance(name):
|
|
604
|
+
raise ResourceError(f"Instance '{name}' already exists")
|
|
605
|
+
if name in current.instances:
|
|
606
|
+
pass
|
|
607
|
+
|
|
608
|
+
# Create modified state
|
|
609
|
+
modified = copy.deepcopy(current)
|
|
610
|
+
|
|
611
|
+
# Check if instance ID is already in use (if specified)
|
|
612
|
+
if instance_id is not None:
|
|
613
|
+
existing_ids = {
|
|
614
|
+
inst.id for inst in modified.instances.values() if inst.id is not None
|
|
615
|
+
}
|
|
616
|
+
if instance_id in existing_ids:
|
|
617
|
+
# Find which instance uses this ID
|
|
618
|
+
for inst_name, inst in modified.instances.items():
|
|
619
|
+
if inst.id == instance_id:
|
|
620
|
+
raise ResourceError(
|
|
621
|
+
f"Instance ID {instance_id} is already in use "
|
|
622
|
+
f"by instance '{inst_name}'"
|
|
623
|
+
)
|
|
624
|
+
final_instance_id = instance_id
|
|
625
|
+
else:
|
|
626
|
+
final_instance_id = None
|
|
627
|
+
|
|
628
|
+
# Allocate CPUs based on specification
|
|
629
|
+
if is_count:
|
|
630
|
+
# Allocate CPUs automatically from available pool with topology awareness
|
|
631
|
+
cpu_list = allocate_cpus_from_pool(
|
|
632
|
+
modified,
|
|
633
|
+
cpu_spec_value, # cpu_spec_value is int (count)
|
|
634
|
+
cpu_affinity=cpu_affinity,
|
|
635
|
+
numa_nodes=numa_node_list,
|
|
636
|
+
)
|
|
637
|
+
else:
|
|
638
|
+
# Use explicitly specified CPUs
|
|
639
|
+
cpu_list = cpu_spec_value # cpu_spec_value is List[int]
|
|
640
|
+
|
|
641
|
+
# Validate CPU allocation (against baseline and existing instances)
|
|
642
|
+
validate_cpu_allocation(modified, cpu_list)
|
|
643
|
+
|
|
644
|
+
# Find memory base if not specified
|
|
645
|
+
if memory_base_addr is None:
|
|
646
|
+
found_base = find_available_memory_base(modified, memory_bytes)
|
|
647
|
+
if found_base is None:
|
|
648
|
+
raise ResourceError(
|
|
649
|
+
f"No available memory region found for {memory_bytes} bytes. "
|
|
650
|
+
"Try specifying --memory-base or reduce memory size."
|
|
651
|
+
)
|
|
652
|
+
memory_base_addr = found_base
|
|
653
|
+
else:
|
|
654
|
+
# Validate specified memory base
|
|
655
|
+
validate_memory_allocation(modified, memory_base_addr, memory_bytes)
|
|
656
|
+
|
|
657
|
+
# Create instance resources with topology settings
|
|
658
|
+
uring_enabled = uring or uring_sq_entries is not None or uring_cq_entries is not None or uring_shim_pages is not None
|
|
659
|
+
resources = InstanceResources(
|
|
660
|
+
cpus=cpu_list,
|
|
661
|
+
memory_base=memory_base_addr,
|
|
662
|
+
memory_bytes=memory_bytes,
|
|
663
|
+
devices=device_list,
|
|
664
|
+
numa_nodes=numa_node_list,
|
|
665
|
+
cpu_affinity=cpu_affinity,
|
|
666
|
+
memory_policy=memory_policy,
|
|
667
|
+
uring=uring_enabled,
|
|
668
|
+
uring_sq_entries=uring_sq_entries or (256 if uring_enabled else None),
|
|
669
|
+
uring_cq_entries=uring_cq_entries or (256 if uring_enabled else None),
|
|
670
|
+
uring_shim_pages=uring_shim_pages or (64 if uring_enabled else None),
|
|
671
|
+
)
|
|
672
|
+
|
|
673
|
+
options = None
|
|
674
|
+
if enable_host_kcore:
|
|
675
|
+
options = {"enable-host-kcore": True}
|
|
676
|
+
|
|
677
|
+
# Create instance
|
|
678
|
+
instance = Instance(
|
|
679
|
+
name=name, id=final_instance_id, resources=resources, options=options
|
|
680
|
+
)
|
|
681
|
+
|
|
682
|
+
# Add to modified state
|
|
683
|
+
modified.instances[name] = instance
|
|
684
|
+
|
|
685
|
+
return modified
|
|
686
|
+
|
|
687
|
+
# Validate only (dry-run)
|
|
688
|
+
if dry_run:
|
|
689
|
+
try:
|
|
690
|
+
current = manager.read_baseline()
|
|
691
|
+
modified = create_instance_operation(current)
|
|
692
|
+
|
|
693
|
+
# Get instance details from modified tree
|
|
694
|
+
instance = modified.instances[name]
|
|
695
|
+
|
|
696
|
+
click.echo(f"ā Validation passed for instance '{name}'")
|
|
697
|
+
if is_count:
|
|
698
|
+
cpus_str = ", ".join(map(str, instance.resources.cpus))
|
|
699
|
+
click.echo(f" CPUs: {cpu_spec_value} CPUs auto-allocated: {cpus_str}")
|
|
700
|
+
else:
|
|
701
|
+
click.echo(f" CPUs: {', '.join(map(str, instance.resources.cpus))}")
|
|
702
|
+
if instance.resources.cpu_affinity:
|
|
703
|
+
click.echo(f" CPU Affinity: {instance.resources.cpu_affinity}")
|
|
704
|
+
if instance.resources.numa_nodes:
|
|
705
|
+
click.echo(
|
|
706
|
+
f" NUMA Nodes: {', '.join(map(str, instance.resources.numa_nodes))}"
|
|
707
|
+
)
|
|
708
|
+
click.echo(f" Memory: {memory} at {hex(instance.resources.memory_base)}")
|
|
709
|
+
if instance.resources.memory_policy:
|
|
710
|
+
click.echo(f" Memory Policy: {instance.resources.memory_policy}")
|
|
711
|
+
if instance.resources.devices:
|
|
712
|
+
click.echo(f" Devices: {', '.join(instance.resources.devices)}")
|
|
713
|
+
click.echo(f" Instance ID: {instance.id}")
|
|
714
|
+
|
|
715
|
+
if debug:
|
|
716
|
+
dump_overlay_for_debug(manager, current, modified, name, suffix="_dryrun")
|
|
717
|
+
click.echo() # Add blank line after debug output
|
|
718
|
+
|
|
719
|
+
click.echo("\nā Instance would be created (dry-run mode)")
|
|
720
|
+
click.echo(" Remove --dry-run to apply overlay to kernel")
|
|
721
|
+
except (ResourceError, ValidationError) as e:
|
|
722
|
+
click.echo(f"Error: {e}", err=True)
|
|
723
|
+
sys.exit(1)
|
|
724
|
+
except (KernelInterfaceError, ParseError) as e:
|
|
725
|
+
click.echo(f"Error: {e}", err=True)
|
|
726
|
+
sys.exit(1)
|
|
727
|
+
return
|
|
728
|
+
|
|
729
|
+
try:
|
|
730
|
+
if debug:
|
|
731
|
+
current = manager.read_baseline()
|
|
732
|
+
modified = create_instance_operation(current)
|
|
733
|
+
dump_overlay_for_debug(manager, current, modified, name)
|
|
734
|
+
|
|
735
|
+
tx_id = manager.apply_operation(create_instance_operation)
|
|
736
|
+
|
|
737
|
+
click.echo(f"ā Created instance '{name}' (transaction {tx_id})")
|
|
738
|
+
if verbose:
|
|
739
|
+
current = manager.read_baseline()
|
|
740
|
+
instance = current.instances[name]
|
|
741
|
+
click.echo(f" Instance ID: {instance.id}")
|
|
742
|
+
click.echo(f" CPUs: {', '.join(map(str, instance.resources.cpus))}")
|
|
743
|
+
if instance.resources.cpu_affinity:
|
|
744
|
+
click.echo(f" CPU Affinity: {instance.resources.cpu_affinity}")
|
|
745
|
+
if instance.resources.numa_nodes:
|
|
746
|
+
numa_str = ", ".join(map(str, instance.resources.numa_nodes))
|
|
747
|
+
click.echo(f" NUMA Nodes: {numa_str}")
|
|
748
|
+
click.echo(f" Memory: {memory} at {hex(instance.resources.memory_base)}")
|
|
749
|
+
if instance.resources.memory_policy:
|
|
750
|
+
click.echo(f" Memory Policy: {instance.resources.memory_policy}")
|
|
751
|
+
if instance.resources.devices:
|
|
752
|
+
click.echo(f" Devices: {', '.join(instance.resources.devices)}")
|
|
753
|
+
except ResourceError as e:
|
|
754
|
+
click.echo(f"Error: Resource allocation failed: {e}", err=True)
|
|
755
|
+
if verbose:
|
|
756
|
+
traceback.print_exc()
|
|
757
|
+
sys.exit(1)
|
|
758
|
+
except ValidationError as e:
|
|
759
|
+
click.echo(f"Error: Validation failed: {e}", err=True)
|
|
760
|
+
if verbose:
|
|
761
|
+
traceback.print_exc()
|
|
762
|
+
sys.exit(1)
|
|
763
|
+
except KernelInterfaceError as e:
|
|
764
|
+
click.echo(f"Error: Kernel interface error: {e}", err=True)
|
|
765
|
+
if verbose:
|
|
766
|
+
traceback.print_exc()
|
|
767
|
+
sys.exit(1)
|
|
768
|
+
|
|
769
|
+
except KeyboardInterrupt:
|
|
770
|
+
click.echo("\nOperation cancelled", err=True)
|
|
771
|
+
sys.exit(130)
|
|
772
|
+
except (RuntimeError, OSError) as e:
|
|
773
|
+
click.echo(f"Unexpected error: {e}", err=True)
|
|
774
|
+
if verbose:
|
|
775
|
+
traceback.print_exc()
|
|
776
|
+
sys.exit(1)
|
|
777
|
+
|
|
778
|
+
|
|
779
|
+
if __name__ == "__main__":
|
|
780
|
+
create() # pylint: disable=no-value-for-parameter
|