From d118532afc4c28e0a377e132a1dcb0157ccf601d Mon Sep 17 00:00:00 2001
From: Andrew Waterman <andrew@sifive.com>
Date: Sat, 16 Sep 2023 16:30:16 -0700
Subject: Incorporate @gfavor's feedback on Zimop

---
 src/zimop.adoc | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

(limited to 'src/zimop.adoc')

diff --git a/src/zimop.adoc b/src/zimop.adoc
index a1d64f3..70a86a4 100644
--- a/src/zimop.adoc
+++ b/src/zimop.adoc
@@ -9,16 +9,16 @@ encoding space for 40 MOPs.
 [NOTE]
 ====
 It is sometimes desirable to define instruction-set extensions whose
-instructions do not raise illegal-instruction exceptions when the extension is
-not implemented.  For example, programs with control-flow integrity checks can
+instructions, rather than raising illegal instruction exceptions when the extension is
+not implemented, take no useful action.
+For example, programs with control-flow integrity checks can
 execute correctly on implementations without the corresponding extension,
 provided the checks are simply ignored.  Implementing these checks as MOPs
 allows the same programs to run on implementations with or without the
 corresponding extension.
 
-Although similar in some respects to HINTs, most MOPs cannot be encoded as
-HINTs, because MOPs might sometimes alter architectural state, which HINTs are
-forbidden from doing.
+Although similar in some respects to HINTs, MOPs cannot be encoded as HINTs,
+because unlike HINTs, MOPs are allowed to alter architectural state.
 ====
 
 The Zimop extension defines 32 MOP instructions named `mop.r.__n__`, where
@@ -39,6 +39,11 @@ read `x[rs1]` and `x[rs2]`, as well as write `x[rd]`.
 include::images/wavedrom/mop-rr.adoc[]
 [[mop-rr]]
 
+NOTE: The recommended assembly syntax for `mop.r.__n__` is `mop.r.__n__ rd, rs1`,
+with any `x`-register specifier being valid for either argument.  Similarly for
+`mop.rr.__n__`, the recommended syntax is `mop.rr.__n__ rd, rs1, rs2`.
+The extension that redefines a MOP may define an alternate assembly mnemonic.
+
 NOTE: These MOPs are encoded in the SYSTEM major opcode in part because it is
 expected their behavior will be modulated by privileged CSR state.
 
@@ -66,6 +71,8 @@ to define them to read register `x[__m__]`.
 include::images/wavedrom/c-mop.adoc[]
 [[c-mop]]
 
+NOTE: The recommended assembly syntax for `c.mop.__n__` is simply the nullary
+`c.mop.__n__`.  The possibly accessed register is implicitly `x__m__`.
 
 NOTE: The expectation is that each Zcmop instruction is equivalent to some
 Zimop instruction, but the choice of expansion (if any) is left to the
-- 
cgit v1.1

