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/dtc/overlay.py ADDED
@@ -0,0 +1,378 @@
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
+ Device tree overlay generation.
17
+
18
+ This module provides the OverlayGenerator class for generating device tree
19
+ overlays (DTBO) that represent incremental changes to the device tree state.
20
+ """
21
+
22
+ from typing import Set
23
+
24
+ import libfdt
25
+
26
+ from ..models import GlobalDeviceTree
27
+ from .cells import pack_cpu_id, pack_cpu_ids
28
+
29
+
30
+ class OverlayGenerator:
31
+ """Generates device tree overlay blobs (DTBO) from device tree model deltas."""
32
+
33
+ def generate_overlay(self, current: GlobalDeviceTree, modified: GlobalDeviceTree) -> bytes:
34
+ """
35
+ Generate overlay DTBO representing the difference between current and modified states.
36
+
37
+ The overlay contains only instance changes (additions, modifications, deletions).
38
+ Hardware resources are never included in overlays.
39
+
40
+ Args:
41
+ current: Current device tree state (before change)
42
+ modified: Modified device tree state (after change)
43
+
44
+ Returns:
45
+ DTBO blob as bytes
46
+ """
47
+ # Compute instance delta
48
+ instances_to_add = {}
49
+ instances_to_update = {}
50
+ instances_to_remove = set()
51
+
52
+ for name, instance in modified.instances.items():
53
+ if name not in current.instances:
54
+ instances_to_add[name] = instance
55
+ elif current.instances[name] != instance:
56
+ instances_to_update[name] = instance
57
+
58
+ for name in current.instances:
59
+ if name not in modified.instances:
60
+ instances_to_remove.add(name)
61
+
62
+ return self._create_overlay_dtb(instances_to_add, instances_to_update, instances_to_remove)
63
+
64
+ def generate_removal_overlay(self, instance_name: str) -> bytes:
65
+ """
66
+ Generate an instance-remove overlay for a single instance.
67
+
68
+ This method generates a minimal overlay that only contains an instance-remove
69
+ fragment, allowing the kernel to handle deletion via mk_instance_destroy().
70
+
71
+ Args:
72
+ instance_name: Name of the instance to remove
73
+
74
+ Returns:
75
+ DTBO blob as bytes containing only the instance-remove fragment
76
+ """
77
+ return self._create_overlay_dtb({}, {}, {instance_name})
78
+
79
+ def generate_update_overlay(self, instance_name: str, old_instance, new_instance) -> bytes:
80
+ """
81
+ Generate resource update overlay for an existing instance.
82
+
83
+ Operations are generated in order: memory-remove, memory-add, cpu-remove, cpu-add,
84
+ device-remove, device-add.
85
+ All operations are in a single fragment.
86
+
87
+ Args:
88
+ instance_name: Name of the instance to update
89
+ old_instance: Current instance state
90
+ new_instance: New instance state
91
+
92
+ Returns:
93
+ DTBO blob as bytes containing resource update operations
94
+ """
95
+ import struct
96
+
97
+ fdt_sw = libfdt.FdtSw()
98
+ fdt_sw.finish_reservemap()
99
+
100
+ fdt_sw.begin_node("")
101
+ fdt_sw.property_string("compatible", "linux,multikernel-overlay")
102
+
103
+ old_cpus = set(old_instance.resources.cpus)
104
+ new_cpus = set(new_instance.resources.cpus)
105
+ cpus_to_remove = sorted(old_cpus - new_cpus)
106
+ cpus_to_add = sorted(new_cpus - old_cpus)
107
+
108
+ old_mem_base = old_instance.resources.memory_base
109
+ old_mem_size = old_instance.resources.memory_bytes
110
+ new_mem_base = new_instance.resources.memory_base
111
+ new_mem_size = new_instance.resources.memory_bytes
112
+ memory_changed = (old_mem_base != new_mem_base) or (old_mem_size != new_mem_size)
113
+
114
+ old_devices = set(old_instance.resources.devices)
115
+ new_devices = set(new_instance.resources.devices)
116
+ devices_to_remove = sorted(old_devices - new_devices)
117
+ devices_to_add = sorted(new_devices - old_devices)
118
+
119
+ # Single fragment with all operations
120
+ fdt_sw.begin_node("fragment@0")
121
+ fdt_sw.begin_node("__overlay__")
122
+
123
+ # 1. memory-remove (if memory shrunk or base changed)
124
+ if memory_changed:
125
+ if old_mem_base == new_mem_base:
126
+ # Same base: only remove the excess if shrinking
127
+ if old_mem_size > new_mem_size:
128
+ remove_base = old_mem_base + new_mem_size
129
+ remove_size = old_mem_size - new_mem_size
130
+ fdt_sw.begin_node("memory-remove")
131
+ fdt_sw.property_string("mk,instance", instance_name)
132
+ fdt_sw.begin_node("region@0")
133
+ reg_data = struct.pack(">QQ", remove_base, remove_size)
134
+ fdt_sw.property("reg", reg_data)
135
+ fdt_sw.end_node()
136
+ fdt_sw.end_node()
137
+ else:
138
+ # Different base: remove entire old region
139
+ fdt_sw.begin_node("memory-remove")
140
+ fdt_sw.property_string("mk,instance", instance_name)
141
+ fdt_sw.begin_node("region@0")
142
+ reg_data = struct.pack(">QQ", old_mem_base, old_mem_size)
143
+ fdt_sw.property("reg", reg_data)
144
+ fdt_sw.end_node()
145
+ fdt_sw.end_node()
146
+
147
+ # 2. memory-add (if memory grew or base changed)
148
+ if memory_changed:
149
+ if old_mem_base == new_mem_base:
150
+ # Same base: only add the extension if growing
151
+ if new_mem_size > old_mem_size:
152
+ add_base = old_mem_base + old_mem_size
153
+ add_size = new_mem_size - old_mem_size
154
+ fdt_sw.begin_node("memory-add")
155
+ fdt_sw.property_string("mk,instance", instance_name)
156
+ fdt_sw.begin_node("region@0")
157
+ reg_data = struct.pack(">QQ", add_base, add_size)
158
+ fdt_sw.property("reg", reg_data)
159
+ fdt_sw.end_node()
160
+ fdt_sw.end_node()
161
+ else:
162
+ # Different base: add entire new region
163
+ fdt_sw.begin_node("memory-add")
164
+ fdt_sw.property_string("mk,instance", instance_name)
165
+ fdt_sw.begin_node("region@0")
166
+ reg_data = struct.pack(">QQ", new_mem_base, new_mem_size)
167
+ fdt_sw.property("reg", reg_data)
168
+ fdt_sw.end_node()
169
+ fdt_sw.end_node()
170
+
171
+ # 3. cpu-remove (if CPUs removed)
172
+ if cpus_to_remove:
173
+ fdt_sw.begin_node("cpu-remove")
174
+ fdt_sw.property_string("mk,instance", instance_name)
175
+
176
+ for cpu_id in cpus_to_remove:
177
+ fdt_sw.begin_node(f"cpu@{cpu_id}")
178
+ fdt_sw.property("reg", pack_cpu_id(cpu_id))
179
+ fdt_sw.end_node()
180
+
181
+ fdt_sw.end_node()
182
+
183
+ # 4. cpu-add (if CPUs added)
184
+ if cpus_to_add:
185
+ fdt_sw.begin_node("cpu-add")
186
+ fdt_sw.property_string("mk,instance", instance_name)
187
+
188
+ for cpu_id in cpus_to_add:
189
+ fdt_sw.begin_node(f"cpu@{cpu_id}")
190
+ fdt_sw.property("reg", pack_cpu_id(cpu_id))
191
+
192
+ if new_instance.resources.numa_nodes:
193
+ fdt_sw.property_u32("numa-node", new_instance.resources.numa_nodes[0])
194
+
195
+ fdt_sw.end_node()
196
+
197
+ fdt_sw.end_node()
198
+
199
+ # 5. device-remove (if devices removed)
200
+ if devices_to_remove:
201
+ fdt_sw.begin_node("device-remove")
202
+ fdt_sw.property_string("mk,instance", instance_name)
203
+
204
+ for idx, pci_id in enumerate(devices_to_remove):
205
+ fdt_sw.begin_node(f"pci@{idx}")
206
+ fdt_sw.property_string("pci-id", pci_id)
207
+ fdt_sw.end_node()
208
+
209
+ fdt_sw.end_node()
210
+
211
+ # 6. device-add (if devices added)
212
+ if devices_to_add:
213
+ fdt_sw.begin_node("device-add")
214
+ fdt_sw.property_string("mk,instance", instance_name)
215
+
216
+ for idx, pci_id in enumerate(devices_to_add):
217
+ fdt_sw.begin_node(f"pci@{idx}")
218
+ fdt_sw.property_string("pci-id", pci_id)
219
+ fdt_sw.end_node()
220
+
221
+ fdt_sw.end_node()
222
+
223
+ fdt_sw.end_node() # End __overlay__
224
+ fdt_sw.end_node() # End fragment@0
225
+
226
+ fdt_sw.end_node() # End root
227
+
228
+ dtb = fdt_sw.as_fdt()
229
+ dtb.pack()
230
+ return dtb.as_bytearray()
231
+
232
+ def _add_memory_operation(self, fdt_sw, fragment_id, operation, instance_name, base, size):
233
+ """Helper to add memory operation fragment."""
234
+ import struct
235
+
236
+ fdt_sw.begin_node(f"fragment@{fragment_id}")
237
+ fdt_sw.begin_node("__overlay__")
238
+ fdt_sw.begin_node(operation)
239
+ fdt_sw.property_string("mk,instance", instance_name)
240
+
241
+ fdt_sw.begin_node("region@0")
242
+ reg_data = struct.pack(">QQ", base, size)
243
+ fdt_sw.property("reg", reg_data)
244
+ fdt_sw.end_node()
245
+
246
+ fdt_sw.end_node()
247
+ fdt_sw.end_node()
248
+ fdt_sw.end_node()
249
+
250
+ return fragment_id + 1
251
+
252
+ def _add_cpu_operation(
253
+ self, fdt_sw, fragment_id, operation, instance_name, cpu_ids, numa_nodes
254
+ ):
255
+ """Helper to add CPU operation fragment."""
256
+ fdt_sw.begin_node(f"fragment@{fragment_id}")
257
+ fdt_sw.begin_node("__overlay__")
258
+ fdt_sw.begin_node(operation)
259
+ fdt_sw.property_string("mk,instance", instance_name)
260
+
261
+ for cpu_id in cpu_ids:
262
+ fdt_sw.begin_node(f"cpu@{cpu_id}")
263
+ fdt_sw.property("reg", pack_cpu_id(cpu_id))
264
+
265
+ if operation == "cpu-add" and numa_nodes:
266
+ fdt_sw.property_u32("numa-node", numa_nodes[0])
267
+
268
+ fdt_sw.end_node()
269
+
270
+ fdt_sw.end_node()
271
+ fdt_sw.end_node()
272
+ fdt_sw.end_node()
273
+
274
+ return fragment_id + 1
275
+
276
+ def _create_overlay_dtb(
277
+ self, instances_to_add: dict, instances_to_update: dict, instances_to_remove: Set[str]
278
+ ) -> bytes:
279
+ """
280
+ Create overlay DTB with instance changes using fragment format.
281
+
282
+ Args:
283
+ instances_to_add: Dict of instance name -> Instance to add
284
+ instances_to_update: Dict of instance name -> Instance to update
285
+ instances_to_remove: Set of instance names to remove
286
+
287
+ Returns:
288
+ DTBO blob as bytes
289
+ """
290
+ fdt_sw = libfdt.FdtSw()
291
+ fdt_sw.finish_reservemap()
292
+
293
+ # Root node
294
+ fdt_sw.begin_node("")
295
+ fdt_sw.property_string("compatible", "linux,multikernel-overlay")
296
+
297
+ fragment_id = 0
298
+
299
+ all_instances = {**instances_to_add, **instances_to_update}
300
+ for name, instance in all_instances.items():
301
+ fdt_sw.begin_node(f"fragment@{fragment_id}")
302
+ fdt_sw.begin_node("__overlay__")
303
+ fdt_sw.begin_node("instance-create")
304
+
305
+ # Add instance properties
306
+ fdt_sw.property_string("instance-name", name)
307
+ if instance.id is not None:
308
+ fdt_sw.property_u32("id", instance.id)
309
+
310
+ fdt_sw.begin_node("resources")
311
+
312
+ fdt_sw.property("cpus", pack_cpu_ids(instance.resources.cpus))
313
+
314
+ fdt_sw.property_u64("memory-base", instance.resources.memory_base)
315
+ fdt_sw.property_u64("memory-bytes", instance.resources.memory_bytes)
316
+
317
+ if instance.resources.devices:
318
+ stringlist_data = b'\0'.join(d.encode('utf-8') for d in instance.resources.devices) + b'\0'
319
+ fdt_sw.property("device-names", stringlist_data)
320
+
321
+ if instance.resources.numa_nodes:
322
+ import struct
323
+
324
+ numa_data = struct.pack(
325
+ ">" + "I" * len(instance.resources.numa_nodes), *instance.resources.numa_nodes
326
+ )
327
+ fdt_sw.property("numa-nodes", numa_data)
328
+
329
+ if instance.resources.cpu_affinity:
330
+ fdt_sw.property_string("cpu-affinity", instance.resources.cpu_affinity)
331
+
332
+ if instance.resources.memory_policy:
333
+ fdt_sw.property_string("memory-policy", instance.resources.memory_policy)
334
+
335
+ if instance.resources.uring:
336
+ fdt_sw.begin_node("uring")
337
+ if instance.resources.uring_sq_entries:
338
+ fdt_sw.property_u32("sq-entries", instance.resources.uring_sq_entries)
339
+ if instance.resources.uring_cq_entries:
340
+ fdt_sw.property_u32("cq-entries", instance.resources.uring_cq_entries)
341
+ if instance.resources.uring_shim_pages:
342
+ fdt_sw.property_u32("shim-data-pages", instance.resources.uring_shim_pages)
343
+ fdt_sw.end_node()
344
+
345
+ fdt_sw.end_node() # End resources
346
+
347
+ # Add options node if options exist
348
+ if instance.options:
349
+ fdt_sw.begin_node("options")
350
+
351
+ # Add enable-host-kcore if enabled
352
+ if instance.options.get("enable-host-kcore"):
353
+ fdt_sw.property("enable-host-kcore", b"")
354
+
355
+ # Future options can be added here
356
+
357
+ fdt_sw.end_node() # End options
358
+
359
+ fdt_sw.end_node() # End instance-create
360
+ fdt_sw.end_node() # End __overlay__
361
+ fdt_sw.end_node() # End fragment
362
+ fragment_id += 1
363
+
364
+ for name in instances_to_remove:
365
+ fdt_sw.begin_node(f"fragment@{fragment_id}")
366
+ fdt_sw.begin_node("__overlay__")
367
+ fdt_sw.begin_node("instance-remove")
368
+ fdt_sw.property_string("instance-name", name)
369
+ fdt_sw.end_node() # End instance-remove
370
+ fdt_sw.end_node() # End __overlay__
371
+ fdt_sw.end_node() # End fragment
372
+ fragment_id += 1
373
+
374
+ fdt_sw.end_node() # End root
375
+
376
+ dtb = fdt_sw.as_fdt()
377
+ dtb.pack()
378
+ return dtb.as_bytearray()