kerf-multikernel 0.1.0__tar.gz → 0.3.0__tar.gz

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.
Files changed (54) hide show
  1. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/PKG-INFO +34 -18
  2. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/README.md +33 -16
  3. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/pyproject.toml +1 -2
  4. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/__init__.py +3 -3
  5. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/cli.py +3 -1
  6. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/create/main.py +91 -31
  7. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/data/kerf-init +0 -0
  8. kerf_multikernel-0.3.0/src/kerf/devices.py +87 -0
  9. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/dtc/extractor.py +21 -75
  10. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/dtc/overlay.py +138 -138
  11. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/dtc/parser.py +213 -716
  12. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/dtc/reporter.py +9 -4
  13. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/dtc/validator.py +42 -92
  14. kerf_multikernel-0.3.0/src/kerf/dump/__init__.py +20 -0
  15. kerf_multikernel-0.3.0/src/kerf/dump/main.py +86 -0
  16. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/exec/main.py +0 -3
  17. kerf_multikernel-0.3.0/src/kerf/init/main.py +1179 -0
  18. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/kill/main.py +8 -1
  19. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/models.py +49 -6
  20. kerf_multikernel-0.3.0/src/kerf/pool_diff.py +111 -0
  21. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/resources.py +96 -97
  22. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/runtime.py +86 -97
  23. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/show/main.py +59 -35
  24. kerf_multikernel-0.3.0/src/kerf/topology.py +139 -0
  25. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/update/main.py +63 -167
  26. kerf_multikernel-0.1.0/src/kerf/init/main.py +0 -696
  27. kerf_multikernel-0.1.0/src/kerf/lazy_cma.py +0 -132
  28. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/LICENSE +0 -0
  29. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/baseline.py +0 -0
  30. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/console/__init__.py +0 -0
  31. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/console/main.py +0 -0
  32. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/create/__init__.py +0 -0
  33. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/data/__init__.py +0 -0
  34. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/daxfs/__init__.py +0 -0
  35. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/daxfs/mkdaxfs.py +0 -0
  36. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/delete/__init__.py +0 -0
  37. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/delete/main.py +0 -0
  38. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/docker/__init__.py +0 -0
  39. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/docker/image.py +0 -0
  40. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/dtc/__init__.py +0 -0
  41. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/dtc/cells.py +0 -0
  42. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/exceptions.py +0 -0
  43. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/exec/__init__.py +0 -0
  44. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/init/__init__.py +0 -0
  45. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/kill/__init__.py +0 -0
  46. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/load/__init__.py +0 -0
  47. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/load/main.py +0 -0
  48. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/metadata.py +0 -0
  49. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/show/__init__.py +0 -0
  50. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/unload/__init__.py +0 -0
  51. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/unload/main.py +0 -0
  52. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/update/__init__.py +0 -0
  53. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/utils.py +0 -0
  54. {kerf_multikernel-0.1.0 → kerf_multikernel-0.3.0}/src/kerf/vmlinuz.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: kerf-multikernel
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: Multikernel Management CLI tool
5
5
  Author: Cong Wang
6
6
  Requires-Python: >=3.9,<4.0
@@ -14,7 +14,6 @@ Requires-Dist: click (>=8.0.0,<9.0.0)
14
14
  Requires-Dist: pylibfdt (>=1.7.0,<2.0.0)
15
15
  Requires-Dist: pyudev (>=0.24.0,<0.25.0)
16
16
  Requires-Dist: pyyaml (>=6.0,<7.0)
17
- Requires-Dist: rdtsc (>=0.2.1,<0.3.0)
18
17
  Description-Content-Type: text/markdown
19
18
 
20
19
  ![Kerf Logo](logo.png)
@@ -146,11 +145,19 @@ Baseline DTB (static)
146
145
 
147
146
  ### Command Line Interface
