add missing documentation and rename for clarity

documentation added for macros and helper functions.

plugins/arm/semantics/aarch64-arithmetic.lisp

@@ -12,9 +12,9 @@
 ;; and doesn't actually change from lshift
 (defun ADDWri (rd rn imm off) (ADD*r* setw lshift rd rn imm off))
 (defun ADDXri (rd rn imm off) (ADD*r* set$ lshift rd rn imm off))
-;; shifted decodes the shift type and shifts
-(defun ADDWrs (rd rn rm off) (ADD*r* setw shifted rd rn rm off))
-(defun ADDXrs (rd rn rm off) (ADD*r* set$ shifted rd rn rm off))
+;; shift-encoded decodes the shift type and shifts
+(defun ADDWrs (rd rn rm off) (ADD*r* setw shift-encoded rd rn rm off))
+(defun ADDXrs (rd rn rm off) (ADD*r* set$ shift-encoded rd rn rm off))
 
 (defun ADRP (dst imm)
   (set$ dst (+
@@ -28,17 +28,17 @@
 ;; see ADD*ri vs ADD*rs
 (defun SUBWri (rd rn rm off) (SUB*r* setw lshift rd rn rm off))
 (defun SUBXri (rd rn rm off) (SUB*r* set$ lshift rd rn rm off))
-(defun SUBWrs (rd rn rm off) (SUB*r* setw shifted rd rn rm off))
-(defun SUBXrs (rd rn rm off) (SUB*r* set$ shifted rd rn rm off))
+(defun SUBWrs (rd rn rm off) (SUB*r* setw shift-encoded rd rn rm off))
+(defun SUBXrs (rd rn rm off) (SUB*r* set$ shift-encoded rd rn rm off))
 
 (defun SUBXrx64 (rd rn rm off)
   (set$ rd (- rn (extended rm off))))
 
 (defun SUBSWrs (rd rn rm off)
-  (add-with-carry/clear-base rd rn (lnot (shifted rm off)) 1))
+  (add-with-carry/clear-base rd rn (lnot (shift-encoded rm off)) 1))
 
 (defun SUBSXrs (rd rn rm off)
-  (add-with-carry rd rn (lnot (shifted rm off)) 1))
+  (add-with-carry rd rn (lnot (shift-encoded rm off)) 1))
 
 (defun SUBSWri (rd rn imm off)
   (add-with-carry/clear-base rd rn (lnot (lshift imm off)) 1))

plugins/arm/semantics/aarch64-helper.lisp

@@ -9,23 +9,31 @@
 
 (defun word () (word-width))
 
-(defun shifted (rm off)
+(defun shift-encoded (rm off)
+  "(shift-encoded rm off) decodes the 8-bit shift value
+   into its type and offset, and shifts rm accordingly."
   (let ((typ (extract 7 6 off))
         (off (extract 5 0 off)))
     (case typ
       0b00 (lshift rm off)
       0b01 (rshift rm off)
       0b10 (arshift rm off)
-      ;; TODO: 0b11 ror?
+      0b11 (rotate-right rm off)
       )))
 
 (defun unsigned-extend (n rm)
+  "(unsigned-extend n rm) returns the unsigned extension (prepend with zeros)
+   of the lowest n bits of rm."
   (cast-unsigned (word-width) (cast-low n rm)))
 
 (defun signed-extend (n rm)
+  "(signed-extend n rm) returns the signed extension (prepend with rm[n-1])
+   of the lowest n bits of rm."
   (cast-signed (word-width) (cast-low n rm)))
 
 (defun extended (rm bits)
+  "(extended rm bits) decodes the extension type and amount from bits,
+   and returns the value of the extension on rm."
   (let ((typ (extract 5 3 bits))
         (off (extract 2 0 bits)))
     (lshift (case typ
@@ -75,6 +83,10 @@
     (decode-bit-masks N imms immr true)))
 
 (defun barrier-option-to-symbol (barrier-type option)
+  "(barrier-option-to-symbol barrier-type option) converts the
+   barrier type (:dmb, :dsb, :isb) and 4-bit optional value
+   to a symbol.
+   This is to be used with the (special) primitive."
   (case barrier-type
     :dmb
       (case option

plugins/arm/semantics/aarch64-logical.lisp

@@ -7,6 +7,8 @@
 ;; Logical
 
 (defmacro ORN*rs (set rd rn rm is)
+  "(ORN*rs set rd rn rm is) implements the OR NOT instruction
+   accepting either a W or X register."
   (set rd (logor rn (lnot (lshift rm is)))))
 
 (defun ORNWrs (rd rn rm is) (ORN*rs setw rd rn rm is))
@@ -15,7 +17,7 @@
 (defmacro log*rs (set op rd rn rm is)
   "(log*rs set op rd rn is) implements the logical operation (shift) instruction
    accepting either a W or X register. op is the binary logical operation."
-  (set rd (op rn (shifted rm is))))
+  (set rd (op rn (shift-encoded rm is))))
 
 (defun ORRWrs (rd rn rm is) (log*rs setw logor  rd rn rm is))
 (defun EORWrs (rd rn rm is) (log*rs setw logxor rd rn rm is))
@@ -40,6 +42,8 @@
 ;; (bitfield moves)
 
 (defmacro make-BFM (set cast xd xr ir is)
+  "(make-BFM set cast xd xr ir is) implements bitfield move instructions
+   accepting either a W or X register, with cast being an unsigned or signed cast."
   (let ((rs (word)))
     (if (< is ir)
         (if (and (/= is (- rs 1)) (= (+ is 1) ir))

plugins/arm/semantics/aarch64-pstate.lisp

@@ -9,7 +9,7 @@
    or CCMN*r. The semantics are the same at the lisp level;
    an immediate or register value is given as second argument."
   (if (condition-holds cnd)
-    (set-flags (+ rn rm-or-imm) rn rm-or-imm)
+    (set-nzcv-from-registers (+ rn rm-or-imm) rn rm-or-imm)
     (set-nzcv nzcv)))
 
 (defun CCMNWi (rn imm nzcv cnd) (CCMN** rn imm nzcv cnd))
@@ -23,7 +23,7 @@
    an immediate or register value is given as second argument."
   (if (condition-holds cnd)
     (let ((rm-or-imm (lnot rm-or-imm)))
-      (set-flags (+ rn rm-or-imm 1) rn rm-or-imm))
+      (set-nzcv-from-registers (+ rn rm-or-imm 1) rn rm-or-imm))
     (set-nzcv nzcv)))
 
 (defun CCMPWi (rn imm nzcv cnd) (CCMP** rn imm nzcv cnd))

plugins/arm/semantics/arm-bits.lisp

@@ -3,40 +3,58 @@
 
 (in-package arm)
 
-(defun set-flags (r x y)
+(defun set-nzcv-from-registers (r x y)
+  "(set-nzcv-from-registers r x y) sets the processor state flags
+   to the result of some arithmetic operation (op x y) with r as the result.
+   Common examples include:
+    (set-nzcv-from-registers (+ x y) x y)
+   or
+    (set-nzcv-from-registers (+ x y 1) x y)
+   This function was formerly named set-flags, but was renamed to improve clarity."
   (set NF (msb r))
   (set VF (overflow r x y))
   (set ZF (is-zero r))
   (set CF (carry r x y)))
 
 (defun set-nzcv (nzcv)
+  "(set-nzcv nzcv) sets the negative, zero, carry and overflow flags to
+   the bottom 4 bits of nzcv."
   (set NF (select 3 nzcv))
   (set ZF (select 2 nzcv))
   (set CF (select 1 nzcv))
   (set VF (select 0 nzcv)))
 
 (defun add-with-carry (rd x y c)
+  "(add-with-carry rd x y c) sets rd to the result of adding x and y
+   with carry bit c, and sets processor flags."
   (let ((r (+ c y x)))
-    (set-flags r x y)
+    (set-nzcv-from-registers r x y)
     (set$ rd r)))
 
 (defun add-with-carry/clear-base (rd x y c)
+  "(add-with-carry/clear-base rd x y c) sets rd to the result of adding x and y
+   with carry bit c after clearing the base register rd, and sets processor flags."
   (let ((r (+ c y x)))
-    (set-flags r y x)
+    (set-nzcv-from-registers r y x)
     (clear-base rd)
     (set$ rd r)))
 
 (defun add-with-carry/it-block (rd x y c cnd)
+  "(add-with-carry/it-block rd x y c cnd) sets rd to the result of adding x and y
+   with carry bit c if cnd holds, and sets processor flags if cnd is unconditional."
   (when (condition-holds cnd)
     (let ((r (+ c y x)))
       (when (is-unconditional cnd)
-        (set-flags r x y))
+        (set-nzcv-from-registers r x y))
       (set$ rd r))))
 
 (defun logandnot (rd rn)
   (logand rd (lnot rn)))
 
 (defmacro shift-with-carry (shift rd rn rm cnd)
+  "(shift-with-carry shift rd rn rm cnd) sets rd to the shifted
+   value of rn and rm, and relevant processor flags, when cnd holds.
+   The overflow flag is not changed."
   (when (condition-holds cnd)
     (let ((r (cast-signed (word-width) rn)))
       (when (is-unconditional cnd)
@@ -46,6 +64,8 @@
         (set NF (msb rd))))))
 
 (defun condition-holds (cnd)
+  "(condition-holds cnd) calculates the result of the given condition cnd
+   based on the values of processor flags."
   (case cnd
     0b0000 ZF
     0b0001 (lnot ZF)
@@ -64,9 +84,11 @@
     true))
 
 (defun is-unconditional (cnd)
+  "(is-unconditional cnd) checks whether cnd is unconditional, i.e. 0b1110."
   (= cnd 0b1110))
 
 (defun clear-base (reg)
+  "(clear-base reg) clears all of the register reg."
   (set$ (alias-base-register reg) 0))
 
 (defmacro setw (reg val)