Adding documentation for generics

doc/.gitignore

@@ -13,3 +13,6 @@
 *.out
 *.pdf
 *.toc
+*.fdb_latexmk
+*.fls
+*.synctex.gz

doc/BH_ref_guide/BH_lang.tex

@@ -117,13 +117,10 @@
 \newcommand{\BSInc}{Bluespec, Inc.}
 
 \newcommand{\BH}{BH}
-\newcommand\BHfull{Bluespec Haskell/Classic}
+\newcommand{\BHFull}{Bluespec Haskell/Classic}
 
-\newcommand{\blue}{Bluespec SystemVerilog}
 \newcommand{\BSVFull}{Bluespec SystemVerilog}
 \newcommand{\BSV}{BSV}
-\newcommand{\BSVVersion}{3.8}
-\newcommand{\BSVvN}{BSV 3.8}
 
 \newcommand{\bsc}{\emph{bsc}}
 
@@ -377,7 +374,7 @@
 
 \section{Introduction}
 
-{\BH} ({\BHfull}) is a language for hardware design.  The language borrows its
+{\BH} ({\BHFull}) is a language for hardware design.  The language borrows its
 notation, type and package system from an existing general-purpose
 functional programming language called Haskell
 {\cite{haskell12}}{\index{Haskell}} where those constructs have been
@@ -664,6 +661,18 @@ \section{Types}
 \end{verbatim}
 represents the type of unsigned integers that can be represented in 32
 bits.