148
147
  ```bash
149
- # Initialize resource pool with CPUs (memory parsed from /proc/iomem)
150
- kerf init --cpus=4-7
148
+ # Initialize resource pool with CPUs and pool memory
149
+ # A plain size lands on the NUMA node of the requested CPUs
150
+ kerf init --cpus=4-7 --memory=2GB
151
151
 
152
- # Initialize with CPUs and devices
153
- kerf init --cpus=4-31 --devices=enp9s0_dev,nvme0
152
+ # Initialize with CPUs, per-node memory and devices
153
+ kerf init --cpus=4-31 --memory=8GB@0,8GB@1 --devices=nvme0n1,enp9s0
154
+
155
+ # Re-run to reshape the live pool; "none" asks for none of a resource
156
+ kerf init --cpus=4-15 --memory=4GB
157
+ kerf init --cpus=4-15 --memory=none
158
+
159
+ # Hand everything back to the host
160
+ kerf init --cpus=none --memory=none
154
161
 
155
162
  # Create kernel instance with resource allocation
156
163
  kerf create web-server --cpus=4-7 --memory=2GB
@@ -167,6 +174,11 @@ kerf exec web-server
167
174
  kerf show
168
175
  kerf show web-server
169
176
 
177
+ # Dump the device tree the kernel holds: DTB to replay, --dts to read
178
+ kerf dump -o host.dtb
179
+ kerf dump web-server -o web.dtb
180
+ kerf dump web-server --dts
181
+
170
182
  # Shutdown a running kernel instance
171
183
  kerf kill web-server
172
184
 
@@ -345,22 +357,26 @@ pip install -e .
345
357
  kerf --help
346
358
  kerf init --help
347
359
 
348
- # Try with example baseline configuration
349
- kerf init --input=examples/baseline.dts --report
360
+ # Carve a pool out of the host: 7 CPUs (by APIC ID) and 1GB on their NUMA node
361
+ sudo kerf init --cpus=128-134 --memory=1GB --report
350
362
  ```
351
363
 
352
- ## Examples
364
+ ### Reusing a Dumped Baseline
353
365
 
354
- The `examples/` directory contains sample baseline Device Tree Source (DTS) files demonstrating various hardware resource configurations:
366
+ `kerf dump` writes the device tree the kernel holds, byte for byte, and
367
+ `kerf init --input` and `kerf create --input` accept it back. This is the
368
+ supported way to capture a configuration and replay it later or on another
369
+ host; hand-written device tree files are not supported. An instance dump
370
+ carries its CPUs, memory size, devices and id; options such as --uring and
371
+ --enable-host-kcore are given again on the command line.
355
372
 
356
- - **`baseline.dts`** - Complete baseline with CPU, memory, and device resources (32 CPUs, 16GB memory)
357
- - **`minimal.dts`** - Simple baseline for testing and development (8 CPUs, 8GB memory)
358
- - **`edge_computing.dts`** - Edge computing baseline with GPU support for AI inference (16 CPUs, 32GB memory)
359
- - **`numa_topology.dts`** - Advanced NUMA topology baseline with 4 NUMA nodes and topology-aware allocation
360
- - **`system.dts`** - Example baseline with various device configurations
361
- - **`conflict_example.dts`** - Intentionally invalid baseline demonstrating common validation errors
362
-
363
- **Note**: All baseline files contain **only** hardware resources - no instances. Instances are created dynamically via overlays using `kerf create` command.
373
+ ```bash
374
+ sudo kerf dump -o host.dtb # baseline
375
+ sudo kerf dump web-server -o web.dtb # a running instance
376
+ sudo kerf init --input=host.dtb # replay the baseline
377
+ sudo kerf create --input=web.dtb # recreate the instance
378
+ sudo kerf dump --dts # read it; text is not replayable
379
+ ```
364
380
 
365
381
  ## CPU and NUMA Topology Support
366
382
 
@@ -127,11 +127,19 @@ Baseline DTB (static)
127
127
 
128
128
  ### Command Line Interface
