Post-Link Layout Optimization

Post-link layout optimization is an explicit release optimization path. It is

not part of the default developer build loop. The goal is to improve final

binary layout after ordinary PGO and Thin summary optimization while preserving

determinism, relocation safety, binary-size budgets, and clear fail-closed

diagnostics.

Run:

make post-link-layout-check
make native-post-link-check

make native-post-link-check depends on both make pgo-thin-summary-check and

make post-link-layout-check. Profile evidence must be valid before layout

evidence can pass.

Evidence Files

• post-link-layout/strategy.tsv selects the supported strategy per target.
• post-link-layout/block-metadata.tsv records block-level layout metadata

where the object format supports it.

• post-link-layout/order-files.tsv records generated and consumed function

and block order files.

• post-link-layout/orders/ stores source-owned order files.
• post-link-layout/counters.tsv defines the required performance counters.
• post-link-layout/fallback-policy.tsv records fail-closed behavior and

explicit function-order fallback behavior.

• post-link-layout/diagnostics.tsv defines stable diagnostics.
• release/post-link-layout-strategy-report.tsv records selected strategies.
• release/post-link-layout-order-report.tsv records order-file hashes.
• release/post-link-layout-metrics-report.tsv records before/after binary

size, startup, and runtime counters.

• release/post-link-layout-fallback-report.tsv records fallback behavior.
• release/post-link-layout-diagnostics-report.tsv records negative

diagnostics.

• perf/post-link-layout-performance-evidence.tsv records performance

evidence.

• compat/post-link-layout-contract.tsv records release ownership and gate

wiring.

• tools/post-link-layout-check.py validates all rows and fixtures.

Strategy Selection

Each target must select a supported strategy or fail closed:

• hosted x86_64-unknown-linux-elf supports the 0x0 native ordering-file path;
• hosted x86_64-unknown-linux-elf records a Propeller-like relinking strategy

when object block sections are available;

• hosted x86_64-unknown-linux-elf rejects BOLT-like binary rewriting until

relocation and unwind coverage are complete;

• thumbv6m-none-eabi supports function-order-only firmware layout when block

sections are unavailable;

• wasm32-unknown-unknown fails closed because WASM layout is owned by the

WASM lowering milestone.

Every strategy row is explicit-only and must not run on the default developer

path.

Order Files And Metrics

The gate records both function-order and block-order files when the target can

emit block sections. Order files are consumed only when their input hash,

output hash, profile hash, and relocation evidence are current.

The release metrics report records:

• binary size before and after layout;
• instruction-cache misses;
• instruction TLB misses;
• branch misses;
• startup page faults;
• cold-start time.

A layout decision fails when any required metric regresses beyond its budget or

when binary size grows beyond the recorded release budget.

Diagnostics

The gate rejects unsupported or unsafe layout decisions with stable

diagnostics:

POST_LINK_LAYOUT_UNSUPPORTED_TARGET
POST_LINK_LAYOUT_BLOCK_METADATA
POST_LINK_LAYOUT_ORDER_HASH
POST_LINK_LAYOUT_COUNTER_REGRESSION
POST_LINK_LAYOUT_PROFILE
POST_LINK_LAYOUT_RELOCATION
POST_LINK_LAYOUT_DEFAULT_PATH

Unsupported targets, missing block metadata, stale or missing profiles, missing

relocation evidence, order hash drift, metric regressions, and accidental

default-path enablement all fail closed.

Documentation Impact

Compiler, linker, object format, profile, or native toolchain changes that

alter post-link layout strategy, block metadata, order files, metrics,

fallbacks, or diagnostics must update this page, the evidence TSV files,

release notes, and public reference index in the same change.