perf(aarch64): refuse a gap candidate the ARM64 PE unwind data places inside a routine

[r0ny123]

The ARM64 counterpart of #309: an ARM64 PE declares an exception directory too, the engine already reads it for candidates, and it never consulted it again when the gap scan carved entries out of addresses the image had declared to belong to a routine starting earlier.

#309 explicitly left this case open, because there is no ARM64 PE in the sample set that PR was measured against and it was itself the argument against shipping an unmeasured suppression rule. This PR closes it against a set that does contain them.

What is different about ARM64

An x64 RUNTIME_FUNCTION carries EndAddress. An ARM64 one does not: the extent has to be reconstructed, either from the packed unwind data in the record itself or from the .xdata record it points at. That is the only difference. Once an extent is known, what to do with it is identical, which is why the lookup moves rather than being written twice.

declaredExceptionRangeContaining and its _pdata_ranges state move from intel/FunctionCandidateManager up into common/FunctionCandidateManager, and the ARM64 manager fills the same list from what it reconstructs. The x64 path is unchanged — same list, same bisect, same running-maximum walk, same deliberate refusal to merge adjacent extents.

USE_PE_ARM64_PDATA_INTERIOR_GAPS, on by default, mirrors the x64 flag: a fragment record suppresses on its own because it says the whole extent is part of another function, a primary record only once the function it names has actually been recovered, and the scan resumes at the extent's end rather than one word on.

Branch layout

This branch stacks on #309 and on #310 plus its follow-up series, because it hoists code #309 introduces and edits a gap-scan loop those change. Its own commit is the last one; everything before it is those two PRs. Taking them first leaves this as a single commit on top.

Tests

tests/testAArch64PdataExtraction.py gains the interior-gap cases over a synthetic ARM64 PE carrying .pdata and .xdata: an interior address inside a recovered primary extent refused and the scan resumed at its end, a fragment record suppressing from its own first byte, a primary record not suppressing while the function it names is unrecovered, and the flag off restoring the old behaviour.

Validation

ruff check / ruff format --check pass, ty check exit 0, full suite green on this branch, and the x64 .pdata suite from #309 passes unchanged after the hoist — which is the assertion that the move is a move.

Branch shape

Rebased onto current master (395c88d) as 14 flat commits: #309's one, #311's ten, and this branch's own three. Dropped the five merge commits, the three pre-squash copies of #310, and three duplicate fix(ci) commits that had accumulated through the merges.

Content-neutral: the tree is 0b2ce4d, byte for byte what the merge-based version resolved to. ruff check, ruff format --check and ty 0.0.74 clean; the full suite was 1959 passed / 1 skipped / 2593 subtests on this identical tree.

Once #309 and #311 land this reduces to its own three commits, which is the shape described above.

[danielplohmann]

Merged. #309 and #311 went in first (68f2cfd, db5eff0), and this reduced to its own three commits exactly as you said it would.

The rebase checked out

I verified content-neutrality independently rather than take the tree hashes on trust — reconstructing each branch from the pre-rebase material I reviewed yesterday and comparing:

	how I rebuilt it	tree	matches
#309	cherry-picked the pre-rebase commit onto master, resolved SmdaConfig.py by keeping both blocks	0fb222b	yes
#311	cherry-picked the original ten onto master	38b27ba	yes
#312	master + #309 + #311's ten + your three	0b2ce4d	yes

Byte-identical in all three, so nothing needed re-measuring. The -> bool hazard you flagged is gone too: none of the three touches AArch64CapstoneVerification.py at all now.

The hoist is a move

This was the part I most wanted to confirm, since it edits a path #309 had just landed. declaredExceptionRangeContaining is character-identical between the two files apart from the chained → fragment rename and the added paragraph; bisect was already imported in common for the gap-index lookup, so dropping it from intel is correct and not a latent NameError. Both backends reset their own state and then call super().init(), which clears _pdata_ranges before locateCandidates(), so a reused manager cannot inherit the previous image's extents.

Scored every bundled fixture that can reach either .pdata path, before and after:

