From 275c3a64db55ce6f77a8a46ba1201e476cc1bcad Mon Sep 17 00:00:00 2001 From: phix33 <122955334+phix33@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:09:36 +1100 Subject: [PATCH] [AUTOMATED] feat(cli): list a function's warnings in its JSON record - Every `--json` function record from `decompile` and `decompile-all`, and from the browser front-end, now has a `warnings` array of `{kind,message,line,address}`. The array is always present and is `[]` for a function with no warnings and for one that failed. - The printer records an entry each time it writes one of the engine's own warning comments: a header warning, a body warning, an inline slug, or the note on a body it has no structure for. A comment whose text merely reads like a warning is never listed. That covers an `--assert comment`, a storage comment, and the original name a Rust or Go render keeps above the prototype. - `address` is the instruction the warning was recorded at, or the function's entry for a header warning. It is `null` only for `structuring-declined`. `line` is the line of `code` that holds the comment, and `message` is the warning text without its `WARNING: ` marker. - `kind` is assigned by matching the warning text. A fixed table covers decode failures, flow cut at the instruction budget, out-of-bounds and unmapped flow, unrecovered jump tables and declined structuring. Any other warning gets the slug `warnstyle inline` prints for it (without its ` xN` count) or a kuna producer tag. Text that matches none of these gets `other`. - The `--jobs` result wire and the result store carry the records, and the wire format moves to `KUNAJOBRES12`. Both `warnstyle` values give the same records except for `line`. --- decompiler/crates/kuna-cli/src/decompile.rs | 2 +- .../crates/kuna-cli/src/decompile_all.rs | 48 +++- .../src/decompile_all/result_store.rs | 7 +- decompiler/crates/kuna-cli/src/jobs.rs | 93 ++++++- decompiler/crates/kuna-cli/src/jobs/wire.rs | 32 ++- .../crates/kuna-cli/src/project_stream.rs | 1 + .../kuna-cli/tests/function_warnings_cli.rs | 259 ++++++++++++++++++ .../crates/kuna-cli/tests/integration.rs | 3 + decompiler/crates/kuna-console/src/project.rs | 19 +- .../src/p9_emit/kuna_functionwarnings.rs | 105 +++++++ .../p9_emit/kuna_functionwarnings/tests.rs | 98 +++++++ .../crates/kuna-decomp/src/p9_emit/mod.rs | 1 + .../crates/kuna-decomp/src/p9_emit/printc.rs | 71 +++-- decompiler/crates/kuna-wasm/src/inspect.rs | 1 + decompiler/crates/kuna-wasm/src/lib.rs | 13 + docs/cli.md | 38 ++- docs/spec/09-emission.md | 33 +++ 17 files changed, 790 insertions(+), 34 deletions(-) create mode 100644 decompiler/crates/kuna-cli/tests/function_warnings_cli.rs create mode 100644 decompiler/crates/kuna-decomp/src/p9_emit/kuna_functionwarnings.rs create mode 100644 decompiler/crates/kuna-decomp/src/p9_emit/kuna_functionwarnings/tests.rs diff --git a/decompiler/crates/kuna-cli/src/decompile.rs b/decompiler/crates/kuna-cli/src/decompile.rs index fb7c32d220..ce0430c354 100644 --- a/decompiler/crates/kuna-cli/src/decompile.rs +++ b/decompiler/crates/kuna-cli/src/decompile.rs @@ -1174,7 +1174,7 @@ fn usage() { (a `0x`-prefixed target implies it); an address inside another function is\n\ decompiled as asked, with a note naming that function. --json emits the\n\ decompile-all record for that one function\n\ - ({{binary,count,functions:[{{name,address,code,variables,..}}]}});\n\ + ({{binary,count,functions:[{{name,address,code,error,warnings,variables,..}}]}});\n\ without it, the C text alone. With --json, --omit KEY[,KEY].. leaves those\n\ record collections out (aliases, line_mappings, variables -- with\n\ stack_objects -- and types) and lists them in a top-level `omitted` array;\n\ diff --git a/decompiler/crates/kuna-cli/src/decompile_all.rs b/decompiler/crates/kuna-cli/src/decompile_all.rs index 1206c2ea31..5334c17e89 100644 --- a/decompiler/crates/kuna-cli/src/decompile_all.rs +++ b/decompiler/crates/kuna-cli/src/decompile_all.rs @@ -2450,6 +2450,7 @@ fn function_json( "unstructured_gotos".into(), Json::Number(f.unstructured_gotos().to_string()), ), + ("warnings".into(), Json::Array(f.warnings.iter().map(warning_json).collect())), ]); if !omit.line_mappings { record.push(( @@ -2501,6 +2502,15 @@ fn assertions_json(outcomes: &[kuna_console::assertions::Outcome]) -> Json { ) } +fn warning_json(warning: &kuna_decomp::kuna_functionwarnings::Warning) -> Json { + Json::Object(vec![ + ("kind".into(), Json::Str(warning.kind())), + ("message".into(), Json::Str(warning.message())), + ("line".into(), Json::Number(warning.line.to_string())), + ("address".into(), warning.address.map_or(Json::Null, |a| Json::Number(a.to_string()))), + ]) +} + fn line_mapping_json(mapping: &LineMapping) -> Json { Json::Object(vec![ ("line_number".into(), Json::Number(mapping.line_number.to_string())), @@ -2640,6 +2650,7 @@ mod provenance_json_tests { callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, } } @@ -2689,7 +2700,7 @@ mod provenance_json_tests { let record = doc["functions"][0].as_object().unwrap(); assert!(!record.contains_key("line_mappings") && !record.contains_key("types")); assert_eq!(record["variables"][0]["line_numbers"], serde_json::json!([3])); - for key in ["name", "address", "code", "error", "unstructured_gotos"] { + for key in ["name", "address", "code", "error", "unstructured_gotos", "warnings"] { assert!(record.contains_key(key), "{key} must survive --omit"); } assert_eq!(doc["language"], "c-language"); @@ -2703,6 +2714,33 @@ mod provenance_json_tests { assert!(!doc["functions"][0].as_object().unwrap().contains_key("variables")); } + #[test] + fn a_record_lists_its_warnings_and_a_failed_one_none() { + use kuna_decomp::kuna_functionwarnings::Warning; + let warned = FuncResult { + warnings: vec![ + Warning { address: Some(0x401000), text: "WARNING: Subroutine does not return".into(), line: 1 }, + Warning { address: Some(0x401010), text: "WARNING: Function flows out of bounds".into(), line: 4 }, + Warning { address: None, text: "WARNING: structured blocks unavailable".into(), line: 5 }, + ], + ..function() + }; + let failed = FuncResult { code: None, error: Some("boom".into()), ..function() }; + let text = dumps_indent2(&result_json( + "fixture", &[warned, failed], "c-language", None, None, &[], &Default::default(), Omit::default(), + )); + let doc: serde_json::Value = serde_json::from_str(&text).unwrap(); + assert_eq!( + doc["functions"][0]["warnings"], + serde_json::json!([ + {"kind": "no-return", "message": "Subroutine does not return", "line": 1, "address": 0x401000}, + {"kind": "out-of-bounds", "message": "Function flows out of bounds", "line": 4, "address": 0x401010}, + {"kind": "structuring-declined", "message": "structured blocks unavailable", "line": 5, "address": null}, + ]) + ); + assert_eq!(doc["functions"][1]["warnings"], serde_json::json!([])); + } + #[test] fn omitted_aliases_leave_the_record_and_keep_its_identity() { let aliased = FuncResult { aliases: vec!["sub_401000".into()], ..function() }; @@ -3223,8 +3261,12 @@ fn usage_decompile_all() { \x20 [--raw-image --target T --base VMA (--entry|--addr VMA)..]\n\ \n\ Decompile every CODE-backed function in one in-process load (load-once,\n\ - decompile-many). --json emits {{binary,count,functions:[{{name,address,code,variables,..}}]}};\n\ - without it, concatenated C with `// Function:` headers.\n\ + decompile-many). --json emits {{binary,count,functions:[{{name,address,code,error,warnings,variables,..}}]}};\n\ + without it, concatenated C with `// Function:` headers. A record's\n\ + `warnings` lists the engine warnings its code carries as comments, as\n\ + {{kind,message,line,address}}, each at the instruction it was recorded\n\ + at (a header warning at the entry); `error` is set only for a failed\n\ + function.\n\ --omit KEY[,KEY].. (with --json) leaves those record collections out of\n\ every record -- aliases, line_mappings, variables (with stack_objects),\n\ types -- and lists them in a top-level `omitted` array, so an omitted\n\ diff --git a/decompiler/crates/kuna-cli/src/decompile_all/result_store.rs b/decompiler/crates/kuna-cli/src/decompile_all/result_store.rs index e552e6c3d6..72c20481b9 100644 --- a/decompiler/crates/kuna-cli/src/decompile_all/result_store.rs +++ b/decompiler/crates/kuna-cli/src/decompile_all/result_store.rs @@ -153,12 +153,16 @@ mod tests { callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, } } fn check(mut store: ResultStore) { - store.put(2, result("c", Some("int c(void)\n{\n}"))); + let warning = kuna_decomp::kuna_functionwarnings::Warning { + address: Some(0x1004), text: "WARNING: Bad instruction".into(), line: 2, + }; + store.put(2, FuncResult { warnings: vec![warning.clone()], ..result("c", Some("int c(void)\n{\n}")) }); store.put(0, result("a", None)); store.put(0, result("a2", Some("void a(void)"))); let mut tokens = result("d", Some("void d(void)")); @@ -171,6 +175,7 @@ mod tests { assert_eq!(all.iter().map(|r| r.name.as_str()).collect::>(), ["a2", "c", "d"]); assert_eq!(all[1].code.as_deref(), Some("int c(void)\n{\n}")); assert_eq!(all[1].aliases, ["alias"]); + assert_eq!(all[1].warnings, [warning]); assert!(all[2].detail.is_some()); } diff --git a/decompiler/crates/kuna-cli/src/jobs.rs b/decompiler/crates/kuna-cli/src/jobs.rs index 733d3bf6e4..c89a5faca3 100644 --- a/decompiler/crates/kuna-cli/src/jobs.rs +++ b/decompiler/crates/kuna-cli/src/jobs.rs @@ -1646,6 +1646,7 @@ fn lost_result(t: &TargetSpec, reason: &str) -> FuncResult { callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, } } @@ -2162,6 +2163,7 @@ mod tests { callee_hints: vec![0x401200, 0x401340, 0xffff_ffff_ffff_fff0], synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, } } @@ -2182,6 +2184,7 @@ mod tests { && a.callee_hints == b.callee_hints && a.field_calls == b.field_calls && a.pointerargs == b.pointerargs + && a.warnings == b.warnings && a.synth == b.synth && a.line_mappings == b.line_mappings && a.globals == b.globals @@ -2240,6 +2243,14 @@ mod tests { expression: "&v1".into(), }], }); + let warning = |address, text: &str, line| { + kuna_decomp::kuna_functionwarnings::Warning { address, text: text.into(), line } + }; + a.warnings = vec![ + warning(Some(0x401000), "WARNING: Subroutine does not return", 2), + warning(Some(0x401234), "WARNING: Bad instruction", 7), + warning(None, "WARNING: structured blocks unavailable", 5), + ]; let b = FuncResult { name: "sub_1234".into(), address: 0x1234, @@ -2262,6 +2273,7 @@ mod tests { callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, }; { @@ -2292,7 +2304,7 @@ mod tests { } #[test] - fn result_encoding_matches_the_version_eleven_wire_layout() { + fn result_encoding_matches_the_version_twelve_wire_layout() { let dir = ScratchDir::create().unwrap(); let path = dir.path().join("wire.bin").to_string_lossy().into_owned(); let result = FuncResult { @@ -2317,10 +2329,11 @@ mod tests { callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, }; let expected = [ - b"KUNAJOBRES11\x01\x51\0\0\0".as_slice(), + b"KUNAJOBRES12\x01\x55\0\0\0".as_slice(), b"\x10\0\0\0\0\0\0\0\x20\0\0\0\0\0\0\0", b"\xff\xff\xff\xff\xff\xff\xff\xff", b"\x01\0\0\0f\0\x01\x01\0\0\0e\0\0", @@ -2334,6 +2347,7 @@ mod tests { b"\0\0\0\0", // field calls b"\0\0\0\0", // callee hints b"\0\0", // synth and pointer arguments + b"\0\0\0\0", // warnings b"\0\0\0\0", // call declarations b"\0\0\0\0", // callwide prototypes ] @@ -2365,6 +2379,80 @@ mod tests { assert!(decode_results(&std::fs::read(&path).unwrap()).unwrap().results.is_empty()); } + #[test] + fn a_malformed_warnings_block_does_not_cross_the_worker_boundary() { + use kuna_decomp::kuna_functionwarnings::Warning; + let at = Warning { + address: Some(0x8877_6655_4433_2211), + text: "WARNING: Bad instruction".into(), + line: 0x0a09_0807_0605_0403, + }; + let shell = Warning { + address: None, + text: "WARNING: blocks \u{e9}".into(), + line: 0x1c1b_1a19_1817_1615, + }; + let at_bytes = [ + b"\x01\x11\x22\x33\x44\x55\x66\x77\x88".as_slice(), + b"\x18\0\0\0WARNING: Bad instruction", + b"\x03\x04\x05\x06\x07\x08\x09\x0a", + ] + .concat(); + let shell_bytes = + [b"\0\x12\0\0\0WARNING: blocks \xc3\xa9".as_slice(), b"\x15\x16\x17\x18\x19\x1a\x1b\x1c"].concat(); + let pointerargs = kuna_decomp::kuna_pointerargs::Record { + entry: ("ram".into(), 0x401000), + parameters: vec![Some(kuna_decomp::kuna_pointerargs::Parameter { + storage: (("register".into(), 0x38), 8), + spelling: "unsigned char *".into(), + })], + calls: Vec::new(), + }; + for (before, warnings, records) in [ + (None, vec![at.clone(), shell.clone()], [at_bytes.as_slice(), &shell_bytes]), + (Some(pointerargs), vec![shell.clone(), at.clone()], [shell_bytes.as_slice(), &at_bytes]), + ] { + let mut record = sample_result(); + record.pointerargs = before; + record.warnings = warnings; + let body = encode_result(&record); + let after = record.call_declarations[0].as_bytes(); + let end = body.windows(after.len()).position(|w| w == after).unwrap() - 8; + let block = [b"\x02\0\0\0".as_slice(), records[0], records[1]].concat(); + let start = end - block.len(); + assert_eq!(body[start..end], block[..]); + assert_eq!(body[end..end + 8], *b"\x01\0\0\0\x1e\0\0\0"); + let decoded = decode_result(&body).unwrap(); + assert!(same(&decoded, &record)); + assert_eq!(decoded.pointerargs, record.pointerargs); + assert_eq!(decoded.call_declarations, record.call_declarations); + + let patched = |offset: usize, bytes: &[u8]| { + let mut bad = body.clone(); + bad[offset..offset + bytes.len()].copy_from_slice(bytes); + decode_result(&bad) + }; + for count in [0u32, 1, 3, u32::MAX] { + assert!(patched(start, &count.to_le_bytes()).is_none(), "count {count}"); + } + let mut tag = start + 4; + for bytes in records { + for invalid in [2u8, 0xff] { + assert!(patched(tag, &[invalid]).is_none(), "address tag {invalid}"); + } + let length = tag + if bytes[0] == 1 { 9 } else { 1 }; + for oversized in [(body.len() - length - 3) as u32, u32::MAX] { + assert!(patched(length, &oversized.to_le_bytes()).is_none(), "text length {oversized}"); + } + assert!(patched(bytes.len() + tag - 9, &[0xff]).is_none(), "text that is not UTF-8"); + tag += bytes.len(); + } + for cut in start..end { + assert!(decode_result(&body[..cut]).is_none(), "cut at {cut}"); + } + } + } + /// The dynamic source is the only thing `--stream` changes about the pool: /// every chunk it hands out is served once, and a drained source ends the /// thread's loop. @@ -2793,6 +2881,7 @@ mod tests { callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, }; let results = vec![ diff --git a/decompiler/crates/kuna-cli/src/jobs/wire.rs b/decompiler/crates/kuna-cli/src/jobs/wire.rs index 766a950f3e..8f40b005ac 100644 --- a/decompiler/crates/kuna-cli/src/jobs/wire.rs +++ b/decompiler/crates/kuna-cli/src/jobs/wire.rs @@ -14,7 +14,7 @@ use kuna_decomp::kuna_structsynth::shard::FunctionRecord; use super::TargetSpec; const SPEC_MAGIC: &[u8; 12] = b"KUNAJOBSPEC3"; -pub(super) const RESULT_MAGIC: &[u8; 12] = b"KUNAJOBRES11"; +pub(super) const RESULT_MAGIC: &[u8; 12] = b"KUNAJOBRES12"; /// Result-stream frame kinds. The envelope is what lets a truncated tail be /// dropped rather than guessed. @@ -389,6 +389,7 @@ pub(crate) fn encode_result(r: &FuncResult) -> Vec { None => body.push(0), } put_pointerargs(&mut body, r.pointerargs.as_ref()); + put_warnings(&mut body, &r.warnings); put_u32(&mut body, r.call_declarations.len() as u32); for declaration in &r.call_declarations { put_str(&mut body, declaration); } put_u32(&mut body, r.callwide_prototypes.len() as u32); @@ -574,6 +575,7 @@ pub(crate) fn decode_result(body: &[u8]) -> Option { _ => return None, }; let pointerargs = read_pointerargs(&mut r)?; + let warnings = read_warnings(&mut r)?; let count = r.u32()? as usize; let mut call_declarations = r.sized(count); for _ in 0..count { call_declarations.push(r.string()?); } @@ -618,6 +620,7 @@ pub(crate) fn decode_result(body: &[u8]) -> Option { callee_hints, synth, pointerargs, + warnings, detail: None, }) } @@ -659,6 +662,33 @@ fn put_pointerargs(out: &mut Vec, record: Option<&kuna_decomp::kuna_pointera } } +fn put_warnings(out: &mut Vec, warnings: &[kuna_decomp::kuna_functionwarnings::Warning]) { + put_u32(out, warnings.len() as u32); + for warning in warnings { + match warning.address { + Some(address) => { + out.push(1); + put_u64(out, address); + } + None => out.push(0), + } + put_str(out, &warning.text); + put_u64(out, warning.line as u64); + } +} + +fn read_warnings(r: &mut Reader<'_>) -> Option> { + let n = r.u32()? as usize; + let mut warnings = r.sized(n); + for _ in 0..n { + let address = match r.u8()? { 0 => None, 1 => Some(r.u64()?), _ => return None }; + let text = r.string()?; + let line = r.u64()?.try_into().ok()?; + warnings.push(kuna_decomp::kuna_functionwarnings::Warning { address, text, line }); + } + Some(warnings) +} + fn read_entry(r: &mut Reader<'_>) -> Option { Some((r.string()?, r.u64()?)) } diff --git a/decompiler/crates/kuna-cli/src/project_stream.rs b/decompiler/crates/kuna-cli/src/project_stream.rs index 2b3012fcb5..a7e8a91b88 100644 --- a/decompiler/crates/kuna-cli/src/project_stream.rs +++ b/decompiler/crates/kuna-cli/src/project_stream.rs @@ -1358,6 +1358,7 @@ mod tests { callee_hints: hints, synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, } } diff --git a/decompiler/crates/kuna-cli/tests/function_warnings_cli.rs b/decompiler/crates/kuna-cli/tests/function_warnings_cli.rs new file mode 100644 index 0000000000..d342a554cd --- /dev/null +++ b/decompiler/crates/kuna-cli/tests/function_warnings_cli.rs @@ -0,0 +1,259 @@ +//! A `--json` function record lists the analysis warnings the engine wrote +//! into its `code` in `warnings`, each at the address the engine recorded it +//! at, while `error` stays `null` and the exit status `0` for a body that +//! decompiled, and the comments stay in `code`. + +use crate::common; + +use serde_json::{json, Value}; + +const RAW: [&str; 6] = ["--raw-image", "--target", "AARCH64:LE:64:v8A", "--base", "0x10000", "--json"]; + +fn document(args: &[&str]) -> Value { + let (stdout, stderr, code) = common::run_kuna(args); + assert_eq!(code, 0, "{args:?}: {stdout}\n{stderr}"); + serde_json::from_str(&stdout).unwrap_or_else(|e| panic!("{e}: {stdout}")) +} + +/// The record's warnings, each checked to sit on a line of `code` holding its +/// comment, which spells its message or, abbreviated, its kind. +fn placed(record: &Value) -> Vec { + let code = record["code"].as_str().unwrap_or_default(); + let lines: Vec<&str> = code.lines().collect(); + let warnings = record["warnings"].as_array().unwrap().clone(); + for warning in &warnings { + let line = lines[warning["line"].as_u64().unwrap() as usize - 1]; + let message = warning["message"].as_str().unwrap().lines().next().unwrap(); + assert!(line.contains("//") || line.contains("/*"), "{warning} on {line:?}"); + assert!(line.contains(message) || line.contains(warning["kind"].as_str().unwrap()), "{warning} on {line:?}"); + } + warnings +} + +/// `(kind, message, address)` of every warning, in order: what both warning +/// styles and every language agree on. +fn records(record: &Value) -> Vec<(String, String, Value)> { + placed(record) + .iter() + .map(|w| (w["kind"].as_str().unwrap().into(), w["message"].as_str().unwrap().into(), w["address"].clone())) + .collect() +} + +/// The mnemonic and operands of the instruction at `address`. +fn instruction(image: &str, address: u64) -> (String, String) { + let at = format!("0x{address:x}"); + let doc = document(&["disassemble", image, &at, "--addr", "--count", "1", "--json"]); + let row = &doc["instructions"][0]; + assert_eq!(row["address"], address, "{doc}"); + (row["mnemonic"].as_str().unwrap().into(), row["operands"].as_str().unwrap().into()) +} + +/// A raw AArch64 image at 0x10000: `ret`, `nop`, a word that decodes to +/// nothing (0xffffffff at 0x10008), then `udf #0` (0x1000c), whose exception +/// vector is an indirect call. +#[test] +fn a_bad_instruction_is_a_warning_of_a_record_that_did_not_fail() { + let path = common::scratch_file("function-warnings", "bin"); + let bytes = [0xc0, 0x03, 0x5f, 0xd6, 0x1f, 0x20, 0x03, 0xd5, 0xff, 0xff, 0xff, 0xff, 0, 0, 0, 0]; + std::fs::write(&path, bytes).unwrap(); + let image = path.to_str().unwrap(); + let bad = json!([ + {"kind": "bad-instruction", "message": "Control flow encountered bad instruction data", + "line": 1, "address": 0x10004}, + {"kind": "bad-instruction", "message": "Bad instruction - Truncating control flow here", + "line": 3, "address": 0x10008}, + ]); + + let one = document(&[&["decompile", image, "0x10004"], &RAW[..]].concat()); + let record = &one["functions"][0]; + assert_eq!(one["error"], Value::Null); + assert_eq!(record["error"], Value::Null); + assert!( + record["code"].as_str().unwrap().contains("halt_baddata(); // warn: Bad instruction - Truncating control flow here"), + "{record}" + ); + assert_eq!(placed(record), bad.as_array().unwrap().clone()); + + let mut all = vec!["decompile-all", image]; + all.extend(RAW); + all.extend(["--entry", "0x10000", "--entry", "0x10004", "--entry", "0x1000c"]); + let doc = document(&all); + let functions = doc["functions"].as_array().unwrap(); + assert_eq!(functions.len(), 3, "{doc}"); + assert_eq!(functions[0]["warnings"], json!([]), "the clean `ret`: {}", functions[0]); + assert_eq!(functions[1]["warnings"], bad); + assert_eq!( + functions[2]["warnings"], + json!([{"kind": "jump-as-call", "message": "Treating indirect jump as call", "line": 3, "address": 0x1000c}]) + ); + + let serial = document(&[&all[..], &["--option", "protoorder", "off"]].concat()); + assert_eq!(serial["functions"], doc["functions"], "the callee-first result store keeps them"); + + all.extend(["--option", "warnstyle", "banner"]); + let banner = document(&all); + for (inline, banner) in functions.iter().zip(banner["functions"].as_array().unwrap()) { + assert_eq!(records(inline), records(banner), "{banner}"); + } + assert!(banner["functions"][1]["code"].as_str().unwrap().starts_with("/* WARNING: Control flow")); + + for language in ["go", "rust"] { + for entry in ["0x10004", "0x1000c"] { + let doc = document(&[&["decompile", image, entry, "--language", language], &RAW[..]].concat()); + let c = document(&[&["decompile", image, entry], &RAW[..]].concat()); + assert_eq!(records(&doc["functions"][0]), records(&c["functions"][0]), "{language} {entry}: {doc}"); + } + } + std::fs::remove_file(&path).unwrap(); +} + +/// `nop; nop; ret` at 0x10000, cut after its first instruction. +#[test] +fn a_flow_cut_by_the_budget_or_a_declared_extent_is_a_warning() { + let path = common::scratch_file("function-warnings-nops", "bin"); + std::fs::write(&path, [0x1f, 0x20, 0x03, 0xd5, 0x1f, 0x20, 0x03, 0xd5, 0xc0, 0x03, 0x5f, 0xd6]).unwrap(); + let image = path.to_str().unwrap(); + let cases: [(&[&str], [(&str, &str); 2]); 2] = [ + ( + &["--option", "maxinstruction", "1"], + [("instruction-limit", "Exceeded the 1 instruction budget: "), ("instruction-limit", "Too many instructions -- ")], + ), + ( + &["--define-function", "0x10000-0x10004"], + [("out-of-bounds", "Function flows out of bounds"), ("out-of-bounds", "Function flow out of bounds: ")], + ), + ]; + for (cut, expected) in cases { + let doc = document(&[&["decompile", image, "0x10000"], &RAW[..], cut].concat()); + let record = &doc["functions"][0]; + assert_eq!((&doc["error"], &record["error"]), (&Value::Null, &Value::Null), "{record}"); + let warnings = placed(record); + assert_eq!(warnings.len(), 2, "{record}"); + for ((warning, (kind, text)), (line, address)) in + warnings.iter().zip(expected).zip([(1, 0x10000), (3, 0x10004)]) + { + assert_eq!(warning["kind"], kind, "{record}"); + assert!(warning["message"].as_str().unwrap().starts_with(text), "{record}"); + assert_eq!((&warning["line"], &warning["address"]), (&json!(line), &json!(address)), "{record}"); + } + } + std::fs::remove_file(&path).unwrap(); +} + +/// Each function's body falls through into the next function at its last +/// instruction, which is where the drained `funcboundflow` warning is recorded. +#[test] +fn an_empty_body_s_drained_warning_is_a_body_warning_in_every_language() { + let cases = [ + ("function_boundary_return_x86_64", "ordinary_first", 0x401016, vec![]), + ("i386_pie_nl", "register_tm_clones", 0x18f0, vec![("injected", 0x18d0)]), + ]; + for (fixture, name, last, header) in &cases { + let image = common::fixture(fixture); + let listing = document(&["disassemble", &image, name, "--json"]); + assert_eq!(listing["instructions"].as_array().unwrap().last().unwrap()["address"], *last, "{listing}"); + let mut expected: Vec<(String, Value)> = vec![("funcboundflow".into(), json!(last))]; + expected.extend(header.iter().map(|(kind, address)| (kind.to_string(), json!(address)))); + expected.sort_by_key(|(kind, _)| kind.clone()); + for language in ["c", "go", "rust"] { + for style in ["inline", "banner"] { + let args = ["decompile", &image, name, "--json", "--language", language]; + let doc = document(&[&args[..], &["--option", "warnstyle", style]].concat()); + let record = &doc["functions"][0]; + let mut found: Vec<(String, Value)> = + records(record).into_iter().map(|(kind, _, address)| (kind, address)).collect(); + found.sort_by_key(|(kind, _)| kind.clone()); + assert_eq!(found, expected, "{language} {style}: {record}"); + } + } + } + + let go = |fixture: &str, name: &str| { + document(&["decompile", &common::fixture(fixture), name, "--json", "--language", "go"])["functions"][0].clone() + }; + let alone = go("function_boundary_return_x86_64", "ordinary_first"); + assert!(alone["code"].as_str().unwrap().starts_with("func ordinary_first() { // warn: funcboundflow: "), "{alone}"); + let both = go("i386_pie_nl", "register_tm_clones"); + assert!( + both["code"].as_str().unwrap().starts_with("func register_tm_clones() { // injected // warn: funcboundflow: "), + "{both}" + ); + let at: Vec<(Value, Value)> = placed(&both).iter().map(|w| (w["line"].clone(), w["address"].clone())).collect(); + assert_eq!(at, [(json!(1), json!(0x18d0)), (json!(1), json!(0x18f0))], "{both}"); +} + +/// `audit_undecodable` opens with `JZ 0x401033`, a branch into the middle of +/// the next instruction, whose bytes decode to nothing. +#[test] +fn a_storage_or_asserted_comment_beside_a_bad_instruction_is_not_a_warning() { + let image = common::fixture("followoverlap_x86_64"); + assert_eq!(instruction(&image, 0x401030), ("JZ".into(), "0x401033".into())); + let bad: Vec<(String, String, Value)> = [ + ("Control flow encountered bad instruction data", 0x401030), + ("Bad instruction - Truncating control flow here", 0x401033), + ] + .map(|(message, address)| ("bad-instruction".into(), message.into(), json!(address))) + .into(); + for style in ["inline", "banner"] { + let doc = document(&[ + "decompile", &image, "audit_undecodable", "--json", "--option", "warnstyle", style, + "--assert", "comment 0x401032 WARNING: hello there", + ]); + assert_eq!(doc["assertions"][0]["status"], "applied", "{doc}"); + let record = &doc["functions"][0]; + let code = record["code"].as_str().unwrap(); + assert!(code.contains("bool v1; // zf") && code.contains("/* WARNING: hello there */"), "{style}: {record}"); + assert_eq!(records(record), bad, "{style}: {record}"); + } +} + +#[test] +fn a_function_s_original_name_comment_is_not_a_warning() { + let image = common::fixture("adrnext_x86_64"); + for name in ["no-return", "inlined: lea_next", "warn: Bad instruction - Truncating control flow here"] { + let define = format!("0x201120={name}"); + for language in ["rust", "go", "c"] { + let args = ["decompile", &image, "0x201120", "--addr", "--define-function", &define, "--json"]; + let doc = document(&[&args[..], &["--language", language]].concat()); + let record = &doc["functions"][0]; + let code = record["code"].as_str().unwrap(); + assert_eq!(code.starts_with(&format!("// {name}\n")), language != "c", "{language}: {code}"); + assert_eq!(record["warnings"], json!([]), "{language}: {record}"); + } + } +} + +#[test] +fn both_warning_styles_report_the_same_warnings() { + let pe = common::fixture("explicit_branch_assertion_pe_i386.exe"); + let mut args = vec!["decompile-all", &pe, "--json", "--omit", "line_mappings,variables,types"]; + args.extend(["--addr", "0x418764", "--addr", "0x406de0", "--addr", "0x44a0c6"]); + let inline = document(&args); + let workers = document(&[&args[..], &["--jobs", "2"]].concat()); + assert_eq!(workers["functions"], inline["functions"], "a --jobs worker's records carry them"); + args.extend(["--option", "warnstyle", "banner"]); + let banner = document(&args); + let mut seen = Vec::new(); + for (inline, banner) in inline["functions"].as_array().unwrap().iter().zip(banner["functions"].as_array().unwrap()) { + assert_eq!(records(inline), records(banner), "{}", inline["name"]); + seen.extend(records(inline).into_iter().map(|(kind, _, address)| (kind, address))); + } + for kind in ["bad-instruction", "int3-pad", "calltrampoline", "branch-flip", "funcboundflow"] { + assert!(seen.iter().any(|(k, _)| k == kind), "{kind} missing from {seen:?}"); + } + assert!(seen.contains(&("calltrampoline".into(), json!(0x406df0))), "{seen:?}"); + assert_eq!(instruction(&pe, 0x406df0), ("CALL".into(), "0x44a677".into())); + assert!(seen.contains(&("branch-flip".into(), json!(0x406e9f))), "{seen:?}"); + assert_eq!(instruction(&pe, 0x406e9f).0, "JZ"); + let joined = placed(&inline["functions"][1]); + let line50: Vec<&Value> = joined.iter().filter(|w| w["line"] == 50).map(|w| &w["address"]).collect(); + assert_eq!(line50, [&json!(0x406eba), &json!(0x406ed9)], "{joined:?}"); + + let stripped = common::fixture("pe_imports_stripped.exe"); + let doc = document(&["decompile", &stripped, "0x140001b30", "--json"]); + let message = "returndup: duplicated 5 shared bare-epilogue return(s) for early-return recovery in sub_140001b30"; + assert_eq!( + placed(&doc["functions"][0])[0], + json!({"kind": "return-dupe", "message": message, "line": 1, "address": 0x140001b30u64}) + ); +} diff --git a/decompiler/crates/kuna-cli/tests/integration.rs b/decompiler/crates/kuna-cli/tests/integration.rs index 52c08050d6..70d7db957b 100644 --- a/decompiler/crates/kuna-cli/tests/integration.rs +++ b/decompiler/crates/kuna-cli/tests/integration.rs @@ -190,6 +190,9 @@ mod decompile_graph_cli; #[path = "decompile_json_cli.rs"] mod decompile_json_cli; +#[path = "function_warnings_cli.rs"] +mod function_warnings_cli; + #[path = "decompile_project_cli.rs"] mod decompile_project_cli; diff --git a/decompiler/crates/kuna-console/src/project.rs b/decompiler/crates/kuna-console/src/project.rs index 77ecd519fa..57c7692336 100644 --- a/decompiler/crates/kuna-console/src/project.rs +++ b/decompiler/crates/kuna-console/src/project.rs @@ -131,6 +131,10 @@ pub struct FuncResult { pub synth: Option, /// Internal facts from this render, reconciled only by buffered drivers. pub pointerargs: Option, + /// The analysis warnings `code` carries as comments, each at the address + /// the engine recorded it at (in the target's address units). Empty on + /// every error record. + pub warnings: Vec, /// The token source map, captured only when the caller asked for it /// ([`DecompileOptions::want_tokens`]). pub detail: Option>, @@ -600,6 +604,7 @@ pub fn decompile_pulled( callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, }); continue; @@ -639,6 +644,7 @@ pub fn decompile_pulled( callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, }); continue; @@ -666,6 +672,7 @@ pub fn decompile_pulled( callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, }); continue; @@ -887,6 +894,10 @@ pub fn decompile_pulled( (print_c(prog.arch_mut(), &fd), Default::default(), Vec::new()) }; let pointerargs = prog.arch_mut().print_mut().take_pointer_arguments(&untrimmed); + let mut warnings = prog.arch_mut().print_mut().take_warnings(&untrimmed); + for address in warnings.iter_mut().filter_map(|w| w.address.as_mut()) { + *address = prog.output_code_offset(*address); + } if let Some(err) = budget.error() { return Err(err.explain().to_string()); } @@ -947,7 +958,7 @@ pub fn decompile_pulled( if budget.spent_in("extracting variables") { return Err(budget.error().map(|e| e.explain().to_string()).unwrap_or_default()); } - Ok::<_, String>((code, variables, types, (globals, field_calls, call_declarations, callwide_prototypes), proto, line_mappings, callee_hints, detail, pointerargs, stack_objects)) + Ok::<_, String>((code, variables, types, (globals, field_calls, call_declarations, callwide_prototypes), proto, line_mappings, callee_hints, detail, (pointerargs, warnings), stack_objects)) })).unwrap_or_else(|_| { Err(budget.error().map_or_else( || "panic while rendering C / extracting variables".to_string(), @@ -957,7 +968,7 @@ pub fn decompile_pulled( drop(budget); fd.set_display_name(&original_display); match rendered { - Ok((code, variables, types, (globals, field_calls, call_declarations, callwide_prototypes), proto, line_mappings, callee_hints, detail, pointerargs, stack_objects)) => { + Ok((code, variables, types, (globals, field_calls, call_declarations, callwide_prototypes), proto, line_mappings, callee_hints, detail, (pointerargs, warnings), stack_objects)) => { crate::assertions::verify_printed(prog, &fd, &code, &replayed); sink(FuncResult { name, @@ -981,6 +992,7 @@ pub fn decompile_pulled( callee_hints, synth: None, pointerargs, + warnings, detail, }) } @@ -1006,6 +1018,7 @@ pub fn decompile_pulled( callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, }), } @@ -1032,6 +1045,7 @@ pub fn decompile_pulled( callee_hints: Vec::new(), synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, }), } @@ -2299,6 +2313,7 @@ mod tests { callee_hints: vec![], synth: None, pointerargs: None, + warnings: Vec::new(), detail: None, } } diff --git a/decompiler/crates/kuna-decomp/src/p9_emit/kuna_functionwarnings.rs b/decompiler/crates/kuna-decomp/src/p9_emit/kuna_functionwarnings.rs new file mode 100644 index 0000000000..c48829283e --- /dev/null +++ b/decompiler/crates/kuna-decomp/src/p9_emit/kuna_functionwarnings.rs @@ -0,0 +1,105 @@ +//! The analysis warnings a render writes, each as the engine recorded it. +//! +//! The printer records a [`Warning`] when it writes a `Funcdata::warning` or +//! `warning_header` comment (`emit_comment_group`, `emit_comment_func_header`, +//! `flush_eol_warnings`) and when it writes its own no-structure shell, so the +//! record carries the address the warning was indexed at and the line of the +//! render holding its comment. A comment of any other type (a user comment, a +//! storage or name comment) is never recorded, whatever it spells. Taken with +//! [`PrintC::take_warnings`](crate::printc::PrintC::take_warnings). + +use crate::kuna_decodehalt::{ + BAD_INSTRUCTION_HEADER, BAD_INSTRUCTION_WARNING, UNIMPLEMENTED_HEADER, + UNIMPLEMENTED_IGNORED_HEADER, UNIMPLEMENTED_WARNING, +}; +use crate::printc::warning_slug; + +/// Engine warning stems `warning_slug` keeps unabbreviated, with their kinds. +pub const STEMS: [(&str, &str); 18] = [ + (BAD_INSTRUCTION_WARNING, "bad-instruction"), + (BAD_INSTRUCTION_HEADER, "bad-instruction"), + (UNIMPLEMENTED_WARNING, "unimplemented-instruction"), + (UNIMPLEMENTED_HEADER, "unimplemented-instruction"), + (UNIMPLEMENTED_IGNORED_HEADER, "unimplemented-instruction"), + ("Too many instructions -- truncating flow here", "instruction-limit"), + ("Exceeded the ", "instruction-limit"), + ("Function flow out of bounds", "out-of-bounds"), + ("Function flows out of bounds", "out-of-bounds"), + ("Function flow reaches unmapped memory", "unmapped-flow"), + ("Function flows into unmapped memory", "unmapped-flow"), + ("Could not recover jumptable", "jumptable"), + ("Switch model does not reproduce", "jumptable"), + ("Ignoring partial resolution of indirect", "jumptable"), + ("Second-stage recovery error", "jumptable"), + ("Sanity check requires truncation of jumptable", "jumptable"), + ("structured blocks unavailable", "structuring-declined"), + ("decompilation failed", "decompilation-failed"), +]; + +/// One warning a render wrote: the byte address it was indexed at (the entry +/// for a header warning; `None` only for the printer's own shell), its stored +/// text and the 1-based line holding it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Warning { + pub address: Option, + pub text: String, + pub line: usize, +} + +impl Warning { + pub(crate) fn new(address: Option, text: &str) -> Self { + Self { address, text: text.to_string(), line: 0 } + } + + /// The text less its `WARNING: ` marker; a jump-table recovery warning keeps + /// `(jumptable): `. + pub fn message(&self) -> String { + match self.text.strip_prefix("WARNING (jumptable): ") { + Some(body) => format!("(jumptable): {body}"), + None => self.text.strip_prefix("WARNING: ").unwrap_or(&self.text).to_string(), + } + } + + /// A stable code: the kind of an unabbreviated engine stem, else the slug + /// `warning_slug` gives the text (less its count), else the producer tag + /// of a kuna warning, else `other`. + pub fn kind(&self) -> String { + let body = self.text.strip_prefix("WARNING (jumptable): "); + let body = body.or_else(|| self.text.strip_prefix("WARNING: ")).unwrap_or(&self.text); + if let Some((_, kind)) = STEMS.iter().find(|(stem, _)| body.starts_with(stem)) { + return kind.to_string(); + } + let slug = warning_slug(&self.text); + let slug = slug.strip_prefix("jt: ").unwrap_or(&slug); + if slug.starts_with("inlined: ") { + return "inlined".to_string(); + } + if !slug.starts_with("warn: ") { + return match slug.rsplit_once(" x") { + Some((base, n)) if !n.is_empty() && n.bytes().all(|b| b.is_ascii_digit()) => base, + _ => slug, + } + .to_string(); + } + match body.split_once(": ") { + Some((tag, _)) + if tag.starts_with(|c: char| c.is_ascii_lowercase()) + && tag.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit()) => + { + tag.to_string() + } + _ => "other".to_string(), + } + } +} + +/// Rebase lines counted in `untrimmed` onto it with its leading newlines removed. +pub(crate) fn trim_lines(warnings: &mut [Warning], untrimmed: &str) { + let skip = untrimmed.len() - untrimmed.trim_start_matches('\n').len(); + for warning in warnings { + warning.line = warning.line.saturating_sub(skip); + } +} + +#[cfg(test)] +mod tests; diff --git a/decompiler/crates/kuna-decomp/src/p9_emit/kuna_functionwarnings/tests.rs b/decompiler/crates/kuna-decomp/src/p9_emit/kuna_functionwarnings/tests.rs new file mode 100644 index 0000000000..f7aae1b2b3 --- /dev/null +++ b/decompiler/crates/kuna-decomp/src/p9_emit/kuna_functionwarnings/tests.rs @@ -0,0 +1,98 @@ +use super::{trim_lines, Warning, STEMS}; +use crate::printc::warning_slug; + +fn warning(text: &str) -> Warning { + Warning::new(Some(0x1000), text) +} + +/// The slug `warning_slug` gives `text`, less its `jt: ` prefix, an inlined +/// name and an ` xN` count. +fn slug_base(text: &str) -> String { + let slug = warning_slug(text); + let slug = slug.strip_prefix("jt: ").unwrap_or(&slug).to_string(); + if slug.starts_with("inlined: ") { + return "inlined".into(); + } + match slug.rsplit_once(" x") { + Some((base, n)) if n.bytes().all(|b| b.is_ascii_digit()) => base.into(), + _ => slug, + } +} + +#[test] +fn an_abbreviated_warning_s_kind_is_its_slug() { + for (text, kind) in [ + ("Subroutine does not return", "no-return"), + ("Does not return", "no-return"), + ("Treating indirect jump as call", "jump-as-call"), + ("Treating indirect jump as return", "jump-as-return"), + ("Could not inline here", "inline-failed"), + ("No fallthrough prevents inlining here", "inline-failed"), + ("Return address prevents inlining here", "inline-failed"), + ("Read-only address 0x2000 written", "writes-rodata"), + ("branchflip: negated the guard", "branch-flip"), + ("tailcalljump: jump to f is a tail call", "tail-call"), + ("taildup: duplicated 2 tails", "return-dupe"), + ("crossjumprevert: split 3 shared tails", "crossjump-dupe"), + ("int3pad: 11 bytes of int3 padding", "int3-pad"), + ("outline: 4 outlined bodies", "outlined"), + ("returndup: duplicated 5 shared bare-epilogue return(s)", "return-dupe"), + ("earlyreturn: hoisted 3 returns", "early-return"), + ("switchreturn: 2 cases return", "switch-return"), + ("dedupitetail: merged 2 tails", "ite-dedupe"), + ("iteregion: 2 ternaries", "ternary"), + ("ifelseflatten: 6 else blocks", "else-flattened"), + ("Inlined function: g x2", "inlined"), + ("Function: f replaced with injection: g", "injected"), + ("Unable to use symbol s: size mismatch", "symbol-size-mismatch"), + ] { + for text in [format!("WARNING: {text}"), format!("WARNING (jumptable): {text}")] { + assert!(!warning_slug(&text).contains("warn: "), "{text} is abbreviated"); + assert_eq!(slug_base(&text), kind, "{text}"); + assert_eq!(warning(&text).kind(), kind, "{text}"); + } + } +} + +#[test] +fn a_stem_is_one_the_slugs_leave_whole() { + for (stem, _) in STEMS { + for text in [format!("WARNING: {stem}"), format!("WARNING (jumptable): {stem}")] { + assert!(warning_slug(&text).contains("warn: "), "{stem} is abbreviated; its kind is its slug"); + } + } + for (text, kind) in [ + ("WARNING: Bad instruction - Truncating control flow here", "bad-instruction"), + ("WARNING: Control flow ignored unimplemented instructions", "unimplemented-instruction"), + ("WARNING: Exceeded the 1 instruction budget: some flow is truncated", "instruction-limit"), + ("WARNING (jumptable): Could not recover jumptable at 0x10. Too many branches", "jumptable"), + ("WARNING: structured blocks unavailable (structuring declined)", "structuring-declined"), + ("WARNING: funcboundflow: fall-through reached the next function entry", "funcboundflow"), + ("WARNING: calltrampoline: 0x0044a677 discards the return address", "calltrampoline"), + ("WARNING: ptrarith problems", "other"), + ("WARNING: Unknown: data", "other"), + ] { + assert_eq!(warning(text).kind(), kind, "{text}"); + } +} + +#[test] +fn a_message_is_the_text_less_its_marker() { + assert_eq!(warning("WARNING: Subroutine does not return").message(), "Subroutine does not return"); + assert_eq!( + warning("WARNING (jumptable): Treating indirect jump as return").message(), + "(jumptable): Treating indirect jump as return" + ); + assert_eq!(warning("no marker").message(), "no marker"); +} + +#[test] +fn lines_are_rebased_past_the_leading_newlines() { + let mut warnings = vec![warning("WARNING: a"), warning("WARNING: b")]; + warnings[0].line = 3; + warnings[1].line = 7; + trim_lines(&mut warnings, "\n\nvoid f(void)\n"); + assert_eq!(warnings.iter().map(|w| w.line).collect::>(), [1, 5]); + trim_lines(&mut warnings, "void f(void)\n"); + assert_eq!(warnings.iter().map(|w| w.line).collect::>(), [1, 5]); +} diff --git a/decompiler/crates/kuna-decomp/src/p9_emit/mod.rs b/decompiler/crates/kuna-decomp/src/p9_emit/mod.rs index c9c6d1404c..bfe69769b3 100644 --- a/decompiler/crates/kuna-decomp/src/p9_emit/mod.rs +++ b/decompiler/crates/kuna-decomp/src/p9_emit/mod.rs @@ -68,6 +68,7 @@ pub mod kuna_swiftstrobj; // (kuna) a Swift string object is not a pointer to th pub mod kuna_renderfault; // (kuna) test-only: panic one function's render partway through pub mod kuna_truncarg; pub mod kuna_pointerargs; // (kuna) a scalar's address passed to a character-pointer parameter +pub mod kuna_functionwarnings; // (kuna) the analysis warnings a render wrote, where the engine recorded them pub mod kuna_castimplied; // (kuna) casts C's own conversions already perform pub mod kuna_castnarrow; // (kuna) a narrowing C's own assignment, argument or return conversion performs keeps no cast pub mod kuna_declorder; // (kuna) the order local declarations print in diff --git a/decompiler/crates/kuna-decomp/src/p9_emit/printc.rs b/decompiler/crates/kuna-decomp/src/p9_emit/printc.rs index 72ac9e892d..0763bef967 100644 --- a/decompiler/crates/kuna-decomp/src/p9_emit/printc.rs +++ b/decompiler/crates/kuna-decomp/src/p9_emit/printc.rs @@ -1564,7 +1564,14 @@ pub struct PrintC { /// as one `// slug, slug` end-of-line comment by /// [`flush_eol_warnings`](PrintC::flush_eol_warnings) at the owning line's /// last token (statement `;`, `if (cond) {` header, prototype, ...). - pub(crate) eol_warns: Vec<(String, std::rc::Rc, u64)>, + pub(crate) eol_warns: Vec<( + String, + std::rc::Rc, + u64, + Option, + )>, + /// The analysis warnings the last plain render wrote, positioned in its text. + warnings: Vec, /// Per-document spelling for a local HighVariable whose recovered name /// collides in the C function scope. Body references consume the same map. local_name_overrides: std::collections::HashMap, @@ -1636,6 +1643,7 @@ impl PrintC { rt_ctx: RealTypeCtx::OFF, out_lang: crate::kuna_lang::OutLang::C, eol_warns: Vec::new(), + warnings: Vec::new(), local_name_overrides: std::collections::HashMap::new(), indirect_input_aliases: std::collections::HashSet::new(), signature_param_names: std::collections::HashMap::new(), @@ -1977,6 +1985,7 @@ impl PrintC { self.clear_rpn(); self.emit_fd = None; self.eol_warns.clear(); + self.warnings.clear(); self.void_tail_return = None; self.stmt_op = None; self.label_names.clear(); @@ -2437,6 +2446,23 @@ impl PrintC { Some(record) } + /// The analysis warnings the last plain render, whose text was `untrimmed`, + /// wrote, positioned against that text with its leading newlines removed. + pub fn take_warnings(&mut self, untrimmed: &str) -> Vec { + let mut warnings = std::mem::take(&mut self.warnings); + crate::kuna_functionwarnings::trim_lines(&mut warnings, untrimmed); + warnings + } + + /// Record `warning` on the line of the comment `token` just written; a + /// markup pass records nothing. + fn record_warning(&mut self, mut warning: crate::kuna_functionwarnings::Warning, token: &str) { + if let PrintEmit::NoMarkup(emit) = &mut self.emit { + warning.line = emit.position().line - token.matches('\n').count(); + self.warnings.push(warning); + } + } + /// C++ `PrintC::docFunction` (printc.cc:2790), transcribed faithfully and /// driven over a real [`Funcdata`] + [`Architecture`]: emit the signature /// shell (real return type from the recovered proto), then the **structured @@ -2621,6 +2647,9 @@ impl PrintC { self.declared_entry = Some(fd.get_address().clone()); self.pointer_decls.clear(); self.begin_pointer_record(fd); + if !self.emit.emits_markup() { + self.warnings.clear(); + } // (kuna `signedness`) Round the declared signedness of this function's // integer locals from the operations applied to them. Computed before // any declaration is written and consumed by @@ -2721,13 +2750,13 @@ impl PrintC { // a pipeline failure (the driver stamped its reason), NOT structuring // declining on analyzed IR. self.emit.tag_line(); - let text = match fd.kuna_pipeline_failure() { - Some(reason) => format!("/* WARNING: decompilation failed: {reason} */"), - None => { - "/* WARNING: structured blocks unavailable (structuring declined) */".to_string() - } + let warning = match fd.kuna_pipeline_failure() { + Some(reason) => format!("WARNING: decompilation failed: {reason}"), + None => "WARNING: structured blocks unavailable (structuring declined)".to_string(), }; + let text = format!("/* {warning} */"); self.emit.print(&text, SyntaxHighlight::CommentColor); + self.record_warning(crate::kuna_functionwarnings::Warning::new(None, &warning), &text); } // (kuna warnstyle, DIV-39) drain any slug still pending from a // construct with no closer flush point onto the last body line, so no @@ -3105,18 +3134,16 @@ impl PrintC { for text in headers { // (kuna warnstyle, DIV-39) Inline mode: header warnings collect as // slugs and flush at the end of the prototype line. + let warning = crate::kuna_functionwarnings::Warning::new(Some(off), &text); if self.options.warn_inline { - self.eol_warns.push((warning_slug(&text), std::rc::Rc::clone(&space), off)); + self.eol_warns.push((warning_slug(&text), std::rc::Rc::clone(&space), off, Some(warning))); continue; } // emitLineComment(0, comm): a fresh line then the `/* text */` token. self.emit.tag_line(); - self.emit.tag_comment( - &format!("/* {text} */"), - SyntaxHighlight::CommentColor, - &space, - off, - ); + let token = format!("/* {text} */"); + self.emit.tag_comment(&token, SyntaxHighlight::CommentColor, &space, off); + self.record_warning(warning, &token); } } @@ -4497,6 +4524,9 @@ impl PrintC { if (instr_comment_type & tp) == 0 { continue; } + let warning = (tp == ct::WARNING && addr.get_space().is_some()).then(|| { + crate::kuna_functionwarnings::Warning::new(Some(addr.get_offset()), &String::from_utf8_lossy(&text)) + }); // (kuna warnstyle, DIV-39) Inline mode: a WARNING comment becomes a // terse `// slug` collected for the owning line's end; every other // comment type keeps the banner-line render. @@ -4508,12 +4538,16 @@ impl PrintC { warning_slug(&text_str), space, addr.get_offset(), + warning, )); self.commsorter.mark_last_emitted(); continue; } } self.emit_line_comment(-1, &text, &addr); + if let Some(warning) = warning { + self.record_warning(warning, &String::from_utf8_lossy(&text)); + } // emitLineComment sets comm->setEmitted(true) (printlanguage.cc:655), // so a later walk over the same window skips it. self.commsorter.mark_last_emitted(); @@ -4535,12 +4569,11 @@ impl PrintC { let joined = warns.iter().map(|w| w.0.as_str()).collect::>().join(", "); self.emit.spaces(1, 0); - self.emit.tag_comment( - &format!("// {joined}"), - SyntaxHighlight::CommentColor, - &space, - off, - ); + let token = format!("// {joined}"); + self.emit.tag_comment(&token, SyntaxHighlight::CommentColor, &space, off); + for warning in warns.into_iter().filter_map(|w| w.3) { + self.record_warning(warning, &token); + } } /// C++ `PrintLanguage::emitLineComment` (printlanguage.cc:596): a fresh line diff --git a/decompiler/crates/kuna-wasm/src/inspect.rs b/decompiler/crates/kuna-wasm/src/inspect.rs index 1ce820fdad..1ac9f4fb1c 100644 --- a/decompiler/crates/kuna-wasm/src/inspect.rs +++ b/decompiler/crates/kuna-wasm/src/inspect.rs @@ -228,6 +228,7 @@ fn function_json(prog: &ConsoleProgram, f: &FuncResult, kind: &str, sections: &[ .opt_str("error", f.error.as_deref()) .opt_str("proto", f.proto.as_deref()) .num("unstructured_gotos", f.unstructured_gotos()) + .raw("warnings", &crate::warnings_json(&f.warnings)) .raw("line_mappings", &line_mappings) .raw("variables", &variables) .raw("types", &types) diff --git a/decompiler/crates/kuna-wasm/src/lib.rs b/decompiler/crates/kuna-wasm/src/lib.rs index c38ad3bd16..1d6d2107b0 100644 --- a/decompiler/crates/kuna-wasm/src/lib.rs +++ b/decompiler/crates/kuna-wasm/src/lib.rs @@ -719,6 +719,18 @@ fn list_json( s } +/// A function's `warnings`, each `{kind,message,line,address}`. +pub(crate) fn warnings_json(warnings: &[kuna_decomp::kuna_functionwarnings::Warning]) -> String { + arr(warnings.iter().map(|w| { + Obj::new() + .str("kind", &w.kind()) + .str("message", &w.message()) + .num("line", w.line) + .opt_num("address", w.address) + .end() + })) +} + /// The `decompile` document (`decompile_all.rs::result_json`'s fields with /// `kind` after `address_hex`). `kinds` is parallel to `funcs`. fn result_json( @@ -750,6 +762,7 @@ fn result_json( s.push_str(&format!(" \"code\": {},\n", json_opt_str(f.code.as_deref()))); s.push_str(&format!(" \"error\": {},\n", json_opt_str(f.error.as_deref()))); s.push_str(&format!(" \"unstructured_gotos\": {},\n", f.unstructured_gotos())); + s.push_str(&format!(" \"warnings\": {},\n", warnings_json(&f.warnings))); s.push_str(&format!( " \"line_mappings\": {},\n", arr(f.line_mappings.iter().map(|m| { diff --git a/docs/cli.md b/docs/cli.md index 3d4c6c29b7..b9c6a647e5 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1771,7 +1771,8 @@ numbers a caller orients by are the ones `kuna functions` reports. `--json` emits `{binary,count,functions:[{name,address,address_hex,aliases,object_location,size,code,error, -unstructured_gotos,line_mappings:[{line_number,addresses}],variables:[{name,type,kind,arg_index, +unstructured_gotos,warnings:[{kind,message,line,address}], +line_mappings:[{line_number,addresses}],variables:[{name,type,kind,arg_index, stack_offset,size,line_numbers,addresses}],types:[{name,definition,size}]}]}` (`kuna functions --json` emits `name`/`address`/`address_hex`/`aliases`/`object_location`/`size` per function; with `--reachable-from`, which already walks the image, it also carries a top-level `limits` @@ -1798,6 +1799,33 @@ translation; it is `0` on every C render, and a non-zero one is also spoken as a `note:` on stderr. It does not change the run's verdict — a record with a `null` `error` and a non-zero `unstructured_gotos` is usable output with named lossy sites, which is what makes it worth filtering or re-running on. +`warnings` lists the analysis warnings the engine wrote into `code` as +comments, one `{kind,message,line,address}` per warning in the order it wrote +them, so a consumer can tell a truncated body from a clean one without parsing +the C. It is always present, `[]` for a function with none and for a failed +one. The entries come from the engine's own warning records, not from the text: +a comment that only spells a warning (an `--assert comment` reading +`WARNING: ...`, a storage comment, the original name a Rust or Go render keeps +above the prototype) is never listed. `message` is the engine's text less its +`WARNING: ` marker (`Subroutine does not return`, `Bad instruction - Truncating +control flow here`), the same under both `warnstyle` values, though `inline` +prints it as a slug; `line` is the 1-based line of `code` carrying its comment, +which joins to `line_mappings`. `address` is the instruction the engine +recorded a body warning at (the bad instruction, the truncated or out-of-bounds +flow, the unresolved indirect jump), and the function's `address` for a header +warning; it is `null` only for `structuring-declined`, the printer's own note on +a body it has no structure for. `kind` is a stable code: `bad-instruction` and +`unimplemented-instruction` for decode failures; `instruction-limit` for a flow +cut at the instruction budget; `jump-as-call`, `jump-as-return` and `jumptable` +for an indirect jump left unresolved; `out-of-bounds`, `unmapped-flow` and +`funcboundflow` for flow that left the function's extent or the mapped image; +`structuring-declined` for a body the printer could not structure; the slug +`warnstyle inline` prints for any other warning it abbreviates (`no-return`, +`tail-call`, `branch-flip`, `return-dupe`, `inlined`, ...), less its ` xN` +count; the producer tag of a kuna warning (`calltrampoline`, `overlapbranch`, +`tailcallframe`, ...); and `other` for the rest. Like `unstructured_gotos`, a +warning does not change the verdict: `error` stays reserved for a function that +failed to decompile, and the exit status is the same with or without warnings. A variable's `kind` is `arg` for a parameter, `stack` for a local with a frame offset, and `register` for a local the C declares outside the stack frame (a register, a temporary, or a value with no storage of its own). A `register` row carries the @@ -1868,9 +1896,9 @@ whose variables were examined and none reported, and an absent `stack_objects` with no `omitted` still means none were recovered. A document that omits nothing has no `omitted` key, so the default document is unchanged. The run-level `language`, `count`, `error` and `assertions` and each record's `name`, -`address`, `address_hex`, `object_location`, `size`, `code`, `error` and -`unstructured_gotos` (and `interior_to` and `declared`, where they apply) are -always present; +`address`, `address_hex`, `object_location`, `size`, `code`, `error`, +`unstructured_gotos` and `warnings` (and `interior_to` and `declared`, where +they apply) are always present; `code` and the exit status are what they are without the flag. An unknown key exits 2. @@ -1880,7 +1908,7 @@ kuna decompile ./fixture audit_many --json --omit aliases,line_mappings,variable # "omitted": ["aliases", "line_mappings", "variables", "types", "stack_objects"], # "count": 1, "error": null, # "functions": [{"name": "audit_many", ..., "code": "void audit_many(void) ...", -# "error": null, "unstructured_gotos": 0}], +# "error": null, "unstructured_gotos": 0, "warnings": []}], # "assertions": []} ``` diff --git a/docs/spec/09-emission.md b/docs/spec/09-emission.md index 04149d5ace..b5b47a5ca0 100644 --- a/docs/spec/09-emission.md +++ b/docs/spec/09-emission.md @@ -3315,6 +3315,39 @@ deliberately outside this count: it is a different lossy construct, and naming one number `unstructured_gotos` that meant two things would be worse than reporting the one. +**A function's warnings are recorded as the printer writes them.** Each +per-function JSON record carries `warnings`, taken from the engine's warning +store rather than read back out of `code`. `p9_emit/kuna_functionwarnings.rs` +holds one record per warning a render wrote: the address the engine indexed +it at, its stored text, and the line of the render holding its comment. The printer records one wherever it writes a +warning: `printc.rs (PrintC::emit_comment_func_header)` for a `warningheader` +comment, at the function's entry; `printc.rs (PrintC::emit_comment_group)` for a +comment whose type is exactly `WARNING`, the type `Funcdata::warning` stamps, at +the instruction it was indexed at; `printc.rs (PrintC::flush_eol_warnings)`, +which gives every warning collected under `warnstyle inline` the line it +appends them to, so the warnings joined into one `// a, b` comment keep an +address each; and the shell a body without structured blocks prints +(`structured blocks unavailable`, or `decompilation failed` on the console's +text surface), which has no address. A comment of any other type never reaches +a record, whatever it spells: an `--assert comment` (its type carries the user +bit), a declaration's storage comment, a DWARF line, the original name a Rust or +Go render keeps above the prototype. Only a plain render records; a markup pass +over the same function keeps the plain render's records, and +`printc.rs (PrintC::take_warnings)` rebases their lines onto the trimmed `code` +as `take_pointer_arguments` does. The edits made after printing (the cookie +return rewrite, pointer-argument casts, the `--jobs` structure renames) keep +every line where it was, so each record's `line` holds its comment. The +records ride `FuncResult::warnings` across the `--jobs` wire and the result +store, and each address is mapped to the target's address units as +`line_mappings` is. `kind` is the kind of an engine stem the slugs leave whole +(`STEMS`: decode failures, flow truncation, out-of-bounds and unmapped flow, +unrecovered jump tables, declined structuring), else the slug +`printc.rs (warning_slug)` gives the text, less its ` xN` count, so a slug added +there is a kind at once; else a kuna warning's producer tag, else `other`. +`message` is the stored text less its `WARNING: ` marker. Both warning styles +give the same records but for `line`. The verdict does not move here either; +`error` stays reserved for a failed function. + Go integer stores use `p9_emit/kuna_gostorevalue.rs` to match the rendered pointer's pointee type. When both source and destination are signed or unsigned integers of the same one-, two-, four- or eight-byte width with different