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/runtime.py ADDED
@@ -0,0 +1,527 @@
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
+ Runtime management layer for device tree state with overlay support.
17
+
18
+ This module provides the DeviceTreeManager class which bridges imperative
19
+ kerf commands with the declarative device tree overlay interface exposed by the kernel.
20
+ It implements a transactional overlay pattern to maintain the kernel as the single
21
+ source of truth while supporting imperative operations.
22
+
23
+ Architecture:
24
+ ============
25
+
26
+ The kernel maintains the root device_tree up-to-date with all overlays already merged:
27
+
28
+ **Root Device Tree** (`/sys/fs/multikernel/device_tree`):
29
+ - Contains complete current state (resources + instances)
30
+ - Kept up-to-date by the kernel automatically
31
+ - Read directly to get current effective state (no user-space merging needed)
32
+
33
+ **Overlays** (`/sys/fs/multikernel/overlays/`):
34
+ - Contains ONLY instance changes (no resource modifications)
35
+ - Applied via `/sys/fs/multikernel/overlays/new`
36
+ - Kernel creates `tx_XXX/` directories after applying
37
+ - Kernel automatically merges overlays into root device_tree
38
+ - Rollback via `rmdir /sys/fs/multikernel/overlays/tx_XXX/`
39
+
40
+ DeviceTreeManager workflow (for runtime operations):
41
+ 1. Read: Read root device_tree directly (kernel keeps it up-to-date)
42
+ 2. Modify: Apply imperative operation to create modified state
43
+ 3. Validate: Validate entire modified state + enforce overlay constraints
44
+ 4. Generate: Create DTBO overlay representing instance delta only
45
+ 5. Apply: Write DTBO to `/sys/fs/multikernel/overlays/new`
46
+ 6. Track: Kernel creates `tx_XXX/` directory with transaction metadata
47
+
48
+ Example Usage (for future commands):
49
+ ====================================
50
+
51
+ ```python
52
+ # In kerf/create/main.py
53
+ from kerf.runtime import DeviceTreeManager
54
+ from kerf.resources import validate_cpu_allocation, find_next_instance_id, ...
55
+
56
+ @click.command()
57
+ def create(name: str, cpus: List[int], memory: int):
58
+ manager = DeviceTreeManager()
59
+
60
+ def create_instance(current: GlobalDeviceTree) -> GlobalDeviceTree:
61
+ # Create modified state
62
+ import copy
63
+ modified = copy.deepcopy(current)
64
+
65
+ # Check existence
66
+ if name in modified.instances:
67
+ raise ValueError(f"Instance '{name}' already exists")
68
+
69
+ # Validate resources (against baseline)
70
+ validate_cpu_allocation(modified, cpus)
71
+
72
+ # Find memory base
73
+ memory_base = find_available_memory_base(modified, memory)
74
+ if not memory_base:
75
+ raise ResourceError("No memory available")
76
+
77
+ # Create instance
78
+ instance = Instance(
79
+ name=name,
80
+ id=find_next_instance_id(modified),
81
+ resources=InstanceResources(
82
+ cpus=cpus,
83
+ memory_base=memory_base,
84
+ memory_bytes=memory,
85
+ devices=[]
86
+ )
87
+ )
88
+ modified.instances[name] = instance
89
+
90
+ return modified
91
+
92
+ # Apply transactionally via overlay
93
+ tx_id = manager.apply_operation(create_instance)
94
+ click.echo(f"Created instance '{name}' (transaction {tx_id})")
95
+ ```
96
+
97
+ All operations follow this same pattern, ensuring consistency and validation.
98
+ """
99
+
100
+ import os
101
+ import re
102
+ from pathlib import Path
103
+ from typing import Callable, Optional, List, Dict
104
+ from contextlib import contextmanager
105
+
106
+ from .dtc.parser import DeviceTreeParser
107
+ from .dtc.overlay import OverlayGenerator
108
+ from .dtc.validator import MultikernelValidator
109
+ from .baseline import BaselineManager
110
+ from .models import GlobalDeviceTree
111
+ from .exceptions import ValidationError, ParseError, KernelInterfaceError
112
+
113
+
114
+ class DeviceTreeManager:
115
+ """
116
+ Manages device tree state with kernel overlay interface.
117
+
118
+ This class provides a transactional interface for modifying the device tree
119
+ using overlays. Each operation generates a device tree overlay (DTBO) that
120
+ represents the incremental change.
121
+
122
+ Attributes:
123
+ baseline_path: Path to baseline device tree
124
+ overlays_dir: Path to overlays directory
125
+ overlays_new: Path to write new overlays
126
+ lock_file: Path to lock file for concurrency control
127
+ parser: DeviceTreeParser instance for reading state
128
+ overlay_gen: OverlayGenerator instance for creating overlays
129
+ validator: MultikernelValidator instance for validation
130
+ """
131
+
132
+ DEFAULT_BASELINE_PATH = "/sys/fs/multikernel/device_tree"
133
+ DEFAULT_OVERLAYS_DIR = "/sys/fs/multikernel/overlays"
134
+
135
+ def __init__(self, baseline_path: Optional[str] = None, overlays_dir: Optional[str] = None):
136
+ """
137
+ Initialize DeviceTreeManager.
138
+
139
+ Args:
140
+ baseline_path: Path to baseline device tree. Defaults to
141
+ /sys/fs/multikernel/device_tree
142
+ overlays_dir: Path to overlays directory. Defaults to
143
+ /sys/fs/multikernel/overlays
144
+ """
145
+ self.baseline_path = Path(baseline_path or self.DEFAULT_BASELINE_PATH)
146
+ self.overlays_dir = Path(overlays_dir or self.DEFAULT_OVERLAYS_DIR)
147
+ self.overlays_new = self.overlays_dir / "new"
148
+
149
+ lock_dir = Path("/var/run")
150
+ if not lock_dir.exists() or not os.access(lock_dir, os.W_OK):
151
+ lock_dir = Path("/tmp")
152
+ self.lock_file = lock_dir / "kerf.lock"
153
+
154
+ self.parser = DeviceTreeParser()
155
+ self.overlay_gen = OverlayGenerator()
156
+ self.validator = MultikernelValidator()
157
+ self.baseline_mgr = BaselineManager(str(self.baseline_path))
158
+
159
+ def read_baseline(self) -> GlobalDeviceTree:
160
+ """
161
+ Read root device tree from kernel.
162
+
163
+ The kernel maintains the root device_tree up-to-date with all overlays
164
+ already merged, so this returns the complete current state including
165
+ both resources and instances.
166
+
167
+ Returns:
168
+ GlobalDeviceTree model representing current complete state
169
+
170
+ Raises:
171
+ KernelInterfaceError: If kernel interface is inaccessible
172
+ ParseError: If device tree cannot be parsed
173
+ """
174
+ return self.baseline_mgr.read_baseline()
175
+
176
+ def apply_overlay(self, current: GlobalDeviceTree, modified: GlobalDeviceTree) -> str:
177
+ """
178
+ Apply overlay by writing DTBO to kernel.
179
+
180
+ Generates an overlay representing the difference between current and
181
+ modified states, then writes it to /sys/fs/multikernel/overlays/new.
182
+ The kernel applies it and creates a transaction directory.
183
+
184
+ Args:
185
+ current: Current effective state (before change)
186
+ modified: Modified state (after change)
187
+
188
+ Returns:
189
+ Transaction ID (from kernel-created directory)
190
+
191
+ Raises:
192
+ ValidationError: If modified state validation fails
193
+ KernelInterfaceError: If overlay application fails
194
+ """
195
+ # Validate overlay doesn't modify resources
196
+ if current.hardware != modified.hardware:
197
+ raise ValidationError(
198
+ "Overlays cannot modify hardware resources. "
199
+ "Resources are defined in baseline only. "
200
+ "Current and modified states have different hardware definitions."
201
+ )
202
+
203
+ # Validate modified state before generating overlay
204
+ validation_result = self.validator.validate(modified)
205
+ if not validation_result.is_valid:
206
+ error_msg = "Cannot apply overlay with invalid state:\n"
207
+ error_msg += "\n".join(f" - {err}" for err in validation_result.errors)
208
+ if validation_result.warnings:
209
+ error_msg += "\n\nWarnings:\n"
210
+ error_msg += "\n".join(f" - {warn}" for warn in validation_result.warnings)
211
+ raise ValidationError(error_msg)
212
+
213
+ try:
214
+ dtbo_data = self.overlay_gen.generate_overlay(current, modified)
215
+ except Exception as e:
216
+ raise KernelInterfaceError(f"Failed to generate overlay: {e}") from e
217
+
218
+ try:
219
+ if not self.overlays_new.exists():
220
+ raise KernelInterfaceError(f"Overlay interface not found: {self.overlays_new}")
221
+
222
+ with open(self.overlays_new, "wb") as f:
223
+ f.write(dtbo_data)
224
+
225
+ tx_id = self._find_latest_transaction()
226
+ if not tx_id:
227
+ raise KernelInterfaceError(
228
+ "Overlay written but kernel did not create transaction directory"
229
+ )
230
+
231
+ # Verify transaction succeeded by checking status
232
+ tx_dir = self.overlays_dir / f"tx_{tx_id}"
233
+ status_file = tx_dir / "status"
234
+
235
+ if status_file.exists():
236
+ try:
237
+ with open(status_file, "r", encoding="utf-8") as f:
238
+ status = f.read().strip()
239
+ if status not in ("applied", "success", "ok"):
240
+ error_msg = f"Overlay transaction {tx_id} failed with status: '{status}'"
241
+ instance_file = tx_dir / "instance"
242
+ if instance_file.exists():
243
+ try:
244
+ with open(instance_file, "r", encoding="utf-8") as f:
245
+ instance_name = f.read().strip()
246
+ error_msg += f" (instance: {instance_name})"
247
+ except OSError:
248
+ pass
249
+
250
+ raise KernelInterfaceError(error_msg)
251
+ except OSError:
252
+ # If we can't read status, assume it might still be processing
253
+ # But warn that we couldn't verify
254
+ pass
255
+
256
+ return tx_id
257
+
258
+ except OSError as e:
259
+ raise KernelInterfaceError(
260
+ f"Failed to write overlay to {self.overlays_new}: {e}"
261
+ ) from e
262
+
263
+ def apply_removal_overlay(self, instance_name: str) -> str:
264
+ """
265
+ Apply an instance-remove overlay directly to the kernel.
266
+
267
+ This method generates an instance-remove overlay and applies it to
268
+ /sys/fs/multikernel/overlays/new, allowing the kernel to handle deletion
269
+ via mk_instance_destroy(). This is the correct approach for deletion,
270
+ as it doesn't require reading or modifying the baseline device tree.
271
+
272
+ Args:
273
+ instance_name: Name of the instance to remove
274
+
275
+ Returns:
276
+ Transaction ID from applied overlay
277
+
278
+ Raises:
279
+ KernelInterfaceError: If overlay application fails
280
+ """
281
+ with self._acquire_lock():
282
+ try:
283
+ dtbo_data = self.overlay_gen.generate_removal_overlay(instance_name)
284
+ except Exception as e:
285
+ raise KernelInterfaceError(f"Failed to generate removal overlay: {e}") from e
286
+
287
+ try:
288
+ if not self.overlays_new.exists():
289
+ raise KernelInterfaceError(f"Overlay interface not found: {self.overlays_new}")
290
+
291
+ with open(self.overlays_new, "wb") as f:
292
+ f.write(dtbo_data)
293
+
294
+ tx_id = self._find_latest_transaction()
295
+ if not tx_id:
296
+ raise KernelInterfaceError(
297
+ "Overlay written but kernel did not create transaction directory"
298
+ )
299
+
300
+ tx_dir = self.overlays_dir / f"tx_{tx_id}"
301
+ status_file = tx_dir / "status"
302
+
303
+ if status_file.exists():
304
+ try:
305
+ with open(status_file, "r", encoding="utf-8") as f:
306
+ status = f.read().strip()
307
+ if status not in ("applied", "success", "ok"):
308
+ error_msg = (
309
+ f"Overlay transaction {tx_id} failed with status: '{status}'"
310
+ )
311
+ instance_file = tx_dir / "instance"
312
+ if instance_file.exists():
313
+ try:
314
+ with open(instance_file, "r", encoding="utf-8") as f:
315
+ tx_instance_name = f.read().strip()
316
+ error_msg += f" (instance: {tx_instance_name})"
317
+ except OSError:
318
+ pass
319
+ raise KernelInterfaceError(error_msg)
320
+ except OSError:
321
+ pass
322
+
323
+ return tx_id
324
+
325
+ except OSError as e:
326
+ raise KernelInterfaceError(
327
+ f"Failed to write overlay to {self.overlays_new}: {e}"
328
+ ) from e
329
+
330
+ def _find_latest_transaction(self) -> Optional[str]:
331
+ """Find the latest transaction ID from kernel-created directories."""
332
+ if not self.overlays_dir.exists():
333
+ return None
334
+
335
+ max_tx_id = None
336
+ max_id = -1
337
+
338
+ for tx_dir in self.overlays_dir.iterdir():
339
+ if not tx_dir.is_dir():
340
+ continue
341
+
342
+ match = re.match(r"^tx_(\d+)$", tx_dir.name)
343
+ if match:
344
+ tx_id = int(match.group(1))
345
+ if tx_id > max_id:
346
+ max_id = tx_id
347
+ max_tx_id = match.group(1)
348
+
349
+ return max_tx_id
350
+
351
+ def rollback_transaction(self, tx_id: str) -> None:
352
+ """
353
+ Rollback a transaction by removing its overlay.
354
+
355
+ Args:
356
+ tx_id: Transaction ID to rollback
357
+
358
+ Raises:
359
+ KernelInterfaceError: If rollback fails
360
+ """
361
+ tx_dir = self.overlays_dir / f"tx_{tx_id}"
362
+
363
+ if not tx_dir.exists():
364
+ raise KernelInterfaceError(f"Transaction {tx_id} not found: {tx_dir}")
365
+
366
+ try:
367
+ # Remove transaction directory (kernel handles rollback)
368
+ tx_dir.rmdir()
369
+ except OSError as e:
370
+ raise KernelInterfaceError(f"Failed to rollback transaction {tx_id}: {e}") from e
371
+
372
+ def list_transactions(self) -> List[Dict[str, str]]:
373
+ """
374
+ List all applied transactions.
375
+
376
+ Returns:
377
+ List of transaction info dicts with keys: id, status, instance
378
+ """
379
+ transactions = []
380
+
381
+ if not self.overlays_dir.exists():
382
+ return transactions
383
+
384
+ for tx_dir in self.overlays_dir.iterdir():
385
+ if not tx_dir.is_dir():
386
+ continue
387
+
388
+ match = re.match(r"^tx_(\d+)$", tx_dir.name)
389
+ if not match:
390
+ continue
391
+
392
+ tx_id = match.group(1)
393
+ tx_info = {"id": tx_id}
394
+
395
+ # Read transaction metadata
396
+ status_file = tx_dir / "status"
397
+ instance_file = tx_dir / "instance"
398
+
399
+ if status_file.exists():
400
+ try:
401
+ with open(status_file, "r", encoding="utf-8") as f:
402
+ tx_info["status"] = f.read().strip()
403
+ except OSError:
404
+ tx_info["status"] = "unknown"
405
+
406
+ if instance_file.exists():
407
+ try:
408
+ with open(instance_file, "r", encoding="utf-8") as f:
409
+ tx_info["instance"] = f.read().strip()
410
+ except OSError:
411
+ pass
412
+
413
+ transactions.append(tx_info)
414
+
415
+ # Sort by transaction ID
416
+ transactions.sort(key=lambda x: int(x["id"]))
417
+ return transactions
418
+
419
+ @contextmanager
420
+ def _acquire_lock(self):
421
+ """
422
+ Acquire file lock for concurrency safety.
423
+
424
+ Yields:
425
+ Lock context
426
+
427
+ Raises:
428
+ KernelInterfaceError: If lock cannot be acquired
429
+ """
430
+ lock_acquired = False
431
+
432
+ try:
433
+ max_retries = 10
434
+ retry_delay = 0.1
435
+
436
+ for _ in range(max_retries):
437
+ try:
438
+ if not self.lock_file.exists():
439
+ self.lock_file.touch(exist_ok=False)
440
+ lock_acquired = True
441
+ break
442
+ import time
443
+
444
+ time.sleep(retry_delay)
445
+ except FileExistsError:
446
+ import time
447
+
448
+ time.sleep(retry_delay)
449
+ continue
450
+
451
+ if not lock_acquired:
452
+ raise KernelInterfaceError(
453
+ f"Could not acquire lock after {max_retries} attempts. "
454
+ "Another kerf operation may be in progress."
455
+ )
456
+
457
+ yield
458
+
459
+ finally:
460
+ if lock_acquired and self.lock_file.exists():
461
+ self.lock_file.unlink()
462
+
463
+ def apply_operation(self, operation: Callable[[GlobalDeviceTree], GlobalDeviceTree]) -> str:
464
+ """
465
+ Apply an operation transactionally via overlay.
466
+
467
+ This is the core method that implements the overlay pattern:
468
+ 1. Read root device_tree to get current effective state (kernel keeps it up-to-date)
469
+ 2. Apply operation to get modified state
470
+ 3. Validate modified state
471
+ 4. Generate overlay (delta between current effective and modified)
472
+ 5. Apply overlay to kernel
473
+
474
+ The operation function receives the current effective GlobalDeviceTree
475
+ and must return a modified GlobalDeviceTree (typically a copy).
476
+
477
+ Args:
478
+ operation: Callable that takes GlobalDeviceTree and returns modified
479
+ GlobalDeviceTree. Should raise appropriate exceptions for errors.
480
+
481
+ Returns:
482
+ Transaction ID from applied overlay
483
+
484
+ Raises:
485
+ ValidationError: If resulting state is invalid
486
+ KernelInterfaceError: If kernel interface operations fail
487
+ Any exceptions raised by the operation function
488
+ """
489
+ with self._acquire_lock():
490
+ current = self.read_baseline()
491
+
492
+ # Apply operation (returns modified state)
493
+ modified = operation(current)
494
+
495
+ # Generate overlay comparing current effective to modified
496
+ # Each overlay represents incremental change from current state
497
+ tx_id = self.apply_overlay(current, modified)
498
+
499
+ return tx_id
500
+
501
+ def get_instance_names(self) -> List[str]:
502
+ """
503
+ Get list of all instance names in current effective state.
504
+
505
+ Returns:
506
+ List of instance names (empty list if kernel not initialized)
507
+ """
508
+ try:
509
+ tree = self.read_baseline()
510
+ return list(tree.instances.keys())
511
+ except (KernelInterfaceError, ParseError):
512
+ return []
513
+
514
+ def has_instance(self, name: str) -> bool:
515
+ """
516
+ Check if an instance exists in the kernel filesystem.
517
+
518
+ This checks the actual kernel state (/sys/fs/multikernel/instances/).
519
+
520
+ Args:
521
+ name: Instance name to check
522
+
523
+ Returns:
524
+ True if instance exists in kernel, False otherwise
525
+ """
526
+ instance_dir = Path(f"/sys/fs/multikernel/instances/{name}")
527
+ return instance_dir.exists() and instance_dir.is_dir()
kerf/show/__init__.py ADDED
@@ -0,0 +1,21 @@
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 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
+ Show kernel instance information subcommand implementation.
17
+ """
18
+
19
+ from .main import show
20
+
21
+ __all__ = ["show"]