Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 9 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -380,14 +380,15 @@ position.
reads that text first: quotes, `$(...)` and a leading `-` in a pasted error
can be changed, run, or taken as a flag.
- `--symptom-file PATH` reads the same text from a file instead, or from
standard input when PATH is `-`, so no quoting is needed. It cannot be
combined with `--symptom`. The text that arrives is matched as `--symptom`
would match it, minus one trailing line break. A UTF-8 byte-order mark is
dropped and a UTF-16 file with a byte-order mark (what Windows PowerShell's
`>` writes) is decoded; anything else must be UTF-8. A file that cannot be
read, input that is not text, or input larger than 16 MiB is a usage error
(exit code 2). With nothing piped in, paste the error at the terminal and
end it with Ctrl-D at the start of a line (Ctrl-Z then Enter on Windows).
standard input when PATH is `-`, so no quoting is needed (a file named `-`
is passed as `./-`). It cannot be combined with `--symptom`. The text that
arrives is matched as `--symptom` would match it, minus one trailing line
break. A UTF-8 byte-order mark is dropped and a UTF-16 file with a
byte-order mark (what Windows PowerShell's `>` writes) is decoded; anything
else must be UTF-8. A file that cannot be read, input that is not text, or
input larger than 16 MiB is a usage error (exit code 2). With nothing piped
in, paste the error at the terminal and end it with Ctrl-D at the start of
a line (Ctrl-Z then Enter on Windows).

```bash
# bash (Linux, WSL): the quoted 'EOF' keeps the shell out of the paste
Expand Down
5 changes: 5 additions & 0 deletions apps/rocm/src/advised_commands.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2126,6 +2126,9 @@ fn a_heredoc_ends_the_command() {
"rocm diagnose --symptom-file - <<\"EOF\"",
"rocm diagnose --symptom-file - << EOF",
"rocm diagnose --symptom-file - <<EOF",
// A here-string (`<<<`) ends it the same way.
"rocm diagnose --symptom-file - <<< \"text\"",
"rocm diagnose --symptom-file - <<<text",
] {
assert_eq!(
command_parts(raw),
Expand All @@ -2143,6 +2146,8 @@ fn a_heredoc_ends_the_command() {
"rocm diagnose --symptom-file - <<'EOF' && rocm frobnicate --x",
"rocm diagnose --symptom-file - <<EOF; rocm frobnicate --x",
"rocm diagnose --symptom-file - << EOF || rocm frobnicate --x",
// A here-string (`<<<`) is a redirection too.
"rocm diagnose --symptom-file - <<< \"text\" && rocm frobnicate --x",
] {
assert_eq!(
command_parts(raw),
Expand Down
3 changes: 2 additions & 1 deletion apps/rocm/src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,8 @@ pub(crate) enum Command {
#[arg(long, value_name = "TEXT")]
symptom: Option<String>,
/// Read the error text from a file instead, or from standard input
/// when PATH is `-`, so no shell quoting is needed.
/// when PATH is `-`, so no shell quoting is needed. A file named `-`
/// is passed as `./-`.
///
/// The text that arrives is matched as `--symptom` would match it,
/// with one trailing line break removed (shells and editors add one).
Expand Down
44 changes: 36 additions & 8 deletions apps/rocm/src/symptom_input.rs
Original file line number Diff line number Diff line change
Expand Up @@ -145,27 +145,32 @@ fn read_symptom(reader: impl Read, source: &str) -> Result<String, SymptomFileEr
}

/// UTF-8 (a leading byte-order mark dropped), or UTF-16 announced by its
/// byte-order mark. The error says where decoding failed. Takes the buffer by
/// value so UTF-8 becomes the string in place, without a second buffer.
/// byte-order mark. The error says where decoding failed, as an offset from the
/// start of the input. Takes the buffer by value so UTF-8 becomes the string in
/// place, without a second buffer.
fn decode(mut bytes: Vec<u8>) -> Result<String, String> {
if bytes.starts_with(&[0xEF, 0xBB, 0xBF]) {
bytes.drain(..3);
return utf8(bytes);
const UTF8_BOM: [u8; 3] = [0xEF, 0xBB, 0xBF];
if bytes.starts_with(&UTF8_BOM) {
bytes.drain(..UTF8_BOM.len());
return utf8(bytes, UTF8_BOM.len());
}
if let Some(rest) = bytes.strip_prefix(&[0xFF, 0xFE]) {
return utf16(rest, u16::from_le_bytes);
}
if let Some(rest) = bytes.strip_prefix(&[0xFE, 0xFF]) {
return utf16(rest, u16::from_be_bytes);
}
utf8(bytes)
utf8(bytes, 0)
}

fn utf8(bytes: Vec<u8>) -> Result<String, String> {
/// `bytes` as UTF-8. `skipped` is how many bytes of the input came before
/// them (a byte-order mark), so the offset in an error counts from the start
/// of the input, where the user can find the byte.
fn utf8(bytes: Vec<u8>, skipped: usize) -> Result<String, String> {
String::from_utf8(bytes).map_err(|error| {
format!(
"it is not valid UTF-8 (invalid byte at offset {})",
error.utf8_error().valid_up_to()
skipped + error.utf8_error().valid_up_to()
)
})
}
Expand Down Expand Up @@ -257,6 +262,13 @@ mod tests {
assert!(message.contains("offset 10"), "{message}");
assert!(message.contains("UTF-8"), "{message}");

// Behind a UTF-8 byte-order mark the offset still counts from the
// start of the input, so it points at the byte in the file.
let mut with_bom = vec![0xEF, 0xBB, 0xBF];
with_bom.extend_from_slice(b"HIP error \xff at");
let message = read(&with_bom).unwrap_err().to_string();
assert!(message.contains("offset 13"), "{message}");

// A UTF-16 BOM with an odd tail, and one with a lone surrogate.
assert!(matches!(
read(&[0xFF, 0xFE, 0x41]),
Expand Down Expand Up @@ -314,6 +326,22 @@ mod tests {
assert_eq!(resolve(None, None).unwrap(), None);
}

// `-` alone means standard input, so a file literally named `-` is reached
// as `./-`, which is what the documentation tells the user. The two
// spellings are different paths, and a path that is not `-` is opened as a
// file whatever the working directory.
#[test]
fn a_file_named_dash_is_read_as_a_file_not_as_standard_input() {
assert_ne!(Path::new("./-").as_os_str(), STDIN_PATH);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

assert_ne! compares two literals, and the resolve below uses an absolute tempdir path, so neither exercises ./-; the test would pass with any non-- path. Consider driving resolve with a real relative ./- path, or note that this only pins the whole-path comparison.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, and I took the second option: the description no longer says the test uses ./-. It now says the test compares the two literals and reads a file named - through its absolute path, and that a relative ./- is not driven through resolve because that needs a change of the working directory in parallel tests. I did not change the code, to keep the approved commit as it is. I also added the line on why there is no scenario for the BOM offset.

let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("-");
std::fs::write(&path, "from the file named dash\n").unwrap();
assert_eq!(
resolve(None, Some(&path)).unwrap().as_deref(),
Some("from the file named dash")
);
}

#[test]
fn a_bad_file_is_a_usage_error_naming_the_command() {
let error = usage_error(&SymptomFileError::TooLarge {
Expand Down
3 changes: 3 additions & 0 deletions docs/manual-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -1664,6 +1664,9 @@ Then, in an empty directory, hand it over in each shell you have:
`rocm diagnose --symptom-file error.txt`.
- Any shell, nothing piped in: `rocm diagnose --symptom-file -`, paste at the
prompt, and end the input as the hint printed on the first line says.
- A file named `-`: save the paste as `-` and run
`rocm diagnose --symptom-file ./-`. It reports the same causes; a bare `-`
would read standard input instead.

Expected result:

Expand Down
12 changes: 11 additions & 1 deletion docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -4469,7 +4469,17 @@ hold the behaviour end to end, GPU or not:
pipe), so nothing in it can run by construction; the scenario asserts the
diagnosis, not the absence of something no shell could do. The paste is
ASCII: Windows PowerShell 5.1 pipes text as ASCII, which is why the docs
send PowerShell users through a file instead.
send PowerShell users through a file instead. The cmd.exe and Windows
PowerShell runs need a Windows host, so in CI they run only on the
self-hosted Strix Halo Windows lanes: `e2e-gpu-strix-windows` in
[e2e-selfhosted.yml](../.github/workflows/e2e-selfhosted.yml) (on pull
requests that touch the serve paths, on pushes to `main` and `release/**`,
and in the merge queue) and the scheduled
`e2e-gpu-nightly-strix-windows` in
[nightly.yml](../.github/workflows/nightly.yml). Neither is a required
check. The required `E2E tests` job in [ci.yml](../.github/workflows/ci.yml)
runs only the bash half, on Linux, and ci.yml's Windows lane does not run
this scenario.
- `diagnose-60` (Linux and WSL lanes only, like every pseudo-terminal
scenario here; the Windows key is checked by hand in
[manual-testing.md](manual-testing.md) section 13) runs
Expand Down
4 changes: 2 additions & 2 deletions docs/wsl.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,8 +189,8 @@ Eight entries that are not WSL-specific also run on WSL: `fix-1-arch`,
`fix-2-unset-override`, `fix-6-path`, `fix-8-wheel-rocm`, `fix-16-vllm-oom`,
`fix-17-torch-dlpack`, `fix-18-comgr-conflict`, and `fix-19-shm-too-small`.
`fix-16-vllm-oom` and `fix-17-torch-dlpack` are driven by the error text you
pass with `--symptom` (or `--symptom-file`) and read nothing from the environment or the ROCm
install. `fix-18-comgr-conflict` and
pass with `--symptom` (or `--symptom-file`) and read nothing from the
environment or the ROCm install. `fix-18-comgr-conflict` and
`fix-19-shm-too-small` apply when you run `rocm diagnose` inside the distro. A
`--distro` run skips both (see
[Diagnose a distro from Windows](#diagnose-a-distro-from-windows) later in this
Expand Down
Loading