21 of 21 bit-identical function sets, including the six x64 PEs the hoist actually moves code under — rust_pe_gnu holds at 2201 with #309's suppression live, cxx_pe_gnu 87, msvc_cxx_pe 7, msvc_cxx_pdb_pe 5, cutwail 33, rust_pe_msvc_i686 4 — plus all 12 ARM64 Mach-O cells and aarch64_static at 278.

The length reconstruction

This is the only genuinely new logic, and a bit-field decode is where I would expect a mask to bleed, so I probed it against lengths computed by hand from the spec rather than through your assertions:

case	expected	result
packed primary, FunctionLength 0x40 words	0x100 bytes	ok
packed fragment (flag 2), 0x10 words	0x40 bytes, is_fragment=True	ok
packed, every field above FunctionLength set to 1s (RegF 7, RegI 15, H, CR 3, FrameSize 0x1FF)	0x11 words, unpolluted	ok
packed maximum, 0x7FF words (the full 11 bits)	0x1FFC bytes	ok
full .xdata, header FunctionLength 0x123 words	0x48C bytes	ok
.xdata, CodeWords 31, EpilogCount 31, E, X all set	0x77 words, unpolluted	ok
reserved flag 3	declares nothing	ok
zero-length packed record	declares nothing	ok
.xdata with Vers != 0	refused	ok

(unwind_data >> 2) & 0x7FF and header_word & 0x3FFFF are the right 11 and 18 bits, and neither picks up a neighbouring field at its boundary.

Dropping the xdata_rva % 4 test is sound, and for the reason your comment gives: flag == 0 is the statement that the low two bits are clear, so the alignment test could never have failed on the one path that reaches it. Single call site, so there is no second caller relying on the old contract.

Nine of the new tests fail against master, so the set is non-vacuous. Full suite here: 1958 passed, 2 skipped, 2593 subtests.

What I could not verify, and it is the headline

There is no ARM64 PE in the bundled fixtures. I scanned all 104 fixture files for a PE machine field: 8 × i386, 4 × AMD64, 1 × 0xFD1D (the ReadyToRun image), and zero 0xAA64. So this PR's suppression path is inert on everything in the repo — which is exactly why all 21 fixtures come back identical, and it is the reassuring half of that number rather than the impressive half. The mechanism is verified; the accuracy claim rests entirely on your corpus, the same position #310 ended up in.

That is not a reason to hold it — the rule is #309's, and #309 measured well on a fixture that does move — but I am recording it so the release notes say "measured on the contributor's ARM64 PE corpus" rather than implying we reproduced it.

Two notes, neither blocking

The seeding caveat is now on the record but still open. Your third commit documents that USE_PE_ARM64_PDATA_CANDIDATES, on by default, over-reports on MSVC-built ARM64 images — 78 seeded starts inside functions IDA labels, only 6.4% of them named by Microsoft's PDBs — and that the .xdata handler-data test you hoped would separate them does not reach 120 of the 145 chunks. I would rather have that written down than quietly true, and the self-correction in the third commit is the useful kind. I am tracking it on our side so it does not decay into a comment nobody revisits; no action wanted from you.

The x64 hook logs its suppression, the ARM64 one does not. intel emits a LOGGER.debug naming the refused address; the AArch64 gap loop has no logging anywhere, so this is consistent with its own file rather than an omission. Mentioning it only because the first ARM64 PE that suppresses something surprising will be harder to explain than the x64 equivalent.

Thanks for flattening all three — and for catching the leaked fork issue references in the commit messages. That is the kind of thing that is invisible until it is permanent.

[danielplohmann]

Correction to the comment above: I posted "merged" a moment too early. #309 and #311 landing as squashes made this CONFLICTING — the same artifact you and I both predicted for this branch, arriving on schedule.

Rather than send it back to you for a third mechanical pass, I took it: force-pushed the rebase to upstream-aarch64-pdata-suppression as 8e7594b, your three commits on current master and nothing else.

before  cae175f  14 commits (#309's one, #311's ten, your three)
after   8e7594b   3 commits (yours)
tree    0b2ce4d  unchanged

The tree is the same 0b2ce4d you pushed and I verified, so nothing in the review above moves. The previous head was cae175f01662a3f3a065abf3f6d534f31cc22a47 if you want it back for any reason.

Merging once CI comes back green.