129
129
  ```bash
130
- # Initialize resource pool with CPUs (memory parsed from /proc/iomem)
131
- kerf init --cpus=4-7
130
+ # Initialize resource pool with CPUs and pool memory
131
+ # A plain size lands on the NUMA node of the requested CPUs
132
+ kerf init --cpus=4-7 --memory=2GB
132
133
 
133
- # Initialize with CPUs and devices
134
- kerf init --cpus=4-31 --devices=enp9s0_dev,nvme0
134
+ # Initialize with CPUs, per-node memory and devices
135
+ kerf init --cpus=4-31 --memory=8GB@0,8GB@1 --devices=nvme0n1,enp9s0
136
+
137
+ # Re-run to reshape the live pool; "none" asks for none of a resource
138
+ kerf init --cpus=4-15 --memory=4GB
139
+ kerf init --cpus=4-15 --memory=none
140
+
141
+ # Hand everything back to the host
142
+ kerf init --cpus=none --memory=none
135
143
 
136
144
  # Create kernel instance with resource allocation
137
145
  kerf create web-server --cpus=4-7 --memory=2GB
@@ -148,6 +156,11 @@ kerf exec web-server
148
156
  kerf show
149
157
  kerf show web-server
150
158
 
159
+ # Dump the device tree the kernel holds: DTB to replay, --dts to read
160
+ kerf dump -o host.dtb
161
+ kerf dump web-server -o web.dtb
162
+ kerf dump web-server --dts
163
+
151
164
  # Shutdown a running kernel instance
152
165
  kerf kill web-server
153
166
 
@@ -326,22 +339,26 @@ pip install -e .
326
339
  kerf --help
327
340
  kerf init --help
328
341
 
329
- # Try with example baseline configuration
330
- kerf init --input=examples/baseline.dts --report
342
+ # Carve a pool out of the host: 7 CPUs (by APIC ID) and 1GB on their NUMA node
343
+ sudo kerf init --cpus=128-134 --memory=1GB --report
331
344
  ```
332
345
 
333
- ## Examples
346
+ ### Reusing a Dumped Baseline
334
347
 
335
- The `examples/` directory contains sample baseline Device Tree Source (DTS) files demonstrating various hardware resource configurations:
348
+ `kerf dump` writes the device tree the kernel holds, byte for byte, and
349
+ `kerf init --input` and `kerf create --input` accept it back. This is the
350
+ supported way to capture a configuration and replay it later or on another
351
+ host; hand-written device tree files are not supported. An instance dump
352
+ carries its CPUs, memory size, devices and id; options such as --uring and
353
+ --enable-host-kcore are given again on the command line.
336
354
 
337
- - **`baseline.dts`** - Complete baseline with CPU, memory, and device resources (32 CPUs, 16GB memory)
338
- - **`minimal.dts`** - Simple baseline for testing and development (8 CPUs, 8GB memory)
339
- - **`edge_computing.dts`** - Edge computing baseline with GPU support for AI inference (16 CPUs, 32GB memory)
340
- - **`numa_topology.dts`** - Advanced NUMA topology baseline with 4 NUMA nodes and topology-aware allocation
341
- - **`system.dts`** - Example baseline with various device configurations
342
- - **`conflict_example.dts`** - Intentionally invalid baseline demonstrating common validation errors
343
-
344
- **Note**: All baseline files contain **only** hardware resources - no instances. Instances are created dynamically via overlays using `kerf create` command.
355
+ ```bash
356
+ sudo kerf dump -o host.dtb # baseline
357
+ sudo kerf dump web-server -o web.dtb # a running instance
358
+ sudo kerf init --input=host.dtb # replay the baseline
359
+ sudo kerf create --input=web.dtb # recreate the instance
360
+ sudo kerf dump --dts # read it; text is not replayable
361
+ ```
345
362
 
346
363
  ## CPU and NUMA Topology Support
347
364
 
@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
4
4
 
5
5
  [tool.poetry]
6
6
  name = "kerf-multikernel"
7
- version = "0.1.0"
7
+ version = "0.3.0"
8
8
  description = "Multikernel Management CLI tool"
9
9
  authors = ["Cong Wang"]
10
10
  readme = "README.md"
@@ -19,7 +19,6 @@ pylibfdt = "^1.7.0"
19
19
  click = "^8.0.0"
20
20
  pyyaml = "^6.0"
21
21
  pyudev = "^0.24.0"
22
- rdtsc = "^0.2.1"
23
22
 
24
23
  [tool.poetry.group.dev.dependencies]
25
24
  pytest = "^7.0.0"
@@ -19,7 +19,7 @@ A comprehensive multikernel management system designed to orchestrate
19
19
  and manage multiple kernel instances on a single host.
