feat: add device passthru mode

reddevillg · dengbo11 · commit ca6a44e77c34 · 2026-04-30T13:13:08.000+08:00
Add --device-mode option to allow containers to share the host's /dev
directory.

Signed-off-by: reddevillg &lt;reddevillg@gmail.com&gt;
diff --git a/api/schema/v1.json b/api/schema/v1.json
@@ -1448,6 +1448,12 @@
               "$ref": "#/$defs/ExtensionDefine"
             }
           }
+        },
+        "device_mode": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DeviceOption"
+          }
         }
       }
     },
@@ -1530,6 +1536,12 @@
           }
         }
       }
+    },
+    "DeviceOption": {
+      "description": "device option",
+      "enum": [
+        "passthru"
+      ]
     }
   },
   "type": "object",
@@ -1680,6 +1692,9 @@
     },
     "CDIDeviceEntry": {
       "$ref": "#/$defs/CDIDeviceEntry"
+    },
+    "DeviceOption": {
+      "$ref": "#/$defs/DeviceOption"
     }
   }
 }
diff --git a/api/schema/v1.yaml b/api/schema/v1.yaml
@@ -1097,6 +1097,10 @@ $defs:
           type: array
           items:
             $ref: '#/$defs/ExtensionDefine'
+      device_mode:
+        type: array
+        items:
+          $ref: '#/$defs/DeviceOption'
   RunContextConfig:
     title: RunContextConfig
     type: object
@@ -1153,6 +1157,9 @@ $defs:
           checksum:
             description: CDI device spec checksum
             type: string
+  DeviceOption:
+    description: device option
+    enum: ["passthru"]
 type: object
 properties:
   # NOTE: "properties" is auto generated by referring all types is $defs
diff --git a/apps/ll-cli/src/main.cpp b/apps/ll-cli/src/main.cpp
@@ -31,6 +31,7 @@
 
 #include <algorithm>
 #include <functional>
+#include <map>
 #include <memory>
 #include <string_view>
 #include <thread>
@@ -185,9 +186,16 @@ ll-cli run org.deepin.demo -- bash -x /path/to/bash/script)"));
       ->delimiter(',')
       ->capture_default_str()
       ->allow_extra_args(false);
-    cliRun->add_option("--device", runOptions.devices, _("Add CDI devices"))
+    cliRun->add_option("--device", runOptions.cdiDevices, _("Add CDI devices"))
       ->delimiter(',')
       ->allow_extra_args(false);
+    const std::map<std::string, linglong::api::types::v1::DeviceOption> deviceOptionMap = {
+        { "passthru", linglong::api::types::v1::DeviceOption::Passthru },
+    };
+    cliRun->add_option("--device-mode", runOptions.deviceOptions, _("Add device options"))
+      ->delimiter(',')
+      ->transform(CLI::CheckedTransformer(deviceOptionMap, CLI::ignore_case))
+      ->allow_extra_args(false);
     cliRun->add_option("COMMAND", runOptions.commands, _("Run commands in a running sandbox"));
 }
 
diff --git a/libs/api/src/linglong/api/types/v1/DeviceOption.hpp b/libs/api/src/linglong/api/types/v1/DeviceOption.hpp
@@ -0,0 +1,39 @@
+// This file is generated by tools/codegen.sh
+// DO NOT EDIT IT.
+
+// clang-format off
+
+//  To parse this JSON data, first install
+//
+//      json.hpp  https://github.com/nlohmann/json
+//
+//  Then include this file, and then do
+//
+//     DeviceOption.hpp data = nlohmann::json::parse(jsonString);
+
+#pragma once
+
+#include <optional>
+#include <nlohmann/json.hpp>
+#include "linglong/api/types/v1/helper.hpp"
+
+namespace linglong {
+namespace api {
+namespace types {
+namespace v1 {
+/**
+* device option
+*/
+
+using nlohmann::json;
+
+/**
+* device option
+*/
+enum class DeviceOption : int { Passthru };
+}
+}
+}
+}
+
+// clang-format on
diff --git a/libs/api/src/linglong/api/types/v1/Generators.hpp b/libs/api/src/linglong/api/types/v1/Generators.hpp
@@ -60,6 +60,7 @@
 #include "linglong/api/types/v1/ExportDirs.hpp"
 #include "linglong/api/types/v1/DialogMessage.hpp"
 #include "linglong/api/types/v1/DialogHandShakePayload.hpp"
+#include "linglong/api/types/v1/DeviceOption.hpp"
 #include "linglong/api/types/v1/ContainerProcessStateInfo.hpp"
 #include "linglong/api/types/v1/CommonResult.hpp"
 #include "linglong/api/types/v1/CommonOptions.hpp"
