Edited the Utils Readme to include information pertaining the the SMR…

…Tool microprogram assembler.

Utils/README.md

@@ -6,11 +6,20 @@ All Rights Reserved.
 
 Released under LGPL.
 
-General Description
--------------------
+Directory Contents
+------------------
 
-This subdirectory provides a utility to convert binary assembler output files into
-ASCII hexadecimal memory initialization files as required by Xilinx ISE. 
+This subdirectory provides two utilities to support the M65C02 Microprogrammed
+Processor Core:
+
+    (1) Bin2Txt.exe
+    (2) [b]SMRTool[/b].exe
+
+Bin2Txt.exe
+===========
+
+Bin2Txt.exe convert binary assembler output files from the Kingswood A65 6502 Assembler
+into ASCII hexadecimal memory initialization files as required by Xilinx ISE. 
 
 Usage
 -----
@@ -41,4 +50,149 @@ utility will print out a prompt to the user that defines the needed arguments.
 Status
 ------
 
-Design and verification is complete.
+Design and verification is complete.
+
+[b]SMRTool[/b].exe
+===========
+
+[b]SMRTool[/b].exe is a tool used to convert text source files into VHDL, Verilog,
+or Xilinx memory intialization files. The source files can be used to construct
+simple ROM for a number of usefull purposes. It's particular use in the M65C02
+Microprogrammed Processor Core is to convert the microprogram source files provided
+into two memory initialization files which are loaded into the fixed and variable
+microprogram ROMs.
+
+Usage
+-----
+
+The primary use for [b]SMRTool[/b] is as a tool to convert human-readable microprogrammed
+state machine descriptions into synthesizable VHDL and/or Verilog RTL descriptions
+of ROMs. [b]SMRTool[/b] also provides memory initialization files, and this is
+its primary method of usage for the MAM65C02 Microprogrammed Processor Core.
+
+[b]SMRTool[/b] is a Windows-based tool which provides the user graphical user interface
+specify the input source file, and check boxes and text boxes to select various
+output options and files. It is written in C#, and requires the .NET framework to
+run. 
+
+In the final analysis, [b]SMRTool[/b] is a text substitution tool. As such, it has
+a number of limitations, but it is invaluable for its intended purpose. Extensions
+are being continually added to the tool as additional functionality is required
+to support more complex state machines, and to improve the simulation and testing
+of the state machines in VHDL/Verilog or SystemVerilog verification environment.
+
+Documentation
+-------------
+
+A complete description of the tool is not available. The source files provided in
+the sources subdirectory, M65C02_Decode_ROM.txt and M65C02_uPgm_V3.txt, provide
+an example of the format and syntax that is required by [b]SMRTool[/b]. This section
+will provide additional information about the structure and syntax, but the source
+files provided are the definitive syntax references for the tool; they make use 
+of all of the current directives and features of [b]SMRTool[/b].
+
+First and foremost, [b]SMRTool[/b] is a text substitution tool. No provision is
+made for in-line symbolic equations in the publicly released version of the tool
+provided herein.
+
+Each source file must start with a header. The header is marked by the symbol
+b]header[/b] in column 1 of the first line of the source file, and demarcated by
+the symbol [b]endh[/b]. Within the header, the tool presently recognizes four fields.
+Each header field is terminated by a colon, [b]:[/b], and followed by a string
+which the tool extracts and places into the appropriate GUI text boxes. The currently
+recognized header fields are:
+
+    (1) Project
+    (2) File Revision
+    (3) Author(s)
+    (4) Description
+
+Comments may be used, and are introduced using the VHDL comment symbol [b]--[/b],
+a double hyphen. The comment extents from that point to the end of the line. Presently
+there is no support for multi-line block comments such as is avaiable in Verilog
+and C.
+
+Following the header section, the source file must define all substitution symbols.
+Owing to its intended design and implementation as a microprogram source file processor,
+there are several directives recognized by [b]SMRTool[/b] to aid in this process. 
+
+Each line in the file may be blank, a comment line, or contain symbols to be processed.
+Each source line is divided into at least one or more fields.  With the exception
+of the first and second fields on a source line, fields are separated by commas. 
+[b]Each field is specified to have a constant width, and the values assigned to
+the symbols must be defined to fit into the specified width.[/b] Each field is
+positionally located in a line of source.
+
+On a line of source, fields may be skipped, and the default value is inserted by
+[b]SMRTool[/b], using consecutive commas. From the second field on a line to the
+end, or to a comment, there is no need to include the commas to skip the unused
+fields. The tool will automatically substitute the default value for all skipped
+fields. The default value of a field is zero. A limitation of the present tool is
+that the default value can not be changed.
+
+The current implementation of the tool recognizes the following directives:
+
+    (1) .asm
+    (2) .def
+    (3) .equ
+    (4) .org
+
+
+The [b[.asm[/b] directive defines the microprogram controller's instructions.
+Unless a label (described below) is used at the start of a source line, a symbol
+defined by the [b[.asm[/b] directive must be the first symbol on a source line.
+
+The [b].def[/b] defines the width of each field in the source file. The first
+field defined by a [b].def[/b] directive will be the leftmost field in the output,
+followed by the second field, etc. The sum of all of the widths of all defined fields
+is the total width of the data written to the tool's output. There is no limit to
+the total field width, but with respect to to Block RAMs in Xilinx FPGAs, in particular,
+the maximum practical width of a ROM is 36 or 72 bits.
+
+The [b].equ[/b] directive is used to define all other text substitution symbols
+beyond those defined by the [b].asm[/b] directive. [b]A limitation of the present
+implementation is that all symbols must be unique.[/b] 
+
+The [b].org[/b] directive defines the location counter address of all source lines
+which follow the directive. If multiple [b].org[/b] directives are used in a source
+file, then the intervening locations are automatically filled by the tool with zeros.
+[b]In the present implementation there is a limitation that all [b].org[/b] directives
+be increasing in magnitude. If an [b].org[/b] is placed in the source with a lesser
+value than one already used, the location counter is assigned the new value, and
+the previously defined values may be overwritten by any new output lines.[/b]
+
+[b]Labels[/b] are used to define the symbols to which the [b].asm[/b] and [b].equ[/b]
+directives assigns values, or labels may used to capture the value of the location
+counter to a symbol. When labels are used to capture the location counter value,
+the labels must always start with an underscore character, "_". All labels in a
+source file must be unique, and all labels capturing the value of the location counter
+must be terminated by a colon. Location counter labels, terminated by a colon, may
+appear on a source line before a [b].org[/b] directive, or one of the [b].asm[/b]
+symbols.
+
+The current value of the location counter is the special symbol: [b]$[/b] or dollar
+sign.
+
+[b]The last line of the source file must be labeled "_end" terminated by colon.[/b]
+
+Extensions
+----------
+
+At the present time, there are no plans to port the tool to C/C++ and Linux.
+If there is sufficient interest expressed in such a conversion, then consideration
+will be given to that task.
+
+Status
+------
+
+Mature. [b]SMRTool[/b] is in continous usage for a number of FPGA designs, and being
+actively maintained.
+
+Error Reports
+-------------
+
+If there are any problems found, please open a [b]GitHub[/b] issue. Each reported
+issue with [b]SMRTool[/b] will be evaluated. In order to evaluate a problem report,
+a description of the problem and the relevant sources are required. Without both
+of these components of a problem report, the likelihood of any significant investigation
+into a reported problem is a low probability.