From 4bd5a840c1ceae0459e8e797e7e8a5a44db7764a Mon Sep 17 00:00:00 2001 From: Roman Sirokov Date: Mon, 24 Aug 2026 09:12:06 +0000 Subject: [PATCH 1/3] fix(serve): validate --device via clap possible values (exit 2) Model `rocm serve --device` as a clap `ValueEnum` (`DevicePolicyArg`) so an invalid value is rejected by clap's usage validation (exit code 2) with the valid choices listed, instead of parsing as a free-form string and failing later in application logic with a generic "unsupported device policy" error (exit code 1). This makes `--device` consistent with every other enum-style argument in the CLI (`--engine`, config set-*, engines install, etc.), all of which use clap possible values. The historical aliases (`auto`/`gpu` for gpu_required, `cpu` for cpu_only) stay accepted for backward compatibility but are hidden from the advertised list, and the intentional cpu_only app-level rejection (exit 1 with a GPU-required message) is preserved. Adds regression tests asserting invalid `--device` is a clap InvalidValue usage error and that every value and alias still parses, and reworks the device possible-values sync test to read clap's structural possible values rather than a hand-written doc string. Signed-off-by: Roman Sirokov --- apps/rocm/src/main.rs | 125 +++++++++++++++++++++++++++--------------- 1 file changed, 80 insertions(+), 45 deletions(-) diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index 5b4ac58ade..a7f2e81b0c 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -346,9 +346,9 @@ rocm serve qwen2.5-7b-instruct --verbose --device gpu_required")] /// Engine to use. #[arg(long, value_parser = SUPPORTED_ENGINES)] engine: Option, - /// Device policy [possible values: gpu_required, gpu_preferred, cpu_only]. + /// Device policy. #[arg(long)] - device: Option, + device: Option, /// GPU device to serve on: `auto` (default; first free GPU) or a single /// index like `1`. #[arg(long, value_name = "INDEX|auto")] @@ -978,6 +978,38 @@ enum TelemetryModeArg { Off, } +/// User-facing `rocm serve --device` policy. +/// +/// Modeled as a clap `ValueEnum` so invalid input is rejected by clap's usage +/// validation (exit code 2, with the valid choices listed) rather than a generic +/// application error (exit code 1) — matching how every other enum-style CLI +/// argument behaves. The historical aliases (`auto`/`gpu` for `gpu_required`, +/// `cpu` for `cpu_only`) stay accepted for backward compatibility but are hidden +/// from the advertised list. +#[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)] +#[value(rename_all = "snake_case")] +enum DevicePolicyArg { + /// Require a ROCm GPU; fail if none is usable (the default). + #[value(alias = "auto", alias = "gpu")] + GpuRequired, + /// Prefer a ROCm GPU when one is available. + GpuPreferred, + /// Run on CPU only (not a supported fallback path in rocm serve). + #[value(alias = "cpu")] + CpuOnly, +} + +impl DevicePolicyArg { + /// Canonical policy string understood by [`parse_device_policy`]. + const fn as_policy_str(self) -> &'static str { + match self { + Self::GpuRequired => "gpu_required", + Self::GpuPreferred => "gpu_preferred", + Self::CpuOnly => "cpu_only", + } + } +} + #[derive(Clone, Copy, Debug, Eq, PartialEq, ValueEnum)] #[value(rename_all = "snake_case")] enum SandboxToolArg { @@ -4704,7 +4736,7 @@ fn engine_recipe_enables_tool_choice(hint: Option<&EngineRecipeHint>) -> bool { struct ServeArgs { model: String, engine: Option, - device: Option, + device: Option, gpu: Option, runtime_id: Option, env_id: Option, @@ -4843,7 +4875,7 @@ fn serve(args: ServeArgs) -> Result<()> { } else { None }; - let device_policy = parse_device_policy(device.as_deref())?; + let device_policy = parse_device_policy(device.as_ref().map(|policy| policy.as_policy_str()))?; let gpu_selection = parse_gpu_selection(gpu.as_deref())?; // CPU-only serving never pins a GPU, so skip GPU resolution entirely and // surface the explicit `--gpu` as ignored rather than printing a device the @@ -18053,23 +18085,7 @@ mod tests { } } - fn possible_values_listed_in_help(help: &str) -> Vec { - let marker = "[possible values:"; - let start = help - .find(marker) - .unwrap_or_else(|| panic!("help text missing `{marker}`: {help:?}")); - let rest = &help[start + marker.len()..]; - let end = rest - .find(']') - .unwrap_or_else(|| panic!("unterminated possible-values list in help: {help:?}")); - rest[..end] - .split(',') - .map(|value| value.trim().to_owned()) - .filter(|value| !value.is_empty()) - .collect() - } - - fn serve_arg_help(arg_id: &str) -> String { + fn serve_possible_values(arg_id: &str) -> Vec { let cli = Cli::command(); let serve = cli .find_subcommand("serve") @@ -18078,32 +18094,20 @@ mod tests { .get_arguments() .find(|arg| arg.get_id().as_str() == arg_id) .unwrap_or_else(|| panic!("serve has no `{arg_id}` argument")) - .get_help() - .map(ToString::to_string) - .unwrap_or_default() + .get_possible_values() + .iter() + .map(|value| value.get_name().to_owned()) + .collect() } - // `--engine` restricts its input to `SUPPORTED_ENGINES` via a clap - // `value_parser`, so the possible values are advertised in `--help` and shell - // completion structurally (not a hand-written doc string). `--device` stays - // free-form (it accepts aliases such as `auto`/`gpu` plus the intentional - // `cpu_only` rejection), so its advertised list is hand-written and guarded - // by a sync test below. Both guards keep the advertised lists honest. + // Both `--engine` and `--device` restrict their input to a fixed set via a + // clap `value_parser`/`ValueEnum`, so the possible values are advertised in + // `--help` and shell completion structurally (not a hand-written doc string) + // and invalid input is rejected as a usage error (exit code 2) with the valid + // choices listed. The sync tests below keep the advertised lists honest. #[test] fn serve_engine_help_lists_match_engine_inventory() { - let cli = Cli::command(); - let serve = cli - .find_subcommand("serve") - .expect("serve subcommand exists"); - let engine_arg = serve - .get_arguments() - .find(|arg| arg.get_id() == "engine") - .expect("serve has an `engine` argument"); - let mut listed: Vec = engine_arg - .get_possible_values() - .iter() - .map(|value| value.get_name().to_owned()) - .collect(); + let mut listed = serve_possible_values("engine"); let mut expected: Vec = builtin_engine_inventory() .iter() .map(|(name, _)| (*name).to_owned()) @@ -18118,7 +18122,7 @@ mod tests { #[test] fn serve_device_help_lists_match_device_policy_names() { - let mut listed = possible_values_listed_in_help(&serve_arg_help("device")); + let mut listed = serve_possible_values("device"); let mut expected: Vec = [ DevicePolicy::GpuRequired, DevicePolicy::GpuPreferred, @@ -18131,10 +18135,41 @@ mod tests { expected.sort(); assert_eq!( listed, expected, - "serve --device help possible-values must stay in sync with DevicePolicy names" + "serve --device possible-values must stay in sync with DevicePolicy names" ); } + #[test] + fn serve_rejects_unknown_device_policy_as_usage_error() { + // An invalid `--device` must fail clap's value validation (a usage error, + // exit code 2) rather than parsing as a free-form string and failing later + // in application logic (exit code 1). This keeps `--device` consistent with + // every other enum-style argument and lists the valid choices in the error. + let error = parse_serve(&["--device", "bogus"]).expect_err("invalid device rejected"); + assert_eq!(error.kind(), clap::error::ErrorKind::InvalidValue); + } + + #[test] + fn serve_accepts_device_policy_values_and_aliases() { + for (value, expected) in [ + ("gpu_required", DevicePolicyArg::GpuRequired), + ("gpu_preferred", DevicePolicyArg::GpuPreferred), + ("cpu_only", DevicePolicyArg::CpuOnly), + // Historical aliases stay accepted for backward compatibility. + ("auto", DevicePolicyArg::GpuRequired), + ("gpu", DevicePolicyArg::GpuRequired), + ("cpu", DevicePolicyArg::CpuOnly), + ] { + let cli = parse_serve(&["--device", value]).expect("device value parses"); + match cli.command { + Some(Command::Serve { device, .. }) => { + assert_eq!(device, Some(expected), "device value `{value}`"); + } + other => panic!("expected Serve, got {other:?}"), + } + } + } + fn parse_serve(args: &[&str]) -> Result { let mut argv = vec!["rocm", "serve", "qwen"]; argv.extend_from_slice(args); From a66f06900736f303c0435d5c7215d16c4c1fd609 Mon Sep 17 00:00:00 2001 From: Roman Sirokov Date: Thu, 27 Aug 2026 10:53:11 +0300 Subject: [PATCH 2/3] fix(serve): correct --device help text and hide cpu_only choice The per-variant ValueEnum doc comments render in `serve --help`, shell completions, and the invalid-value suggestion list. `gpu_preferred` previously read "Prefer a ROCm GPU when one is available", which is misleading: parse_device_policy maps gpu_preferred to GpuRequired and rocm serve has no CPU fallback path. Reword it to state it behaves identically to gpu_required. cpu_only is always rejected (rocm serve requires GPU execution), so hide it from the advertised choices with #[value(hide = true)] while keeping it parseable so the deliberate rejection message is preserved. Add device_policy_arg_maps_through_parse_device_policy to guard the DevicePolicyArg::as_policy_str -> parse_device_policy mapping (gpu_required and gpu_preferred resolve to GpuRequired; cpu_only is rejected), closing the previously untested conversion path. Signed-off-by: Roman Sirokov --- apps/rocm/src/main.rs | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index a7f2e81b0c..6e754ef193 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -992,15 +992,22 @@ enum DevicePolicyArg { /// Require a ROCm GPU; fail if none is usable (the default). #[value(alias = "auto", alias = "gpu")] GpuRequired, - /// Prefer a ROCm GPU when one is available. + /// Accepted for compatibility; behaves identically to `gpu_required` + /// (rocm serve has no CPU fallback path). GpuPreferred, - /// Run on CPU only (not a supported fallback path in rocm serve). - #[value(alias = "cpu")] + /// Accepted but always rejected: rocm serve has no CPU fallback path, so + /// this exits with an error. Hidden from `--help`, shell completions and the + /// invalid-value suggestion list so it is never advertised as usable, while + /// still parsing so the deliberate rejection message is preserved. + #[value(alias = "cpu", hide = true)] CpuOnly, } impl DevicePolicyArg { - /// Canonical policy string understood by [`parse_device_policy`]. + /// Canonical policy string understood by [`parse_device_policy`]. Routing the + /// parsed variant back through the string keeps `parse_device_policy` the + /// single choke point that enforces the `cpu_only` rejection across every + /// caller, rather than adding a second conversion path that could bypass it. const fn as_policy_str(self) -> &'static str { match self { Self::GpuRequired => "gpu_required", @@ -18170,6 +18177,31 @@ mod tests { } } + #[test] + fn device_policy_arg_maps_through_parse_device_policy() { + // `as_policy_str` feeds the parsed variant back through + // `parse_device_policy`, the single choke point enforcing the strict + // no-CPU policy. Guard the mapping so a mis-typed arm (e.g. `CpuOnly => + // "gpu_required"`) cannot silently turn the deliberate CPU rejection into + // a GPU-required serve while every other test stays green. + assert_eq!( + parse_device_policy(Some(DevicePolicyArg::GpuRequired.as_policy_str())) + .expect("gpu_required parses"), + DevicePolicy::GpuRequired + ); + assert_eq!( + parse_device_policy(Some(DevicePolicyArg::GpuPreferred.as_policy_str())) + .expect("gpu_preferred parses"), + DevicePolicy::GpuRequired + ); + // `cpu_only` must still be rejected outright rather than mapped to a + // GPU policy. + assert!( + parse_device_policy(Some(DevicePolicyArg::CpuOnly.as_policy_str())).is_err(), + "cpu_only must be rejected" + ); + } + fn parse_serve(args: &[&str]) -> Result { let mut argv = vec!["rocm", "serve", "qwen"]; argv.extend_from_slice(args); From c4e9ac6fda8abe512a9003d1f2e4247daa0a30c1 Mon Sep 17 00:00:00 2001 From: Roman Sirokov Date: Thu, 27 Aug 2026 12:13:58 +0000 Subject: [PATCH 3/3] docs(serve): stop advertising hidden cpu_only device value MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hiding `cpu_only` from `--device` help/completion left three surfaces still presenting it as a real choice. Align them with what the CLI now advertises: - README serve synopsis dropped `cpu_only` from the --device value list. - Removed the '--gpu is ignored with --device cpu_only (the model runs on CPU)' sentence: cpu_only is rejected (exit 1), never runs on CPU, so the line advertised a fallback path that does not exist (AGENTS.md §6). - Corrected the drifted test comment to note cpu_only is #[value(hide = true)] and that serve_device_help_lists_match_device_policy_names compares against the full DevicePolicy set (hidden entries included). Doc/comment only; no behavior change. Signed-off-by: Roman Sirokov --- README.md | 5 ++--- apps/rocm/src/main.rs | 13 +++++++++---- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index bae9b4c09b..855654fbc2 100644 --- a/README.md +++ b/README.md @@ -295,7 +295,7 @@ Start a local OpenAI-compatible model server: ``` rocm serve [--engine lemonade|vllm] - [--device gpu_required|gpu_preferred|cpu_only] + [--device gpu_required|gpu_preferred] [--gpu auto|] [--runtime-id KEY | --env-id ID] [--host HOST] [--port PORT] @@ -356,8 +356,7 @@ not already used by another rocm-cli server (managed or foreground), falling back to the GPU with the most free memory. Pass a single index (`--gpu 1`) to pin a specific device. The selected GPU is exposed to the engine via `HIP_VISIBLE_DEVICES`. Serving one -model across multiple GPUs is not supported. `--gpu` is ignored with -`--device cpu_only` (the model runs on CPU). Because selection uses the +model across multiple GPUs is not supported. Because selection uses the `amd-smi` ordinal but is applied via `HIP_VISIBLE_DEVICES`, rocm-cli warns when `ROCR_VISIBLE_DEVICES` is set, since the two orderings can diverge. diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index 6e754ef193..a17296c998 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -18108,10 +18108,15 @@ mod tests { } // Both `--engine` and `--device` restrict their input to a fixed set via a - // clap `value_parser`/`ValueEnum`, so the possible values are advertised in - // `--help` and shell completion structurally (not a hand-written doc string) - // and invalid input is rejected as a usage error (exit code 2) with the valid - // choices listed. The sync tests below keep the advertised lists honest. + // clap `value_parser`/`ValueEnum`, so invalid input is rejected as a usage + // error (exit code 2) with the accepted choices listed. Values are advertised + // in `--help` and shell completion structurally (not a hand-written doc + // string), with one deliberate exception: `--device cpu_only` is + // `#[value(hide = true)]` — still accepted so its exit-1 rejection message + // survives, but kept out of help and completion. The sync tests below keep the + // advertised lists honest; `serve_device_help_lists_match_device_policy_names` + // compares against the full `DevicePolicy` set (hidden entries included, via + // `get_possible_values`), so a dropped or renamed variant still fails. #[test] fn serve_engine_help_lists_match_engine_inventory() { let mut listed = serve_possible_values("engine");