@@ -265,6 +266,9 @@ void to_json(json & j, const UpgradeListResult & x);
 void from_json(const json & j, LinglongAPIV1 & x);
 void to_json(json & j, const LinglongAPIV1 & x);
 
+void from_json(const json & j, DeviceOption & x);
+void to_json(json & j, const DeviceOption & x);
+
 void from_json(const json & j, InteractionMessageType & x);
 void to_json(json & j, const InteractionMessageType & x);
 
@@ -1273,12 +1277,16 @@ j["version"] = x.version;
 }
 
 inline void from_json(const json & j, RuntimeConfigure& x) {
+x.deviceMode = get_stack_optional<std::vector<DeviceOption>>(j, "device_mode");
 x.env = get_stack_optional<std::map<std::string, std::string>>(j, "env");
 x.extDefs = get_stack_optional<std::map<std::string, std::vector<ExtensionDefine>>>(j, "ext_defs");
 }
 
 inline void to_json(json & j, const RuntimeConfigure & x) {
 j = json::object();
+if (x.deviceMode) {
+j["device_mode"] = x.deviceMode;
+}
 if (x.env) {
 j["env"] = x.env;
 }
@@ -1357,6 +1365,7 @@ x.commonOptions = get_stack_optional<CommonOptions>(j, "CommonOptions");
 x.commonResult = get_stack_optional<CommonResult>(j, "CommonResult");
 x.containerProcessStateInfo = get_stack_optional<ContainerProcessStateInfo>(j, "ContainerProcessStateInfo");
 x.deviceNode = get_stack_optional<DeviceNode>(j, "DeviceNode");
+x.deviceOption = get_stack_optional<DeviceOption>(j, "DeviceOption");
 x.dialogHandShakePayload = get_stack_optional<DialogHandShakePayload>(j, "DialogHandShakePayload");
 x.dialogMessage = get_stack_optional<DialogMessage>(j, "DialogMessage");
 x.exportDirs = get_stack_optional<ExportDirs>(j, "ExportDirs");
@@ -1432,6 +1441,9 @@ j["ContainerProcessStateInfo"] = x.containerProcessStateInfo;
 if (x.deviceNode) {
 j["DeviceNode"] = x.deviceNode;
 }
+if (x.deviceOption) {
+j["DeviceOption"] = x.deviceOption;
+}
 if (x.dialogHandShakePayload) {
 j["DialogHandShakePayload"] = x.dialogHandShakePayload;
 }
@@ -1548,6 +1560,18 @@ j["XDGDirectoryPermissions"] = x.xdgDirectoryPermissions;
 }
 }
 
