cmd/internal/obj/riscv: document compressed instructions

We update the RISC-V assembler documentation to describe how
the RISC-V compressed instruction set is implemented by the
assembler and how compressed instructions can be disabled.

Change-Id: Ic7b1cb1586e6906af78adb8ff5fa10f5fbfde292
Reviewed-on: https://go-review.googlesource.com/c/go/+/719221
Reviewed-by: Mark Freeman <markfreeman@google.com>
Reviewed-by: Cherry Mui <cherryyz@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Joel Sing <joel@sing.id.au>
Auto-Submit: Joel Sing <joel@sing.id.au>
Reviewed-by: Meng Zhuo <mengzhuo1203@gmail.com>

1 files changed, 27 insertions, 0 deletions

diff --git a/src/cmd/internal/obj/riscv/doc.go b/src/cmd/internal/obj/riscv/doc.go
index 365bedd299..898a45b0e6 100644
--- a/src/cmd/internal/obj/riscv/doc.go
+++ b/src/cmd/internal/obj/riscv/doc.go
@@ -289,6 +289,33 @@ the constant literal is 0.0, MOVF and MOVD will be encoded as FLW and FLD
 instructions that load the constant from a location within the program's
 binary.
 
+# Compressed instructions
+
+The Go assembler converts 32 bit RISC-V instructions to compressed
+instructions when generating machine code. This conversion happens
+automatically without the need for any direct involvement from the programmer,
+although judicious choice of registers can improve the compression rate for
+certain instructions (see the [RISC-V ISA Manual] for more details). This
+behaviour is enabled by default for all of the supported RISC-V profiles, i.e.,
+it is not affected by the value of the GORISCV64 environment variable.
+
+The use of compressed instructions can be disabled via a debug flag,
+compressinstructions:
+
+  - Use -gcflags=all=-d=compressinstructions=0 to disable compressed
+    instructions in Go code.
+  - Use -asmflags=all=-d=compressinstructions=0 to disable compressed
+    instructions in assembly code.
+
+To completely disable automatic instruction compression in a Go binary both
+options must be specified.
+
+The assembler also permits the use of compressed instructions in hand coded
+assembly language, but this should generally be avoided. Note that the
+compressinstructions flag only prevents the automatic compression of 32
+bit instructions. It has no effect on compressed instructions that are
+hand coded directly into an assembly file.
+
 [RISC-V ISA Manual]: https://github.com/riscv/riscv-isa-manual
 [rva20u64]: https://github.com/riscv/riscv-profiles/blob/main/src/profiles.adoc#51-rva20u64-profile
 [rva22u64]: https://github.com/riscv/riscv-profiles/blob/main/src/profiles.adoc#rva22u64-profile