docs/rosette: Sort, Struct, and PrintVisitor sections

docs/source/yosys_internals/extending_yosys/functional_ir.rst

@@ -217,31 +217,27 @@ and racket specifications to save on space in this document.
 Sort
 ~~~~
 
-- map variable declarations to s-expressions
+The ``Sort`` class is a wrapper for the ``Functional::Sort`` class, providing
-- handles signals (bitvectors) and memories (arrays of bitvectors)
+the additional functionality of mapping variable declarations to s-expressions
+with the ``to_sexpr()`` method.  The main change from ``SmtSort`` to
+``SmtrSort`` is a syntactical one with signals represented as ``bitvector``\
+s, and memories as ``list``\ s of signals.
 
 .. literalinclude:: /code_examples/functional/rosette.diff
    :language: diff
    :caption: diff of ``Sort`` wrapper
-   :start-at: -struct SmtSort {
+   :start-at: SExpr to_sexpr() const {
-   :end-at: };
+   :end-before: };
 
 Struct
 ~~~~~~
 
-- helpers for defining inputs/outputs/state
+The SMT-LIB backend uses a class, ``SmtStruct``, to help with describing the
-- struct fields in Rosette are accessed as ``<struct_name>-<field_name>``
+input, output, and state data structs.  Where each struct in the SMT-LIB output
-   - field names only need to be unique within the struct, while accessors
+is a new ``datatype`` with each element having its type declared using the
-      are unique within the module
+`Sort`_ above, in Rosette we use the native ``struct`` with each field only
-
+being referred to by name.  For ease of use, we include comments for each field
-.. literalinclude:: /code_examples/functional/rosette.diff
+to indicate the expected type.
-   :language: diff
-   :caption: diff of struct constructor
-   :start-at: -  SmtStruct(std::string name, SmtScope &scope)
-   :end-before: void write_definition
-
-- each is a single (transparent) struct with zero or more fields
-- each field has a name, with the type (sort) as a comment
 
 .. literalinclude:: /code_examples/functional/rosette.diff
    :language: diff
@@ -249,7 +245,22 @@ Struct
    :start-at: void write_definition
    :end-before: template<typename Fn> void write_value
 
-- writing outputs/next state
+Struct fields in Rosette are accessed as ``<struct_name>-<field_name>``, where
+field names only need to be unique within the struct, while accessors are unique
+within the module.  We thus modify the class constructor and ``insert`` method
+to support this; providing one scope that is local to the struct
+(``local_scope``) and one which is shared across the whole module
+(``global_scope``).
+
+.. literalinclude:: /code_examples/functional/rosette.diff
+   :language: diff
+   :caption: diff of struct constructor
+   :start-at: -  SmtStruct(std::string name, SmtScope &scope)
+   :end-before: void write_definition
+
+For writing outputs/next state (the ``write_value`` method), the only change is
+to remove the check for zero-argument constructors since this is not necessary
+with Rosette ``struct``\ s.
 
 .. literalinclude:: /code_examples/functional/rosette.diff
    :language: diff
@@ -260,11 +271,25 @@ Struct
 PrintVisitor
 ~~~~~~~~~~~~
 
-- map FunctionalIR operations to Rosette
+The ``PrintVisitor`` implements the abstract ``Functional::AbstractVisitor``
-   - most functions are the same or very similar to their corresponding smtlib
+class for converting FunctionalIR functions into s-expressions, including
-     function
+reading inputs/current state.  For most functions, the Rosette output is very
+similar to the corresponding SMT-LIB function with minor adjustments for syntax.
 
-- reading inputs/current state
+.. literalinclude:: /code_examples/functional/rosette.diff
+   :language: diff
+   :caption: portion of ``Functional::AbstractVisitor`` implementation diff showing similarities
+   :start-at: SExpr zero_extend
+   :end-at: SExpr sub
+
+However there are some differences in the two formats with regards to how
+booleans are handled, with Rosette providing built-in functions for conversion.
+
+.. literalinclude:: /code_examples/functional/rosette.diff
+   :language: diff
+   :caption: portion of ``Functional::AbstractVisitor`` implementation diff showing differences
+   :start-at: SExpr from_bool
+   :end-before: SExpr extract
 
 Module
 ~~~~~~