+inline void from_json(const json & j, DeviceOption & x) {
+if (j == "passthru") x = DeviceOption::Passthru;
+else { throw std::runtime_error("Input JSON does not conform to schema!"); }
+}
+
+inline void to_json(json & j, const DeviceOption & x) {
+switch (x) {
+case DeviceOption::Passthru: j = "passthru"; break;
+default: throw std::runtime_error("Unexpected value in enumeration \"DeviceOption\": " + std::to_string(static_cast<int>(x)));
+}
+}
+
 inline void from_json(const json & j, InteractionMessageType & x) {
 if (j == "Downgrade") x = InteractionMessageType::Downgrade;
 else if (j == "Install") x = InteractionMessageType::Install;
diff --git a/libs/api/src/linglong/api/types/v1/LinglongAPIV1.hpp b/libs/api/src/linglong/api/types/v1/LinglongAPIV1.hpp
@@ -67,6 +67,7 @@ namespace linglong {
 namespace api {
 namespace types {
 namespace v1 {
+enum class DeviceOption : int;
 enum class InteractionMessageType : int;
 enum class State : int;
 }
@@ -101,6 +102,7 @@ std::optional<CommonOptions> commonOptions;
 std::optional<CommonResult> commonResult;
 std::optional<ContainerProcessStateInfo> containerProcessStateInfo;
 std::optional<DeviceNode> deviceNode;
+std::optional<DeviceOption> deviceOption;
 std::optional<DialogHandShakePayload> dialogHandShakePayload;
 std::optional<DialogMessage> dialogMessage;
 std::optional<ExportDirs> exportDirs;
diff --git a/libs/api/src/linglong/api/types/v1/RuntimeConfigure.hpp b/libs/api/src/linglong/api/types/v1/RuntimeConfigure.hpp
@@ -19,13 +19,24 @@
 
 #include "linglong/api/types/v1/ExtensionDefine.hpp"
 
+namespace linglong {
+namespace api {
+namespace types {
+namespace v1 {
+enum class DeviceOption : int;
+}
+}
+}
+}
+
 namespace linglong {
 namespace api {
 namespace types {
 namespace v1 {
 using nlohmann::json;
 
 struct RuntimeConfigure {
+std::optional<std::vector<DeviceOption>> deviceMode;
 std::optional<std::map<std::string, std::string>> env;
 /**
 * external extension definitions to extend the component
diff --git a/libs/linglong/src/linglong/cli/cli.cpp b/libs/linglong/src/linglong/cli/cli.cpp
@@ -623,8 +623,8 @@ int Cli::run(const RunOptions &options)
     if (runtimeConfig && runtimeConfig->extDefs) {
         opts.externalExtensionDefs = std::move(runtimeConfig->extDefs).value();
     }
-    if (!options.devices.empty()) {
-        auto cdiDevices = cdi::getCDIDevices(options.cdiSpecDir, options.devices);
+    if (!options.cdiDevices.empty()) {
+        auto cdiDevices = cdi::getCDIDevices(options.cdiSpecDir, options.cdiDevices);
         if (!cdiDevices) {
             handleCommonError(cdiDevices.error());
             return -1;
diff --git a/libs/linglong/src/linglong/cli/cli.h b/libs/linglong/src/linglong/cli/cli.h
@@ -60,7 +60,8 @@ struct RunOptions
     bool privileged{ false };
     std::vector<std::string> capsAdd;
     std::vector<std::string> cdiSpecDir = { "/etc/cdi", "/var/run/cdi" };
-    std::vector<std::string> devices;
+    std::vector<std::string> cdiDevices;
+    std::vector<api::types::v1::DeviceOption> deviceOptions;
 };
 
 struct EnterOptions
diff --git a/libs/linglong/src/linglong/runtime/container_builder.cpp b/libs/linglong/src/linglong/runtime/container_builder.cpp
@@ -68,6 +68,15 @@ std::string genContainerID(const api::types::v1::RunContextConfig &config) noexc
 auto RunContainerOptions::applyRuntimeConfig(
   const api::types::v1::RuntimeConfigure &runtimeConfig) noexcept -> utils::error::Result<void>
 {
+    if (runtimeConfig.deviceMode) {
+        for (const auto &option : *runtimeConfig.deviceMode) {
+            if (option == api::types::v1::DeviceOption::Passthru) {
+                this->devicePassthru = true;
+                break;
+            }
+        }
+    }
+
     if (runtimeConfig.env) {
         for (const auto &[key, value] : *runtimeConfig.env) {
             this->env.insert_or_assign(key, value);
@@ -82,6 +91,13 @@ auto RunContainerOptions::applyCliRunOptions(const cli::RunOptions &options) noe
 {
     LINGLONG_TRACE("apply cli run options to run config");
 
+    for (const auto &option : options.deviceOptions) {
+        if (option == api::types::v1::DeviceOption::Passthru) {
+            this->devicePassthru = true;
+            break;
+        }
+    }
+
     for (const auto &item : options.envs) {
         auto split = item.find('=');
         if (split == std::string::npos || split == 0) {
@@ -125,6 +141,11 @@ auto RunContainerOptions::getSecurityContexts() const noexcept
     return this->securityContexts;
 }
 
+auto RunContainerOptions::isDevicePassthruEnabled() const noexcept -> bool
+{
+    return this->devicePassthru;
+}
+
 auto RunContainerOptions::isPrivileged() const noexcept -> bool
 {
     return this->privileged;
@@ -441,7 +462,6 @@ auto ContainerBuilder::configureRunContainer(PreparedContainer &prepared,
     std::filesystem::path homePath{ homeEnv };
 
     prepared.cfgBuilder.setAnnotation(generator::ANNOTATION::LAST_PID, std::to_string(::getpid()))
-      .bindDevNode()
       .bindXDGRuntime()
       .bindRemovableStorageMounts()
       .bindHostRoot()
@@ -453,6 +473,12 @@ auto ContainerBuilder::configureRunContainer(PreparedContainer &prepared,
       .bindIPC()
       .forwardDefaultEnv();
 
+    if (options.isDevicePassthruEnabled()) {
+        prepared.cfgBuilder.bindDev(true);
+    } else {
+        prepared.cfgBuilder.bindDevNode();
+    }
+
     std::error_code ec;
     auto socketDir = prepared.context->getBundleDir() / "init";
     std::filesystem::create_directories(socketDir, ec);
diff --git a/libs/linglong/src/linglong/runtime/container_builder.h b/libs/linglong/src/linglong/runtime/container_builder.h
@@ -52,11 +52,13 @@ struct RunContainerOptions
     [[nodiscard]] auto getCapabilities() const noexcept -> const std::vector<std::string> &;
     [[nodiscard]] auto getSecurityContexts() const noexcept
       -> const std::vector<SecurityContextType> &;
+    [[nodiscard]] auto isDevicePassthruEnabled() const noexcept -> bool;
     [[nodiscard]] auto isPrivileged() const noexcept -> bool;
 
     CommonContainerOptions common;
 
     bool privileged{ false };
+    bool devicePassthru{ false };
     std::map<std::string, std::string> env;
     std::vector<std::string> capabilities;
     std::vector<SecurityContextType> securityContexts;
diff --git a/libs/linglong/tests/ll-tests/CMakeLists.txt b/libs/linglong/tests/ll-tests/CMakeLists.txt
@@ -49,6 +49,7 @@ pfl_add_executable(
   src/linglong/repo/config_test.cpp
   src/linglong/repo/ostree_repo_test.cpp
   src/linglong/repo/repo_cache_test.cpp
+  src/linglong/runtime/container_builder_test.cpp
   src/linglong/runtime/run_context_test.cpp
   src/linglong/utils/bash_command_helper_test.cpp
   src/linglong/utils/cmd_test.cpp
diff --git a/libs/linglong/tests/ll-tests/src/linglong/runtime/container_builder_test.cpp b/libs/linglong/tests/ll-tests/src/linglong/runtime/container_builder_test.cpp
@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 UnionTech Software Technology Co., Ltd.
+//
+// SPDX-License-Identifier: LGPL-3.0-or-later
+
+#include <gtest/gtest.h>
+
+#include "linglong/cli/cli.h"
+#include "linglong/runtime/container_builder.h"
+
+using namespace linglong;
+
+TEST(RunContainerOptionsTest, ApplyRuntimeConfigEnablesDevicePassthru)
+{
+    runtime::RunContainerOptions options;
+
+    api::types::v1::RuntimeConfigure runtimeConfig;
+    runtimeConfig.deviceMode =
+      std::vector<api::types::v1::DeviceOption>{ api::types::v1::DeviceOption::Passthru };
+
+    auto result = options.applyRuntimeConfig(runtimeConfig);
+    ASSERT_TRUE(result);
+    EXPECT_TRUE(options.isDevicePassthruEnabled());
+}
+
+TEST(RunContainerOptionsTest, ApplyCliRunOptionsEnablesDevicePassthru)
+{
+    runtime::RunContainerOptions options;
+    cli::RunOptions runOptions;
+    runOptions.deviceOptions = { api::types::v1::DeviceOption::Passthru };
+
+    auto result = options.applyCliRunOptions(runOptions);
+    ASSERT_TRUE(result);
+    EXPECT_TRUE(options.isDevicePassthruEnabled());
+}
diff --git a/libs/linglong/tests/ll-tests/src/linglong/utils/runtime_config_test.cpp b/libs/linglong/tests/ll-tests/src/linglong/utils/runtime_config_test.cpp
diff --git a/libs/oci-cfg-generators/src/linglong/oci-cfg-generators/container_cfg_builder.cpp b/libs/oci-cfg-generators/src/linglong/oci-cfg-generators/container_cfg_builder.cpp
diff --git a/libs/oci-cfg-generators/src/linglong/oci-cfg-generators/container_cfg_builder.h b/libs/oci-cfg-generators/src/linglong/oci-cfg-generators/container_cfg_builder.h
diff --git a/libs/utils/src/linglong/utils/runtime_config.cpp b/libs/utils/src/linglong/utils/runtime_config.cpp

Original file line number	Diff line number	Diff line change
`@@ -1448,6 +1448,12 @@`
`1448`	`1448`	`"$ref": "#/$defs/ExtensionDefine"`
`1449`	`1449`	`}`
`1450`	`1450`	`}`
	`1451`	`+ },`
	`1452`	`+ "device_mode": {`
	`1453`	`+ "type": "array",`
	`1454`	`+ "items": {`
	`1455`	`+ "$ref": "#/$defs/DeviceOption"`
	`1456`	`+ }`
`1451`	`1457`	`}`
`1452`	`1458`	`}`
`1453`	`1459`	`},`
`@@ -1530,6 +1536,12 @@`
`1530`	`1536`	`}`
`1531`	`1537`	`}`
`1532`	`1538`	`}`
	`1539`	`+ },`
	`1540`	`+ "DeviceOption": {`
	`1541`	`+ "description": "device option",`
	`1542`	`+ "enum": [`
	`1543`	`+ "passthru"`
	`1544`	`+ ]`
`1533`	`1545`	`}`
`1534`	`1546`	`},`
`1535`	`1547`	`"type": "object",`
`@@ -1680,6 +1692,9 @@`
`1680`	`1692`	`},`
`1681`	`1693`	`"CDIDeviceEntry": {`
`1682`	`1694`	`"$ref": "#/$defs/CDIDeviceEntry"`
	`1695`	`+ },`
	`1696`	`+ "DeviceOption": {`
	`1697`	`+ "$ref": "#/$defs/DeviceOption"`
`1683`	`1698`	`}`
`1684`	`1699`	`}`
`1685`	`1700`	`}`