20
20
  """
21
21
 
22
- __version__ = "0.1.0"
22
+ __version__ = "0.3.0"
23
23
  __author__ = "Cong Wang"
24
24
 
25
25
  # Export main runtime components for easy access
@@ -41,7 +41,7 @@ from .resources import (
41
41
  get_available_cpus,
42
42
  get_allocated_cpus,
43
43
  get_allocated_memory_regions,
44
- find_available_memory_base,
44
+ chunk_containing,
45
45
  validate_cpu_allocation,
46
46
  validate_memory_allocation,
47
47
  find_next_instance_id,
@@ -67,7 +67,7 @@ __all__ = [
67
67
  "get_available_cpus",
68
68
  "get_allocated_cpus",
69
69
  "get_allocated_memory_regions",
70
- "find_available_memory_base",
70
+ "chunk_containing",
71
71
  "validate_cpu_allocation",
72
72
  "validate_memory_allocation",
73
73
  "find_next_instance_id",
@@ -26,11 +26,12 @@ from .kill.main import kill_cmd
26
26
  from .unload.main import unload
27
27
  from .delete.main import delete
28
28
  from .show.main import show
29
+ from .dump.main import dump
29
30
  from .console.main import console
30
31
 
31
32
 
32
33
  @click.group()
33
- @click.version_option(version="0.1.0", prog_name="kerf")
34
+ @click.version_option(version="0.3.0", prog_name="kerf")
34
35
  @click.option("--debug", is_flag=True, help="Enable debug mode")
35
36
  @click.pass_context
36
37
  def main(ctx, debug):
@@ -49,6 +50,7 @@ main.add_command(kill_cmd)
49
50
  main.add_command(unload)
50
51
  main.add_command(delete)
51
52
  main.add_command(show)
53
+ main.add_command(dump)
52
54
  main.add_command(console)
53
55
 
54
56
 
@@ -23,15 +23,16 @@ creating an overlay and applying it to the kernel.
23
23
  import copy
24
24
  import sys
25
25
  import traceback
26
+ from pathlib import Path
26
27
  from typing import List, Optional
27
28
  import click
28
29
 
29
30
  from ..runtime import DeviceTreeManager
31
+ from ..dtc.parser import DeviceTreeParser, is_dts_text
30
32
  from ..models import Instance, InstanceResources
31
33
  from ..resources import (
32
34
  validate_cpu_allocation,
33
35
  validate_memory_allocation,
34
- find_available_memory_base,
35
36
  get_available_cpus,
36
37
  )
37
38
  from ..exceptions import ValidationError, KernelInterfaceError, ResourceError, ParseError
@@ -302,6 +303,12 @@ def parse_memory_spec(memory_spec: str) -> int:
302
303
  ) from exc
303
304
 
304
305
 
306
+ def _placement(instance) -> str:
307
+ """Name the base only when one was asked for; the kernel picks otherwise."""
308
+ base = instance.resources.memory_base
309
+ return f" at {hex(base)}" if base else ""
310
+
311
+
305
312
  def parse_memory_base(base_spec: str) -> int:
306
313
  """
307
314
  Parse memory base address specification.
@@ -334,19 +341,16 @@ def parse_memory_base(base_spec: str) -> int:
334
341
 
335
342
  def parse_device_list(device_spec: Optional[str]) -> List[str]:
336
343
  """
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)
344
+ Parse device specification string into list of device references.
342
345
 
343
- Device names must match device node names in the baseline DTB.
346
+ A reference is an alias ("nvme0"), a PCI address ("0000:4f:01.0") or a
347
+ device node name ("pci_0000_4f_01_0") from the baseline, comma-separated.
344
348
 
345
349
  Args:
346
- device_spec: Device specification string or None (device names, comma-separated)
350
+ device_spec: Device specification string or None
347
351
 
348
352
  Returns:
349
- List of device name strings (e.g., ["enp9s0_dev", "nvme0"])
353
+ List of device references (e.g., ["nvme0", "0000:09:00.0"])
350
354
  """
351
355
  if not device_spec:
352
356
  return []
