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/update/main.py ADDED
@@ -0,0 +1,450 @@
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
+ Update kernel instance resources.
17
+
18
+ This command updates hardware resources of an existing kernel instance.
19
+ The underlying DTS overlay processes operations in a specific order to ensure
20
+ clean resource migration:
21
+ 1. memory-remove - Remove memory from instance first
22
+ 2. memory-add - Then add memory to instance
23
+ 3. cpu-remove - Remove CPU from instance first
24
+ 4. cpu-add - Then add CPU to instance
25
+ """
26
+
27
+ import sys
28
+ import copy
29
+ from typing import Optional, List
30
+ import click
31
+
32
+ from ..create.main import parse_cpu_spec, parse_memory_base, parse_memory_spec
33
+ from ..exceptions import KernelInterfaceError, ParseError, ResourceError, ValidationError
34
+ from ..resources import (
35
+ find_available_memory_base,
36
+ validate_cpu_allocation,
37
+ validate_memory_allocation,
38
+ )
39
+ from ..runtime import DeviceTreeManager
40
+
41
+
42
+ def parse_device_spec(device_spec: str) -> List[str]:
43
+ """Parse device specification string into list of PCI IDs."""
44
+ if not device_spec:
45
+ return []
46
+
47
+ devices = [d.strip() for d in device_spec.split(',') if d.strip()]
48
+
49
+ # Validate PCI ID format (basic validation)
50
+ import re
51
+ pci_pattern = re.compile(r'^[0-9a-fA-F]{4}:[0-9a-fA-F]{2}:[0-9a-fA-F]{2}\.[0-9a-fA-F]$')
52
+ for device in devices:
53
+ if not pci_pattern.match(device):
54
+ raise ValueError(f"Invalid PCI ID format: {device}. Expected format: 0000:09:00.0")
55
+
56
+ return devices
57
+
58
+
59
+ def dump_overlay_for_debug(
60
+ manager: DeviceTreeManager,
61
+ instance_name: str,
62
+ old_instance,
63
+ new_instance,
64
+ suffix: str = ""
65
+ ) -> None:
66
+ """Dump overlay DTS source to stdout for debugging when --debug is enabled."""
67
+ dtbo_data = manager.overlay_gen.generate_update_overlay(instance_name, old_instance, new_instance)
68
+
69
+ try:
70
+ from ..dtc.parser import DeviceTreeParser
71
+ import libfdt
72
+
73
+ fdt = libfdt.Fdt(dtbo_data)
74
+ parser = DeviceTreeParser()
75
+ parser.fdt = fdt
76
+ dts_lines = parser._fdt_to_dts_recursive(0, 0) # pylint: disable=protected-access
77
+ dts_content = '\n'.join(dts_lines)
78
+
79
+ click.echo(f"Debug: Overlay DTS source for '{instance_name}'{suffix}:")
80
+ click.echo("─" * 70)
81
+ click.echo(dts_content)
82
+ click.echo("─" * 70)
83
+ except Exception as e:
84
+ click.echo(f"Debug: Failed to convert overlay to DTS: {e}", err=True)
85
+
86
+
87
+ @click.command(name='update')
88
+ @click.argument('name', required=True)
89
+ @click.option('--cpus', '-c',
90
+ help='Update CPU allocation: CPU IDs (e.g., "4-7" for range, "4,5,6,7" for list)')
91
+ @click.option('--memory', '-m',
92
+ help='Update memory allocation (e.g., "2GB", "2048MB")')
93
+ @click.option('--memory-base',
94
+ help='Update memory base address (hex: 0x80000000 or decimal, auto-assigned if not specified with --memory)')
95
+ @click.option('--devices', '-d',
96
+ help='Update device allocation: PCI IDs (comma-separated, e.g., "0000:09:00.0,0000:0a:00.0")')
97
+ @click.option('--dry-run', is_flag=True, help='Validate without applying to kernel')
98
+ @click.option('--verbose', '-v', is_flag=True, help='Verbose output')
99
+ @click.pass_context
100
+ def update(
101
+ ctx: click.Context,
102
+ name: str,
103
+ cpus: Optional[str],
104
+ memory: Optional[str],
105
+ memory_base: Optional[str],
106
+ devices: Optional[str],
107
+ dry_run: bool,
108
+ verbose: bool
109
+ ):
110
+ """
111
+ Update resources of an existing kernel instance.
112
+
113
+ This command updates CPU, memory, and/or device resources for an instance.
114
+ Operations are processed in order: memory-remove, memory-add, cpu-remove, cpu-add,
115
+ device-remove, device-add.
116
+
117
+ At least one of --cpus, --memory, or --devices must be specified.
118
+
119
+ Examples:
120
+
121
+ # Update CPUs only
122
+ kerf update web-server --cpus=8-15
123
+
124
+ # Update memory only (auto-assign base address)
125
+ kerf update web-server --memory=4GB
126
+
127
+ # Update memory with specific base address
128
+ kerf update web-server --memory=4GB --memory-base=0x200000000
129
+
130
+ # Update devices
131
+ kerf update web-server --devices=0000:09:00.0,0000:0a:00.0
132
+
133
+ # Update CPUs, memory, and devices
134
+ kerf update web-server --cpus=8-15 --memory=4GB --devices=0000:09:00.0
135
+
136
+ # Validate without applying
137
+ kerf update web-server --cpus=8-15 --memory=4GB --dry-run
138
+ """
139
+ try:
140
+ if not cpus and not memory and not devices:
141
+ click.echo("Error: At least one of --cpus, --memory, or --devices must be specified", err=True)
142
+ sys.exit(2)
143
+
144
+ if memory_base and not memory:
145
+ click.echo("Error: --memory-base requires --memory", err=True)
146
+ sys.exit(2)
147
+
148
+ debug = ctx.obj.get('debug', False) if ctx and ctx.obj else False
149
+
150
+ manager = DeviceTreeManager()
151
+
152
+ if not manager.has_instance(name):
153
+ click.echo(f"Error: Instance '{name}' does not exist", err=True)
154
+ sys.exit(1)
155
+
156
+ cpu_list = None
157
+ if cpus:
158
+ try:
159
+ cpu_list = parse_cpu_spec(cpus)
160
+ except ValueError as e:
161
+ click.echo(f"Error: Invalid CPU specification '{cpus}': {e}", err=True)
162
+ sys.exit(2)
163
+
164
+ memory_bytes = None
165
+ if memory:
166
+ try:
167
+ memory_bytes = parse_memory_spec(memory)
168
+ except ValueError as e:
169
+ click.echo(f"Error: Invalid memory specification '{memory}': {e}", err=True)
170
+ sys.exit(2)
171
+
172
+ memory_base_addr = None
173
+ if memory_base:
174
+ try:
175
+ memory_base_addr = parse_memory_base(memory_base)
176
+ except ValueError as e:
177
+ click.echo(f"Error: Invalid memory base '{memory_base}': {e}", err=True)
178
+ sys.exit(2)
179
+
180
+ device_list = None
181
+ if devices is not None:
182
+ try:
183
+ device_list = parse_device_spec(devices)
184
+ except ValueError as e:
185
+ click.echo(f"Error: Invalid device specification '{devices}': {e}", err=True)
186
+ sys.exit(2)
187
+
188
+ def update_instance_operation(current):
189
+ """Operation function to update instance resources. Returns (old_instance, new_instance)."""
190
+ nonlocal memory_base_addr
191
+ nonlocal device_list
192
+
193
+ from pathlib import Path
194
+ import libfdt
195
+ import struct
196
+ from ..dtc.cells import unpack_cpu_ids
197
+ from ..models import Instance, InstanceResources
198
+
199
+ instance_dt_path = Path(f'/sys/fs/multikernel/instances/{name}/device_tree')
200
+ if not instance_dt_path.exists():
201
+ raise ResourceError(f"Instance '{name}' device_tree not found at {instance_dt_path}")
202
+
203
+ try:
204
+ with open(instance_dt_path, 'rb') as f:
205
+ instance_dtb_data = f.read()
206
+
207
+ fdt = libfdt.Fdt(instance_dtb_data)
208
+
209
+ instance_offset = 0
210
+ instance_node_name = fdt.get_name(instance_offset)
211
+
212
+ instance_id_prop = fdt.getprop(instance_offset, 'id')
213
+ instance_id = struct.unpack('>I', instance_id_prop)[0]
214
+
215
+ resources_offset = fdt.first_subnode(instance_offset)
216
+ if resources_offset < 0:
217
+ raise ResourceError(f"No resources node found for instance '{instance_node_name}'")
218
+
219
+ cpus_prop = fdt.getprop(resources_offset, 'cpus')
220
+ cpus = unpack_cpu_ids(cpus_prop)
221
+
222
+ memory_base_prop = fdt.getprop(resources_offset, 'memory-base')
223
+ memory_base = struct.unpack('>Q', memory_base_prop)[0]
224
+
225
+ memory_bytes_prop = fdt.getprop(resources_offset, 'memory-bytes')
226
+ memory_bytes_val = struct.unpack('>Q', memory_bytes_prop)[0]
227
+
228
+ # Parse devices from resources/devices/ node
229
+ existing_device_list = []
230
+ try:
231
+ devices_offset = fdt.first_subnode(resources_offset)
232
+ while devices_offset >= 0:
233
+ device_node_name = fdt.get_name(devices_offset)
234
+ if device_node_name == 'devices':
235
+ # Iterate through device subnodes
236
+ device_child_offset = fdt.first_subnode(devices_offset)
237
+ while device_child_offset >= 0:
238
+ try:
239
+ pci_id_prop = fdt.getprop(device_child_offset, 'pci-id')
240
+ pci_id = pci_id_prop.as_str().rstrip('\0')
241
+ existing_device_list.append(pci_id)
242
+ except libfdt.FdtException:
243
+ pass
244
+ try:
245
+ device_child_offset = fdt.next_subnode(device_child_offset)
246
+ except libfdt.FdtException:
247
+ break
248
+ try:
249
+ devices_offset = fdt.next_subnode(devices_offset)
250
+ except libfdt.FdtException:
251
+ break
252
+ except libfdt.FdtException:
253
+ pass
254
+
255
+ existing_instance = Instance(
256
+ name=instance_node_name,
257
+ id=instance_id,
258
+ resources=InstanceResources(
259
+ cpus=cpus,
260
+ memory_base=memory_base,
261
+ memory_bytes=memory_bytes_val,
262
+ devices=existing_device_list
263
+ )
264
+ )
265
+
266
+ except libfdt.FdtException as e:
267
+ raise ResourceError(f"Failed to parse instance '{name}' device_tree: {e}") from e
268
+ except Exception as e:
269
+ raise ResourceError(f"Failed to read instance '{name}' device_tree: {e}") from e
270
+
271
+ modified = copy.deepcopy(current)
272
+ modified.instances[instance_node_name] = copy.deepcopy(existing_instance)
273
+
274
+ if cpu_list is not None:
275
+ current_cpus = set(existing_instance.resources.cpus)
276
+ requested_cpus = set(cpu_list)
277
+ new_cpus = requested_cpus - current_cpus
278
+
279
+ if new_cpus:
280
+ validate_cpu_allocation(modified, sorted(new_cpus), exclude_instance=instance_node_name)
281
+
282
+ if memory_bytes is not None:
283
+ if memory_base_addr is None:
284
+ # Keep the same base address and extend/shrink in place
285
+ old_base = existing_instance.resources.memory_base
286
+ old_size = existing_instance.resources.memory_bytes
287
+
288
+ if memory_bytes > old_size:
289
+ # Growing: validate the extension region doesn't overlap
290
+ extension_base = old_base + old_size
291
+ extension_size = memory_bytes - old_size
292
+ try:
293
+ validate_memory_allocation(
294
+ modified, extension_base, extension_size,
295
+ exclude_instance=instance_node_name
296
+ )
297
+ memory_base_addr = old_base
298
+ except (ResourceError,) as exc:
299
+ # Extension conflicts, find a completely new region
300
+ found_base = find_available_memory_base(modified, memory_bytes)
301
+ if found_base is None:
302
+ raise ResourceError(
303
+ f"No available memory region found for {memory_bytes} bytes. "
304
+ "Try specifying --memory-base or reduce memory size."
305
+ ) from exc
306
+ memory_base_addr = found_base
307
+ elif memory_bytes < old_size:
308
+ # Shrinking: always keep the same base
309
+ memory_base_addr = old_base
310
+ else:
311
+ # Same size, no change
312
+ memory_base_addr = old_base
313
+ else:
314
+ validate_memory_allocation(
315
+ modified, memory_base_addr, memory_bytes, exclude_instance=instance_node_name
316
+ )
317
+
318
+ updated_instance = copy.deepcopy(existing_instance)
319
+ if cpu_list is not None:
320
+ updated_instance.resources.cpus = cpu_list
321
+ if memory_bytes is not None:
322
+ updated_instance.resources.memory_base = memory_base_addr
323
+ updated_instance.resources.memory_bytes = memory_bytes
324
+ if device_list is not None:
325
+ updated_instance.resources.devices = device_list
326
+
327
+ return (existing_instance, updated_instance)
328
+
329
+ if dry_run:
330
+ try:
331
+ current = manager.read_baseline()
332
+ old_instance, new_instance = update_instance_operation(current)
333
+
334
+ click.echo(f"✓ Validation passed for updating instance '{name}'")
335
+ if cpu_list is not None:
336
+ click.echo(f" CPUs: {', '.join(map(str, new_instance.resources.cpus))}")
337
+ if memory_bytes is not None:
338
+ click.echo(f" Memory: {memory} at {hex(new_instance.resources.memory_base)}")
339
+
340
+ if debug:
341
+ dump_overlay_for_debug(manager, name, old_instance, new_instance, suffix="_dryrun")
342
+ click.echo()
343
+
344
+ click.echo("\n✓ Instance would be updated (dry-run mode)")
345
+ click.echo(" Remove --dry-run to apply overlay to kernel")
346
+ except (ResourceError, ValidationError) as e:
347
+ click.echo(f"Error: {e}", err=True)
348
+ sys.exit(1)
349
+ except (KernelInterfaceError, ParseError) as e:
350
+ click.echo(f"Error: {e}", err=True)
351
+ sys.exit(1)
352
+ return
353
+
354
+ try:
355
+ if debug:
356
+ current = manager.read_baseline()
357
+ old_instance, new_instance = update_instance_operation(current)
358
+ click.echo(f"\nDebug: Old instance: CPUs={old_instance.resources.cpus}, Devices={old_instance.resources.devices}")
359
+ click.echo(f"Debug: New instance: CPUs={new_instance.resources.cpus}, Devices={new_instance.resources.devices}")
360
+ dump_overlay_for_debug(manager, name, old_instance, new_instance)
361
+
362
+ def apply_update_operation(current):
363
+ old_instance, new_instance = update_instance_operation(current)
364
+ dtbo_data = manager.overlay_gen.generate_update_overlay(name, old_instance, new_instance)
365
+ return dtbo_data
366
+
367
+ with manager._acquire_lock(): # pylint: disable=protected-access
368
+ current = manager.read_baseline()
369
+ dtbo_data = apply_update_operation(current)
370
+
371
+ try:
372
+ if not manager.overlays_new.exists():
373
+ raise KernelInterfaceError(
374
+ f"Overlay interface not found: {manager.overlays_new}"
375
+ )
376
+
377
+ with open(manager.overlays_new, 'wb') as f:
378
+ f.write(dtbo_data)
379
+
380
+ tx_id = manager._find_latest_transaction() # pylint: disable=protected-access
381
+ if not tx_id:
382
+ raise KernelInterfaceError(
383
+ "Overlay written but kernel did not create transaction directory"
384
+ )
385
+
386
+ tx_dir = manager.overlays_dir / f"tx_{tx_id}"
387
+ status_file = tx_dir / "status"
388
+
389
+ if status_file.exists():
390
+ try:
391
+ with open(status_file, 'r', encoding='utf-8') as f:
392
+ status = f.read().strip()
393
+ if status not in ("applied", "success", "ok"):
394
+ error_msg = f"Overlay transaction {tx_id} failed with status: '{status}'"
395
+ instance_file = tx_dir / "instance"
396
+ if instance_file.exists():
397
+ try:
398
+ with open(instance_file, 'r', encoding='utf-8') as f:
399
+ instance_name_from_tx = f.read().strip()
400
+ error_msg += f" (instance: {instance_name_from_tx})"
401
+ except OSError:
402
+ pass
403
+ raise KernelInterfaceError(error_msg)
404
+ except OSError:
405
+ pass
406
+
407
+ except OSError as e:
408
+ raise KernelInterfaceError(
409
+ f"Failed to write overlay to {manager.overlays_new}: {e}"
410
+ ) from e
411
+
412
+ click.echo(f"✓ Updated instance '{name}' (transaction {tx_id})")
413
+ if verbose:
414
+ current = manager.read_baseline()
415
+ _, new_instance = update_instance_operation(current)
416
+ click.echo(f" Instance ID: {new_instance.id}")
417
+ click.echo(f" CPUs: {', '.join(map(str, new_instance.resources.cpus))}")
418
+ click.echo(f" Memory: {new_instance.resources.memory_bytes} bytes at {hex(new_instance.resources.memory_base)}")
419
+ except ResourceError as e:
420
+ click.echo(f"Error: Resource allocation failed: {e}", err=True)
421
+ if verbose:
422
+ import traceback
423
+ traceback.print_exc()
424
+ sys.exit(1)
425
+ except ValidationError as e:
426
+ click.echo(f"Error: Validation failed: {e}", err=True)
427
+ if verbose:
428
+ import traceback
429
+ traceback.print_exc()
430
+ sys.exit(1)
431
+ except KernelInterfaceError as e:
432
+ click.echo(f"Error: Kernel interface error: {e}", err=True)
433
+ if verbose:
434
+ import traceback
435
+ traceback.print_exc()
436
+ sys.exit(1)
437
+
438
+ except KeyboardInterrupt:
439
+ click.echo("\nOperation cancelled", err=True)
440
+ sys.exit(130)
441
+ except Exception as e:
442
+ click.echo(f"Unexpected error: {e}", err=True)
443
+ if verbose:
444
+ import traceback
445
+ traceback.print_exc()
446
+ sys.exit(1)
447
+
448
+
449
+ if __name__ == '__main__':
450
+ update()
kerf/utils.py ADDED
@@ -0,0 +1,95 @@
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
+ Utility functions for kernel instance management.
17
+
18
+ This module provides shared utility functions for interacting with the kernel
19
+ filesystem interface for multikernel instances.
20
+ """
21
+
22
+ from typing import Optional
23
+ from pathlib import Path
24
+
25
+
26
+ def get_instance_id_from_name(name: str) -> Optional[int]:
27
+ """
28
+ Get instance ID from instance name by reading /sys/fs/multikernel/instances/{name}/id.
29
+
30
+ Args:
31
+ name: Instance name
32
+
33
+ Returns:
34
+ Instance ID if found, None otherwise
35
+ """
36
+ id_path = Path(f"/sys/fs/multikernel/instances/{name}/id")
37
+
38
+ if not id_path.exists():
39
+ return None
40
+
41
+ try:
42
+ with open(id_path, "r", encoding="utf-8") as f:
43
+ instance_id = int(f.read().strip())
44
+ return instance_id
45
+ except (OSError, IOError, ValueError):
46
+ return None
47
+
48
+
49
+ def get_instance_name_from_id(instance_id: int) -> Optional[str]:
50
+ """
51
+ Get instance name from instance ID by scanning /sys/fs/multikernel/instances/.
52
+
53
+ Args:
54
+ instance_id: Instance ID to search for
55
+
56
+ Returns:
57
+ Instance name if found, None otherwise
58
+ """
59
+ instances_dir = Path("/sys/fs/multikernel/instances")
60
+
61
+ if not instances_dir.exists():
62
+ return None
63
+
64
+ try:
65
+ for inst_dir in instances_dir.iterdir():
66
+ if inst_dir.is_dir():
67
+ found_id = get_instance_id_from_name(inst_dir.name)
68
+ if found_id == instance_id:
69
+ return inst_dir.name
70
+ except (OSError, IOError):
71
+ pass
72
+
73
+ return None
74
+
75
+
76
+ def get_instance_status(name: str) -> Optional[str]:
77
+ """
78
+ Get instance status from kernel filesystem.
79
+
80
+ Args:
81
+ name: Instance name
82
+
83
+ Returns:
84
+ Status string if found, None otherwise
85
+ """
86
+ status_path = Path(f"/sys/fs/multikernel/instances/{name}/status")
87
+
88
+ if not status_path.exists():
89
+ return None
90
+
91
+ try:
92
+ with open(status_path, "r", encoding="utf-8") as f:
93
+ return f.read().strip()
94
+ except (OSError, IOError):
95
+ return None