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/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