From 0865245f26033c58520c21eb6d8593236d116bfc Mon Sep 17 00:00:00 2001 From: Simon Cook Date: Thu, 13 Feb 2025 15:41:07 +0000 Subject: [PATCH] Rewrite the far branches During the latest Toolchain SIG meeting it was raised that this section does not make its intent and behavior clear enough. This rewords the prose to explain what is going on in more detail. --- src/asm-manual.adoc | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/asm-manual.adoc b/src/asm-manual.adoc index 5fa0d0b..02ca4e8 100644 --- a/src/asm-manual.adoc +++ b/src/asm-manual.adoc @@ -809,9 +809,10 @@ as seen by `objdump`: == Far Branches -The assembler will convert conditional branches into far branches when -necessary, via inserting a short branch with inverted conditions past an -unconditional jump. For example +When a conditional branch cannot reach a destination, the assembler will replace +these with far branches which use the longer offset available to unconditional +jumps to reach the destination. This is done by inserting a short branch with +inverted conditions past an unconditional jump. For example: [source, asm] ---- @@ -823,7 +824,12 @@ target: bne a0, a1, target ---- -ends up as +This example uses a series of `nop`s to separate the final instruction from the +branch target `target` such that the second `bne` instruction cannot reach it +with its offset. As such a unconditional branch to the target is added and the +original instruction replaced with a conditional branch with inverted conditions +to jump over this new instruction. Consequently, the final assembled binary +contains the following: [source, asm] ----