+These numeric types are said to have kind \texttt{\#},
+rather than kind \texttt{*} for value types.
+
+\index{string types}
+Strings can also be used as type, having kind \texttt{\$}.
+This is less common, but string types are quite useful in the generics library,
+described in the \LibRefGuide.
+Examples:
+\begin{verbatim}
+ MetaData#("Prelude","Maybe",PrimUnit,2)
+ MetaConsNamed#("Valid",1,1)
+\end{verbatim}
 
 % ----------------------------------------------------------------
 
@@ -1008,25 +1017,22 @@ \subsection{\te{data}}
 Error messages involving data type definitions sometimes show traces
 of how they are handled internally.  Data type definitions are
 translated into a data type where each constructor has exactly one
-argument.  Each argument is a struct type.  The types above translate
+argument.  The types above translate
 to:
 \begin{verbatim}
  data Bool = False PrimUnit | True PrimUnit
 
- data Operand = Register Operand.Register
-              | Operand.Literal
-              | Operand.Indexed
- struct Operand°Register = { _1 :: Bit 5 }
- struct Operand°Literal = { _1 :: Bit 22 }
- struct Operand°Indexed = { _1 :: Reg 5; _2 :: Reg 5 }
+ data Operand = Register (Bit 5)
+              | Literal (Bit 22)
+              | Indexed Operand_$Indexed
+ struct Operand_$Indexed = { _1 :: Reg 5; _2 :: Reg 5 }
 
- data Maybe a = Nothing PrimUnit | Maybe.Just a
- struct Maybe.Just a = { _1 :: a }
+ data Maybe a = Nothing PrimUnit | Just a
 
- data Instruction = Immediate Instruction°Immediate |
-                    Register Instruction°Register
- struct Instruction°Immediate = { op::Op; rs::Reg; rt::CPUReg; imm::UInt16; }
- struct Instruction°Register = { op::Op; target::UInt26; }
+ data Instruction = Immediate Instruction_$Immediate
+                  | Register Instruction_$Register
+ struct Instruction_$Immediate = { op::Op; rs::Reg; rt::CPUReg; imm::UInt16; }
+ struct Instruction_$Register = { op::Op; target::UInt26; }
 \end{verbatim}
 \end{NOTE}
 
@@ -2720,6 +2726,15 @@ \subsection{The ``size'' types}
 The second line binds {\te{logWPlusOne}} to the integer value
 corresponding to {\te{n}}.
 
+{\index{stringOf@\te{stringOf} (``function'' of string types)}}
+A ``function'' {\te{stringOf}} is also available to get the string value
+of a type-level string.
+\begin{verbatim}
+ type MyString = "Hello, world!"
+ x :: String
+ x = stringOf MyString  -- x will have the value "Hello, world!"
+\end{verbatim}
+
 % ----------------------------------------------------------------
 
 \subsection{The type \te{Bit}}

doc/BH_ref_guide/version.tex

@@ -1,4 +1,4 @@
-\author{Revision: 26 July 2022}
+\author{Revision: 17 February 2024}
 
 \date{
 Copyright {\copyright}

doc/BSV_ref_guide/BSV_lang.tex

@@ -110,16 +110,16 @@
 \newcommand{\LibRefGuide}{\emph{Libraries Reference Guide}}
 \newcommand{\LibRefGuideFullName}{\emph{Bluespec Compiler (BSC) Libraries Reference Guide}}
 
+\newcommand{\BSCUserGuide}{\emph{BSC User Guide}}
+\newcommand{\BSCUserGuideFullName}{\emph{Bluespec Compiler (BSC) User Guide}}
+
 \newcommand{\BS}{Bluespec}
 \newcommand{\BSInc}{Bluespec, Inc.}
 
 \newcommand{\BH}{BH}
 
-\newcommand{\blue}{Bluespec SystemVerilog}
 \newcommand{\BSVFull}{Bluespec SystemVerilog}
 \newcommand{\BSV}{BSV}
-\newcommand{\BSVVersion}{3.8}
-\newcommand{\BSVvN}{BSV 3.8}
 
 \newcommand{\bsc}{\emph{bsc}}
 
@@ -264,7 +264,6 @@
 \resizebox{2in}{!}{\includegraphics[width=\textwidth]{../common/B-Lang}} \\
 \vspace{0.3in}
 {\BS}$^{\rm{TM}}$ {\SV} \\
-%Version {\BSVVersion} \\
 Language Reference Guide \\
 \vspace*{1in}
 \vspace*{1in}
@@ -1528,6 +1527,16 @@ \section{Types}
 bits indexed from $m$ (msb/left) down through 0 (lsb/right), for $m
 \ge 0$.
 
+\index{string types}
+Type parameters can also be strings (known as \emph{string} types).
+These are not common, but are quite useful in the generics library,
+described in the \LibRefGuide.
+Examples:
+\begin{verbatim}
+ MetaData#("Prelude","Maybe",PrimUnit,2)
+ MetaConsNamed#("Valid",1,1)
+\end{verbatim}
+
 % ----------------------------------------------------------------
 
 \subsection{Polymorphism}
@@ -1719,6 +1728,22 @@ \subsubsection{The pseudo-function \te{valueof} (or \te{valueOf})}
 described in Section {\ref{sec-sizeof}}, which converts a type to a
 numeric type.
 
+\subsubsection{The pseudo-function \te{stringof} (or \te{stringOf})}
+
+A function \texttt{stringof} (or \texttt{stringOf})
+\index{stringOf@\texttt{stringOf} (pseudo-function of string types)}
+similar to \te{valueof}
+exists to convert a string type to a string value.
+Example:
+\begin{verbatim}
+ instance CShow'#(Meta#(MetaConsNamed#(name, idx, nfields), a))
+  provisos (CShowSummand#(a));
+    function cshow'(tagged Meta {x});
+      return $format(stringOf(name), " {", cshowSummandNamed(x), "}");
+    endfunction
+ endinstance
+\end{verbatim}
+
 % ----------------------------------------------------------------
 
 \subsection{A brief introduction to \texttt{deriving} clauses}
@@ -1919,7 +1944,7 @@ \subsection{Interface declaration}
 
 \gram{typeFormals}{\term{\#} \term{(} \nterm{typeFormal} \many{ \term{,} \nterm{typeFormal}}\term{)} }}
 
-\gram{typeFormal}{\opt{\term{numeric}}  \term{type} \nterm{typeIde}}  
+\gram{typeFormal}{\opt{\term{numeric} {\alt} \term{string}} \term{type} \nterm{typeIde}}
 
 \gram{interfaceMemberDecl}{ \nterm{methodProto} {\alt} \nterm{subinterfaceDecl} }
 
@@ -3903,7 +3928,7 @@ \subsection{Type synonyms}
 
 \gram{typeFormals}{\term{\#} \term{(} \nterm{typeFormal} \many{ \term{,} \nterm{typeFormal}}\term{)} }}
 
-\gram{typeFormal}{\opt{\term{numeric}}  \term{type} \nterm{typeIde}}  
+\gram{typeFormal}{\opt{\term{numeric} {\alt} \term{string}} \term{type} \nterm{typeIde}}
 
 
 % \gram{typeDefType}{\nterm{typeIde} \opt{\term{\#} \term{(}
@@ -4138,7 +4163,7 @@ \subsection{Structs and tagged unions}
 
 \gram{typeFormals}{\term{\#} \term{(} \nterm{typeFormal} \many{ \term{,} \nterm{typeFormal}}\term{)} }}
 
-\gram{typeFormal}{\opt{\term{numeric}}  \term{type} \nterm{typeIde}}  
+\gram{typeFormal}{\opt{\term{numeric} {\alt} \term{string}} \term{type} \nterm{typeIde}}
 
 
 
@@ -4458,7 +4483,7 @@ \subsection{Type class declarations}
 
 \gram{typeFormals}{\term{\#} \term{(} \nterm{typeFormal} \many{ \term{,} \nterm{typeFormal}}\term{)} }
 
-\gram{typeFormal}{\opt{\term{numeric}}  \term{type} \nterm{typeIde}}  
+\gram{typeFormal}{\opt{\term{numeric} {\alt} \term{string}} \term{type} \nterm{typeIde}}
 
 \gram{typedepends}          {\term{dependencies} \term{(}
                                              \nterm{typedepend} \many
@@ -10008,7 +10033,7 @@ \subsubsection{\te{split} and \te{nosplit}}
 \end{verbatim}
 
 To enable rule splitting for an entire design, use the compiler
-flag \te{-split-if} at compile time.  See the user guide for
+flag \te{-split-if} at compile time.  See the {\BSCUserGuideFullName} for
 more information on compiler flags.  You can enable rule splitting for
 an entire design with the \te{-split-if} flag and then disable the
 effect for specific rules, by specifying the \te{nosplit} attribute
@@ -10975,7 +11000,7 @@ \subsubsection{Rules}
 \end{verbatim}
 The designer can ensure that the signals will exist in the Verilog
 by using an appropriate compiler flag, the \te{-keep-fires} flag which
-is documented in the {\blue} User Guide.
+is documented in the {\BSCUserGuideFullName}.
 
 The \te{doc} attribute can be attached to any \te{rule..endrule} expression,
 such as inside a function or inside a for-loop.

doc/BSV_ref_guide/version.tex

@@ -1,4 +1,4 @@
-\author{Revision: 26 April 2022}
+\author{Revision: 17 February 2024}
 
 \date{
 Copyright {\copyright}

doc/libraries_ref_guide/LibDoc/BGetPut.tex

@@ -16,7 +16,7 @@ \subsubsection{BGetPut}
 \te{Get} and \te{Put}, but the interconnection of them
 (via \te{Connectable} or in {\veri}) is implemented with a simple protocol
 that allows all inputs and outputs to be directly connected.   
-All wires go to registers and have no {\blue} handshaking.
+All the ports are directly registered, without the logic of ready/enable handshaking.
 The protocol makes no assumptions about setup time and hold time for the
 registers at each end;  so these interfaces may be used when the two ends
 have different clocks.