Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

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

…Tool microprogram assembler.
  • Loading branch information...
commit b525d6c12ebec81543e21a9ec821c6b7c7296acf 1 parent 66a3b33
@MorrisMA authored
Showing with 159 additions and 5 deletions.
  1. +159 −5 Utils/README.md
  2. BIN  Utils/SMRT_tool.zip
View
164 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.
View
BIN  Utils/SMRT_tool.zip
Binary file not shown
Please sign in to comment.
Something went wrong with that request. Please try again.