| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <20251019061631.2235405-11-xiyou.wangcong@gmail.com>
Date: Sat, 18 Oct 2025 23:16:24 -0700
From: Cong Wang <xiyou.wangcong@...il.com>
To: linux-kernel@...r.kernel.org
Cc: jiri@...nulli.us,
stefanha@...hat.com,
multikernel@...ts.linux.dev,
pasha.tatashin@...een.com,
Cong Wang <cwang@...tiernel.io>,
Andrew Morton <akpm@...ux-foundation.org>,
Baoquan He <bhe@...hat.com>,
Alexander Graf <graf@...zon.com>,
Mike Rapoport <rppt@...nel.org>,
Changyuan Lyu <changyuanl@...gle.com>,
kexec@...ts.infradead.org,
linux-mm@...ck.org
Subject: [RFC Patch v2 10/16] Documentation: Add multikernel usage
From: Cong Wang <cwang@...tiernel.io>
Signed-off-by: Cong Wang <cwang@...tiernel.io>
---
Documentation/multikernel/usage.rst | 215 ++++++++++++++++++++++++++++
1 file changed, 215 insertions(+)
create mode 100644 Documentation/multikernel/usage.rst
diff --git a/Documentation/multikernel/usage.rst b/Documentation/multikernel/usage.rst
new file mode 100644
index 000000000000..a2ec8d56ca1d
--- /dev/null
+++ b/Documentation/multikernel/usage.rst
@@ -0,0 +1,215 @@
+===================================
+Multikernel Kernfs Interface Usage
+===================================
+
+Overview
+========
+
+The multikernel kernfs interface provides a clean, user-friendly way to manage multikernel instances through the filesystem. The interface is located at ``/sys/fs/multikernel/`` and supports automatic instance creation from multikernel device trees.
+
+Architecture
+============
+
+::
+
+ /sys/fs/multikernel/
+ ├── device_tree # Root-level DTB upload (write-only)
+ └── instances/ # Instance directory
+ ├── web-server/ # Instance created from DTB
+ │ ├── id # Instance ID (read-only)
+ │ ├── status # Instance status (read-only)
+ │ └── device_tree_source # Instance DTB in DTS format (read-only)
+ ├── database/ # Another instance
+ │ ├── id
+ │ ├── status
+ │ └── device_tree_source
+ └── ...
+
+Workflow
+========
+
+Phase 1: Instance Creation (Automatic from DTB)
+------------------------------------------------
+
+1. **Create Multikernel Device Tree**
+
+ Create a device tree with multiple instances:
+
+ .. code-block:: dts
+
+ /dts-v1/;
+ / {
+ compatible = "multikernel-v1";
+
+ instances {
+ web-server {
+ id = <1>;
+ resources {
+ cpus = <1>;
+ memory-bytes = <0x20000000>; // 512MB
+ };
+ };
+
+ database {
+ id = <2>;
+ resources {
+ cpus = <2 3>;
+ memory-bytes = <0x40000000>; // 1GB
+ };
+ };
+ };
+ };
+
+2. **Upload Multikernel DTB**
+
+ .. code-block:: bash
+
+ # Compile device tree to binary format
+ dtc -O dtb -o multikernel.dtb multikernel.dts
+
+ # Upload DTB to create instances automatically
+ cat multikernel.dtb > /sys/fs/multikernel/device_tree
+
+ This automatically:
+
+ - Validates DTB format and multikernel-v1 compatibility
+ - Parses each instance in the ``/instances`` node
+ - Creates instance directories under ``instances/``
+ - Reserves memory and CPU resources for each instance
+ - Updates each instance status to "ready"
+
+3. **Check Created Instances**
+
+ .. code-block:: bash
+
+ # List created instances
+ ls /sys/fs/multikernel/instances/
+ # Output: database web-server
+
+ # Check instance details
+ cat /sys/fs/multikernel/instances/web-server/id
+ # Output: 1
+
+ cat /sys/fs/multikernel/instances/web-server/status
+ # Output: ready
+
+ # View instance device tree
+ cat /sys/fs/multikernel/instances/web-server/device_tree_source
+ # Output: DTS format showing the instance configuration
+
+Phase 2: Kernel Loading (Kexec Integration)
+--------------------------------------------
+
+1. **Load Kernel Image**
+
+ .. code-block:: bash
+
+ # Load kernel for instance ID 1 (web-server)
+ kexec_file_load(..., KEXEC_MULTIKERNEL | KEXEC_MK_ID(1))
+
+ This:
+
+ - Finds pre-reserved resources for instance ID 1
+ - Creates kimage using pre-allocated memory and CPU resources
+ - Updates status to "loading" → "active"
+ - Preserves instance DTB for KHO (Kexec HandOver) restoration
+
+2. **Instance DTB Preservation**
+
+ The multikernel system automatically preserves each instance's device tree during kexec for restoration in the spawn kernel. The spawn kernel will:
+
+ - Detect multikernel KHO data during early boot
+ - Restore the instance's DTB and recreate the instance structure
+ - Re-reserve the same memory and CPU resources
+
+Device Tree Format
+==================
+
+Multikernel DTB Structure
+--------------------------
+
+The multikernel device tree uses the ``/instances`` structure with ``multikernel-v1`` compatibility:
+
+.. code-block:: dts
+
+ /dts-v1/;
+ / {
+ compatible = "multikernel-v1";
+
+ instances {
+ web-server {
+ id = <1>;
+ resources {
+ cpus = <1>; // CPU ID 1
+ memory-bytes = <0x20000000>; // 512MB
+ };
+ };
+
+ database {
+ id = <2>;
+ resources {
+ cpus = <2 3>; // CPU IDs 2 and 3
+ memory-bytes = <0x40000000>; // 1GB
+ };
+ };
+
+ load-balancer {
+ id = <3>;
+ resources {
+ cpus = <0>; // CPU ID 0
+ memory-bytes = <0x10000000>; // 256MB
+ };
+ };
+ };
+ };
+
+Per-Instance DTB Format
+-----------------------
+
+When viewing an instance's ``device_tree_source``, it appears in per-instance format:
+
+.. code-block:: dts
+
+ /dts-v1/;
+
+ /web-server {
+ compatible = "multikernel-v1";
+ id = <1>;
+ resources {
+ cpus = <1>;
+ memory-bytes = <0x20000000>; // 512 MB
+ };
+ };
+
+Resource Properties
+-------------------
+
+- **cpus**: Array of CPU IDs to assign to this instance
+- **memory-bytes**: Memory size in bytes (must be page-aligned)
+- **id**: Unique instance identifier used for kexec operations
+
+The system validates that:
+
+- CPU IDs are valid and available
+- Memory requests don't exceed available multikernel pool
+- Instance IDs are unique
+- All values are properly aligned
+
+Instance States
+===============
+
+- **empty**: Instance created but no resources allocated yet
+- **ready**: DTB processed, resources reserved, ready for kexec
+- **loading**: Kernel being loaded via kexec
+- **active**: Kernel running in this instance
+- **failed**: Error occurred during any phase
+
+Interface Restrictions
+======================
+
+The new kernfs interface has the following restrictions:
+
+- **No manual instance creation**: Use ``mkdir`` under ``instances/`` is disabled
+- **No direct DTB upload to instances**: Instances don't have writable ``device_tree`` files
+- **Centralized DTB management**: All instances must be created via the root ``device_tree`` file
+- **Read-only instance files**: All instance attributes are read-only for consistency
--
2.34.1
Powered by blists - more mailing lists