From de240ee5609a28f4646251c0c083b028b501e2b6 Mon Sep 17 00:00:00 2001
From: Nick Knight <nick.knight@sifive.com>
Date: Mon, 28 Sep 2020 18:48:00 -0700
Subject: [PATCH] Document branch relaxation

---
 riscv-asm.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/riscv-asm.md b/riscv-asm.md
index 5d60b93..84b09e4 100644
--- a/riscv-asm.md
+++ b/riscv-asm.md
@@ -449,6 +449,36 @@ as seen by `objdump`:
   14:	00028067          	jr	t0 # 0x10
 ```
 
+Branches
+--------------------
+
+Unconditional branches are implemented by the `j(al)?r?` pseudoinstructions.
+(The underlying instructions are `jalr?`.)
+The `j(al)?` targets can be any symbol or address.
+
+Conditional branches are implemented by the `b(l|g)(t|e)(z|u)?` and `b(eq|ne)z?` pseudoinstructions.
+(The underlying instructions are `b(lt|ge)u?` and `b(eq|ne)`.)
+Again, the targets can be any symbol or address.
+
+Various relaxations are performed when the target's offset from the branch exceeds the range of the underlying instruction's immediate field.  
+
+For example,
+
+```assembly
+        beqz t0, foo
+```
+
+may be relaxed to a sequence of the form
+
+```assembly
+        bnez t0, 1f
+        j    foo 
+1:
+```
+
+The `bnez` is further relaxed to `bne`, while `j` is relaxed to `jal` with a relocation.
+
+
 Floating-point rounding modes
 -----------------------------