@@ -371,9 +375,7 @@ def dump_overlay_for_debug(
371
375
  dtbo_data = manager.overlay_gen.generate_overlay(current, modified)
372
376
 
373
377
  try:
374
- # pylint: disable=import-outside-toplevel
375
- from ..dtc.parser import DeviceTreeParser
376
- import libfdt # pylint: disable=import-error
378
+ import libfdt # pylint: disable=import-error,import-outside-toplevel
377
379
 
378
380
  fdt = libfdt.Fdt(dtbo_data)
379
381
  parser = DeviceTreeParser()
@@ -428,17 +430,27 @@ def dump_overlay_for_debug(
428
430
  "interleave (across NUMA nodes), or bind (specific NUMA nodes)",
429
431
  )
430
432
  @click.option(
431
- "--memory", "-m", required=True, help='Memory allocation (e.g., "2GB", "2048MB", or bytes)'
433
+ "--memory", "-m", help='Memory allocation (e.g., "2GB", "2048MB", or bytes)'
432
434
  )
433
435
  @click.option(
434
436
  "--memory-base",
435
- help="Memory base address (hex: 0x80000000 or decimal, auto-assigned if not specified)",
437
+ help="Memory base address to request (hex: 0x80000000 or decimal). "
438
+ "Only checked against the pool; the kernel places instance memory itself.",
436
439
  )
437
440
  @click.option(
438
441
  "--devices",
439
442
  "-d",
440
- help='Device names (comma-separated, e.g., "enp9s0_dev,nvme0"). '
441
- "Device names must match device node names in the baseline DTB.",
443
+ help='Pool devices to assign, by alias, PCI address or node name '
444
+ '(comma-separated, e.g. "nvme0,0000:09:00.0"), as listed by kerf show.',
445
+ )
446
+ @click.option(
447
+ "--input",
448
+ "-i",
449
+ "input_path",
450
+ type=click.Path(exists=True, dir_okay=False),
451
+ help="Replay an instance dumped with 'kerf dump NAME -o FILE': its CPUs, memory "
452
+ "size, devices and id, unless overridden by NAME or --id. The memory base is "
453
+ "left to the kernel. Mutually exclusive with the resource options above.",
442
454
  )
443
455
  @click.option(
444
456
  "--enable-host-kcore", is_flag=True, help="Enable host kcore access for this instance"
@@ -461,6 +473,7 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
461
473
  memory: str,
462
474
  memory_base: Optional[str],
463
475
  devices: Optional[str],
476
+ input_path: Optional[str],
464
477
  enable_host_kcore: bool,
465
478
  uring: bool,
466
479
  uring_sq_entries: Optional[int],
@@ -491,7 +504,7 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
491
504
  kerf create database --cpus=128-142 --memory=8GB --memory-base=0x100000000
492
505
 
493
506
  # Create instance with devices
494
- kerf create compute --cpus=128-142 --memory=4GB --devices=enp9s0_dev
507
+ kerf create compute --cpus=128-142 --memory=4GB --devices=enp9s0
495
508
 
496
509
  # Create instance with explicit single APIC ID
497
510
  kerf create web-server --cpus=128 --memory=2GB
@@ -507,6 +520,9 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
507
520
 
508
521
  # Validate without applying
509
522
  kerf create web-server --cpu-count=4 --memory=2GB --dry-run
523
+
524
+ # Recreate an instance from 'kerf dump web-server -o web.dtb'
525
+ kerf create --input=web.dtb
510
526
  """
511
527
  try:
512
528
  if name is None and ctx is not None:
@@ -518,6 +534,46 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
518
534
  name = arg
519
535
  break
520
536
 
537
+ dumped = None
538
+ if input_path:
539
+ given = [
540
+ flag
541
+ for flag, value in (
542
+ ("--cpus", cpus),
543
+ ("--cpu-count", cpu_count),
544
+ ("--memory", memory),
545
+ ("--memory-base", memory_base),
546
+ ("--devices", devices),
547
+ ("--numa-nodes", numa_nodes),
548
+ ("--memory-policy", memory_policy),
549
+ )
550
+ if value is not None
551
+ ]
552
+ if given:
553
+ click.echo(
554
+ f"Error: --input is mutually exclusive with {', '.join(given)}; "
555
+ "the dump supplies those.",
556
+ err=True,
557
+ )
558
+ sys.exit(2)
559
+ if is_dts_text(Path(input_path)):
560
+ click.echo(f"Error: {input_path} is DTS text; only the DTB from 'kerf dump' "
561
+ "(without --dts) can be replayed.", err=True)
562
+ sys.exit(2)
563
+ try:
564
+ dumped = DeviceTreeParser().parse_instance_dtb_from_bytes(
565
+ Path(input_path).read_bytes()
566
+ )
567
+ except ParseError as e:
568
+ click.echo(f"Error: {input_path} is not an instance dump: {e}", err=True)
569
+ sys.exit(2)
570
+ name = name or dumped.name
571
+ if instance_id is None:
572
+ instance_id = dumped.id
573
+ cpus = ",".join(map(str, dumped.resources.cpus))
574
+ memory = str(dumped.resources.memory_bytes)
575
+ devices = ",".join(dumped.resources.devices) or None
576
+
521
577
  # Validate name is provided
522
578
  if not name:
523
579
  click.echo("Error: Instance name is required", err=True)
@@ -525,6 +581,10 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
525
581
  click.echo(" kerf create [OPTIONS] <name>", err=True)
526
582
  sys.exit(2)
527
583
 
584
+ if memory is None:
585
+ click.echo("Error: --memory is required unless --input is given", err=True)
586
+ sys.exit(2)
587
+
528
588
  # Validate that exactly one of --cpus or --cpu-count is provided
529
589
  if cpus and cpu_count is not None:
530
590
  click.echo(
@@ -641,26 +701,27 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
641
701
  # Validate CPU allocation (against baseline and existing instances)
642
702
  validate_cpu_allocation(modified, cpu_list)
643
703
 
644
- # Find memory base if not specified
704
+ # The kernel places instance memory itself; a base is only ever
705
+ # a caller's request, so it is all there is to validate.
645
706
  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
707
+ memory_base_addr = 0
653
708
  else:
654
- # Validate specified memory base
655
709
  validate_memory_allocation(modified, memory_base_addr, memory_bytes)
656
710
 
711
+ device_nodes = []
712
+ for ref in device_list:
713
+ node = modified.hardware.find_device(ref)
714
+ if node is None:
715
+ raise ResourceError(f"Device '{ref}' is not in the pool")
716
+ device_nodes.append(node)
717
+
657
718
  # Create instance resources with topology settings
658
719
  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
720
  resources = InstanceResources(
660
721
  cpus=cpu_list,
661
722
  memory_base=memory_base_addr,
662
723
  memory_bytes=memory_bytes,
663
- devices=device_list,
724
+ devices=device_nodes,
664
725
  numa_nodes=numa_node_list,
665
726
  cpu_affinity=cpu_affinity,
666
727
  memory_policy=memory_policy,
@@ -705,7 +766,7 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
705
766
  click.echo(
706
767
  f" NUMA Nodes: {', '.join(map(str, instance.resources.numa_nodes))}"
707
768
  )
708
- click.echo(f" Memory: {memory} at {hex(instance.resources.memory_base)}")
769
+ click.echo(f" Memory: {memory}{_placement(instance)}")
709
770
  if instance.resources.memory_policy:
710
771
  click.echo(f" Memory Policy: {instance.resources.memory_policy}")
711
772
  if instance.resources.devices:
@@ -736,8 +797,7 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
736
797
 
737
798
  click.echo(f"✓ Created instance '{name}' (transaction {tx_id})")
738
799
  if verbose:
739
- current = manager.read_baseline()
740
- instance = current.instances[name]
800
+ instance = manager.read_instance(name)
741
801
  click.echo(f" Instance ID: {instance.id}")
742
802
  click.echo(f" CPUs: {', '.join(map(str, instance.resources.cpus))}")
743
803
  if instance.resources.cpu_affinity:
@@ -745,7 +805,7 @@ def create( # pylint: disable=too-many-arguments,too-many-positional-arguments
745
805
  if instance.resources.numa_nodes:
746
806
  numa_str = ", ".join(map(str, instance.resources.numa_nodes))
747
807
  click.echo(f" NUMA Nodes: {numa_str}")
748
- click.echo(f" Memory: {memory} at {hex(instance.resources.memory_base)}")
808
+ click.echo(f" Memory: {memory}{_placement(instance)}")
749
809
  if instance.resources.memory_policy:
750
810
  click.echo(f" Memory Policy: {instance.resources.memory_policy}")
751
811
  if instance.resources.devices:
@@ -0,0 +1,87 @@
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
+ Naming of pool PCI devices.
17
+
18
+ A pool device is identified by its PCI address and nothing else: host
19
+ names such as nvme0n1 or enp9s0 are probe-order or udev artifacts that
20
+ differ between kernels, while the address is fixed by the fabric. The
21
+ device node is named after the address, and a standard device tree
22
+ /aliases entry gives the device a stable name: the name the device has in
23
+ the kernel that owns it, which a spawned kernel then applies ("nvme0"
24
+ stays nvme0 and its namespaces nvme0n1, "enp9s0" stays enp9s0).
25
+ """
26
+
27
+ import re
28
+ from typing import Optional, Tuple
29
+
30
+ PCI_ID_RE = re.compile(r'^([0-9a-fA-F]{1,4}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2})\.([0-9a-fA-F])$')
31
+ PCI_NODE_RE = re.compile(r'^pci_([0-9a-fA-F]{1,4})_([0-9a-fA-F]{1,2})_([0-9a-fA-F]{1,2})_([0-9a-fA-F])$')
32
+ ALIAS_RE = re.compile(r'^[a-z0-9-]{1,31}$')
33
+ NVME_NAME_RE = re.compile(r'^(nvme\d+)(?:n\d+(p\d+)?)?$')
34
+ IFNAMSIZ = 16
35
+
36
+
37
+ def normalize_pci_id(text: str) -> Optional[str]:
38
+ """Canonical "dddd:bb:ss.f" for a PCI address or the node name derived from one."""
39
+ match = PCI_ID_RE.match(text) or PCI_NODE_RE.match(text)
40
+ if not match:
41
+ return None
42
+ domain, bus, slot, func = (int(part, 16) for part in match.groups())
43
+ return f"{domain:04x}:{bus:02x}:{slot:02x}.{func:x}"
44
+
45
+
46
+ def pci_node_name(pci_id: str) -> str:
47
+ """Device node name for a PCI address, as the kernel derives it."""
48
+ normalized = normalize_pci_id(pci_id)
49
+ if normalized is None:
50
+ raise ValueError(f"Invalid PCI ID '{pci_id}', expected DDDD:BB:SS.F")
51
+ return "pci_" + normalized.replace(":", "_").replace(".", "_")
52
+
53
+
54
+ def split_alias(entry: str) -> Tuple[str, Optional[str]]:
55
+ """Split a "device" or "device=alias" request into its parts."""
56
+ name, sep, alias = entry.partition("=")
57
+ if not sep:
58
+ return name, None
59
+ if not ALIAS_RE.match(alias):
60
+ raise ValueError(
61
+ f"Invalid alias '{alias}' for device '{name}': "
62
+ "use 1 to 31 characters from a-z, 0-9 and '-', like nvme0 or enp9s0"
63
+ )
64
+ return name, alias
65
+
66
+
67
+ def is_partition(host_name: str) -> bool:
68
+ match = NVME_NAME_RE.match(host_name)
69
+ return bool(match and match.group(2))
70
+
71
+
72
+ def default_alias(host_name: str, compatible: Optional[str]) -> Optional[str]:
73
+ """
74
+ The alias a host device name implies, None when it implies nothing.
75
+
76
+ An NVMe name carries its controller name, which the namespaces follow.
77
+ A network interface name is the alias itself, when the kernel can
78
+ apply it. A raw PCI address implies no name at all.
79
+ """
80
+ if normalize_pci_id(host_name):
81
+ return None
82
+ match = NVME_NAME_RE.match(host_name)
83
+ if match:
84
+ return match.group(1)
85
+ if compatible == "pci-network" and ALIAS_RE.match(host_name) and len(host_name) < IFNAMSIZ:
86
+ return host_name
87
+ return None