Document the .risu format in the README

Document the .risu file format in the README, rather than in
three duplicate comments in risugen, arm.risu and thumb.risu.

1 files changed, 32 insertions, 0 deletions

diff --git a/README b/README
index a66e6f0..1852a84 100644
--- a/README
+++ b/README
@@ -55,6 +55,38 @@ mismatch status to its standard output.
 NB that in the register dump the r15 (pc) value will be given
 as an offset from the start of the binary, not an absolute value.
 
+File format
+-----------
+
+The .risu file specifies instruction patterns to be tested.
+
+Lines starting with '#' are comments and are ignored.
+Blank lines are ignored.
+
+Lines starting with a '.' are directives to risu/risugen:
+ * ".mode [thumb|arm]" specifies whether the file contains ARM
+   or Thumb instructions; it must precede all instruction patterns.
+
+Other lines are instruction patterns:
+ insnname encodingname bitfield ... [ { eval-block } ]
+where each bitfield is either:
+  var:sz  specifying a variable field of size sz (sz == 0 if :sz omitted)
+  [01]*   specifying fixed bits
+Field names beginning 'r' are special as they are assumed to be general
+purpose registers. They get an automatic "cannot be 13 or 15" (sp/pc)
+constraint.
+The optional eval-block at the end of the line (which must be
+enclosed in braces) is a perl statement to be evaluated and which
+must return true if the generated statement is OK, false if the
+generator should retry with a fresh random number. It is evaluated
+in a context where variables with the same names as the defined
+variable fields are initialised. The intention is that odd cases
+where you need to apply some sort of constraint to the generated
+instruction can be handled via this mechanism.
+NB that there is no sanity checking that you don't do bad things
+in the eval block, although there is a basic check for syntax
+errors and and we bail out if the constraint returns failure too often.
+
 Implementation details and points to note
 -----------------------------------------