add an example on defining ifields the complete way,

and a section on splicing arguments to define-*

diff --git a/cgen/doc/porting.texi b/cgen/doc/porting.texi
index 29e5f40..2df62e9 100644 (file)
--- a/cgen/doc/porting.texi
+++ b/cgen/doc/porting.texi
@@ -121,6 +121,7 @@ descriptions of each type of entry that appears in the description file.
 * Writing define-insn::              Instructions
 * Writing define-macro-insn::        Macro instructions
 * Using define-pmacro::              Preprocessor macros
+* Splicing list arguments::          List arguments in macros
 * Interactive development::          Useful things to do in a Guile shell
 @end menu
 
@@ -377,6 +378,62 @@ There are currently no shorthand macros for specifying the full-blown
 definition.  It is recommended that if you have to use one that you write
 a macro to reduce typing.
 
+Written out the full blown way, the f-op1 field would be specified as:
+
+@example
+
+(define-ifield
+  (name f-op1)
+  (comment "f-op1")
+  (attrs) ; no attributes, could be elided if one wants
+  (word-offset 0)
+  (word-length 16)
+  (start 15)
+  (length 4)
+  (mode UINT)
+  (encode #f) ; no special encoding, could be elided if one wants
+  (decode #f) ; no special encoding, could be elided if one wants
+)
+
+@end example
+
+A macro to simplify that could be written as:
+
+@example
+
+; dwf: define-word-field (??? pick a better name)
+
+(define-pmacro (dwf x-name x-comment x-attrs
+                    x-word-offset x-word-length x-start x-length
+                    x-mode x-encode x-decode)
+  "Define a field including its containing word."
+  (define-ifield
+    (name x-name)
+    (comment x-comment)
+    (.splice attrs (.unsplice x-attrs))
+    (word-offset x-word-offset)
+    (word-length x-word-length)
+    (start x-start)
+    (length x-length)
+    (mode x-mode)
+    (.splice encode (.unsplice x-encode))
+    (.splice decode (.unsplice x-decode))
+    )
+)
+
+@end example
+
+The @samp{.splice} is necessary because @samp{attrs}, @samp{encode},
+and @samp{decode} take a list as an argument.
+
+One would then write f-op1 as:
+
+@example
+
+(dwf f-op1 "f-op1" () 0 16 15 4 UINT #f #f)
+
+@end example
+
 (*) This doesn't include fields like multi-ifields.
 
 @node Writing define-normal-insn-enum
@@ -533,6 +590,53 @@ Here is an example from the M32R port.
 preprocessor's @code{##} concatenation operator.  @xref{Symbol
 concatenation}, and @xref{String concatenation}, for details.
 
+@node Splicing list arguments
+@subsection Splicing arguments
+
+Several cpu description elements take a list as an argument (as opposed
+to a scalar).
+When constructing a call to define-* in a pmacro, these elements must have
+their arguments spliced in to achieve the proper syntax.
+
+This is best explained with an example.
+Here's a simplifying macro for writing ifield definitions with every
+element specified.
+
+@example
+
+; dwf: define-word-field (??? pick a better name)
+
+(define-pmacro (dwf x-name x-comment x-attrs
+                    x-word-offset x-word-length x-start x-length
+                    x-mode x-encode x-decode)
+  "Define a field including its containing word."
+  (define-ifield
+    (name x-name)
+    (comment x-comment)
+    (.splice attrs (.unsplice x-attrs))
+    (word-offset x-word-offset)
+    (word-length x-word-length)
+    (start x-start)
+    (length x-length)
+    (mode x-mode)
+    (.splice encode (.unsplice x-encode))
+    (.splice decode (.unsplice x-decode))
+    )
+)
+
+@end example
+
+The @samp{.splice} is necessary because @samp{attrs}, @samp{encode},
+and @samp{decode} take a list as an argument.
+
+One would then write f-op1 as:
+
+@example
+
+(dwf f-op1 "f-op1" () 0 16 15 4 UINT #f #f)
+
+@end example
+
 @node Interactive development
 @subsection Interactive development