Add C++ backend-device placement foundation

The native server needs a placement contract that can carry target and draft backend/device choices into later mixed-backend and layer-split work without growing ad hoc CLI flags. Backend and GPU id are one placement concept, so the server now exposes device specs instead of separate backend and GPU options.

This keeps the current native server behavior conservative: the parser accepts target and draft device specs, logs resolved placement, and rejects unsupported mixed-backend or target layer-split combinations until the runtime paths are implemented.

Constraint: Native C++ server binaries are still compiled for one GPU backend at a time.

Constraint: Target layer split remains rejected in the native server until the runtime path is wired.

Rejected: Keep --target-backend plus --gpu as the long-term public surface | backend and device id should not be split across unrelated CLI flags.

Confidence: high

Scope-risk: low

Tested: cmake --build dflash/build-cuda-draft-gpu-placement --target dflash_server -j 4

Tested: cmake --build dflash/build-hip-draft-gpu-placement --target dflash_server -j 4

Tested: dflash_server usage and placement-parse smoke checks

Tested: git diff --check

Author: weicj

dflash/src/common/backend_factory.cpp

@@ -37,7 +37,7 @@ std::unique_ptr<ModelBackend> create_backend(const BackendArgs & args) {
         cfg.target_path        = args.model_path;
         cfg.draft_path         = args.draft_path;
         cfg.device             = args.device;
-        cfg.draft_gpu          = args.draft_gpu;
+        cfg.draft_gpu          = args.draft_device.gpu;
         cfg.stream_fd          = args.stream_fd;
         cfg.fa_window          = args.fa_window;
         cfg.kq_stride_pad      = args.kq_stride_pad;

dflash/src/common/backend_factory.h

@@ -11,7 +11,7 @@
 #pragma once
 
 #include "model_backend.h"
-#include "device_placement.h"
+#include "placement/placement_config.h"
 
 #include <memory>
 #include <string>
@@ -30,7 +30,7 @@ struct BackendArgs {
 
     // Device placement
     DevicePlacement device;
-    int             draft_gpu    = 0;
+    DevicePlacement draft_device;
 
     // I/O — only used when running under daemon_loop (legacy). The new
     // server passes -1 and uses on_token callbacks instead.

dflash/src/common/device_placement.h

@@ -1,31 +1,6 @@
-// Device placement configuration for model backends.
-//
-// Describes which GPU(s) to use for a model. Supports:
-//   - Single-GPU: just gpu field
-//   - Multi-GPU layer-split: layer_split_gpus + optional weights
-//   - Peer access between GPUs
+// Compatibility include for older common/device_placement.h users.
+// New C++ placement code should include placement/placement_config.h.
 
 #pragma once
 
-#include <vector>
-
-namespace dflash::common {
-
-struct DevicePlacement {
-    int gpu = 0;                              // primary GPU (single-GPU mode)
-
-    // Multi-GPU layer-split. Empty = single GPU mode.
-    std::vector<int>    layer_split_gpus;     // GPU IDs for each shard
-    std::vector<double> layer_split_weights;  // proportional layer distribution (optional)
-
-    bool peer_access = false;                 // enable CUDA peer access between GPUs
-    int  max_ctx     = 8192;                  // max KV cache context length
-
-    bool is_layer_split() const { return layer_split_gpus.size() > 1; }
-
-    int primary_gpu() const {
-        return layer_split_gpus.empty() ? gpu : layer_split_gpus[0];
-    }
-};
-
-}  // namespace dflash::common
+#include "placement/placement_config.h"

dflash/src/common/layer_split_utils.h

@@ -5,7 +5,7 @@
 
 #pragma once
 
-#include "device_placement.h"
+#include "placement/placement_config.h"
 
 #include <string>
 #include <utility>

dflash/src/gemma4/gemma4_backend.h

@@ -6,7 +6,7 @@
 #pragma once
 
 #include "common/model_backend.h"
-#include "common/device_placement.h"
+#include "placement/placement_config.h"
 #include "gemma4_internal.h"
 #include "common/sampler.h"
 

dflash/src/gemma4/gemma4_daemon.h

@@ -2,7 +2,7 @@
 
 #pragma once
 
-#include "device_placement.h"
+#include "placement/placement_config.h"
 #include <string>
 
 namespace dflash::common {

dflash/src/laguna/laguna_daemon.h

@@ -13,7 +13,7 @@
 
 #pragma once
 
-#include "device_placement.h"
+#include "placement/placement_config.h"
 #include <string>
 #include "ggml.h"
 

dflash/src/placement/placement_backend.h

@@ -0,0 +1,54 @@
+// Backend placement identifiers shared by C++ server/runtime code.
+
+#pragma once
+
+#include <string>
+
+namespace dflash::common {
+
+enum class PlacementBackend {
+    Auto,
+    Cuda,
+    Hip,
+};
+
+inline const char * placement_backend_name(PlacementBackend backend) {
+    switch (backend) {
+        case PlacementBackend::Auto: return "auto";
+        case PlacementBackend::Cuda: return "cuda";
+        case PlacementBackend::Hip:  return "hip";
+    }
+    return "auto";
+}
+
+inline bool parse_placement_backend(const std::string & value,
+                                    PlacementBackend & out) {
+    if (value == "auto") {
+        out = PlacementBackend::Auto;
+        return true;
+    }
+    if (value == "cuda") {
+        out = PlacementBackend::Cuda;
+        return true;
+    }
+    if (value == "hip") {
+        out = PlacementBackend::Hip;
+        return true;
+    }
+    return false;
+}
+
+inline PlacementBackend compiled_placement_backend() {
+#if defined(DFLASH27B_BACKEND_HIP) || defined(GGML_USE_HIP)
+    return PlacementBackend::Hip;
+#else
+    return PlacementBackend::Cuda;
+#endif
+}
+
+inline bool placement_backend_supported(PlacementBackend backend) {
+    return backend == PlacementBackend::Auto ||
+           backend == compiled_placement_backend();
+}
+
+}  // namespace dflash::common

dflash/src/placement/placement_config.h

@@ -0,0 +1,105 @@
+// Device placement configuration for model backends.
+//
+// Describes which backend device(s) to use for a model. Supports:
+//   - Single-GPU: backend + gpu fields, exposed as cuda:0 / hip:0 / auto:0
+//   - Multi-GPU layer-split: one backend + layer_split_gpus + optional weights
+//   - Peer access between GPUs
+
+#pragma once
+
+#include "placement_backend.h"
+
+#include <cstdlib>
+#include <string>
+#include <vector>
+
+namespace dflash::common {
+
+struct DevicePlacement {
+    PlacementBackend backend = PlacementBackend::Auto;
+    int gpu = 0;                              // primary GPU (single-GPU mode)
+
+    // Multi-GPU layer-split. Empty = single GPU mode.
+    std::vector<int>    layer_split_gpus;     // GPU IDs for each shard
+    std::vector<double> layer_split_weights;  // proportional layer distribution (optional)
+
+    bool peer_access = false;                 // enable CUDA/HIP peer access between GPUs
+    int  max_ctx     = 8192;                  // max KV cache context length
+
+    bool is_layer_split() const { return layer_split_gpus.size() > 1; }
+
+    int primary_gpu() const {
+        return layer_split_gpus.empty() ? gpu : layer_split_gpus[0];
+    }
+};
+
+inline std::string placement_device_name(const DevicePlacement & device) {
+    return std::string(placement_backend_name(device.backend)) + ":" +
+           std::to_string(device.primary_gpu());
+}
+
+inline bool parse_placement_device(const std::string & value,
+                                   DevicePlacement & out) {
+    const std::size_t sep = value.find(':');
+    if (sep == std::string::npos || sep == 0 || sep + 1 >= value.size()) {
+        return false;
+    }
+
+    PlacementBackend backend = PlacementBackend::Auto;
+    if (!parse_placement_backend(value.substr(0, sep), backend)) {
+        return false;
+    }
+
+    const std::string gpu_text = value.substr(sep + 1);
+    char * end = nullptr;
+    long gpu = std::strtol(gpu_text.c_str(), &end, 10);
+    if (end == gpu_text.c_str() || *end != '\0' || gpu < 0) {
+        return false;
+    }
+
+    out.backend = backend;
+    out.gpu = static_cast<int>(gpu);
+    out.layer_split_gpus.clear();
+    out.layer_split_weights.clear();
+    return true;
+}
+
+inline bool parse_placement_device_list(const std::string & value,
+                                        DevicePlacement & out) {
+    if (value.empty()) return false;
+
+    std::vector<int> gpus;
+    PlacementBackend backend = PlacementBackend::Auto;
+    bool have_backend = false;
+
+    std::size_t begin = 0;
+    while (begin < value.size()) {
+        const std::size_t end = value.find(',', begin);
+        const std::string item = value.substr(
+            begin,
+            end == std::string::npos ? std::string::npos : end - begin);
+        if (item.empty()) return false;
+
+        DevicePlacement parsed;
+        if (!parse_placement_device(item, parsed)) return false;
+        if (!have_backend) {
+            backend = parsed.backend;
+            have_backend = true;
+        } else if (parsed.backend != backend) {
+            return false;
+        }
+        gpus.push_back(parsed.gpu);
+
+        if (end == std::string::npos) break;
+        begin = end + 1;
+    }
+
+    if (gpus.empty()) return false;
+    out.backend = backend;
+    out.gpu = gpus[0];
+    out.layer_split_gpus = gpus.size() > 1 ? gpus : std::vector<int>{};
+    out.layer_split_weights.clear();
+    return true;
+}
+
+}  // namespace dflash::common

dflash/src/qwen3/qwen3_backend.h

@@ -12,7 +12,7 @@
 #pragma once
 
 #include "common/model_backend.h"
-#include "common/device_placement.h"
+#include "placement/placement_config.h"
 #include "qwen3_drafter_model.h"
 #include "qwen3_drafter.h"
 #include "common/sampler.h"