HDL-FSM-Editor for VHDL and Verilog

Features:

• HDL-FSM-Editor enables you to implement a digital finite state machine (FSM) in a hardware description language (HDL) such as VHDL or Verilog.
• HDL-FSM-Editor is a graphical state diagram editor with which you can describe a complete FSM.
• HDL-FSM-Editor allows you to implement a FSM in the same way as it is usually described in your project documentation.
• HDL-FSM-Editor is the most simple FSM-Editor: It is very easy to use and avoids unnecessary functional overload.
• HDL-FSM-Editor generates efficient and short HDL-code for simulation and synthesis.
• HDL-FSM-Editor is platform independent, it runs at any platform which supports Python3.
• HDL-FSM-Editor is freeware and open source.

Advantages:

• When using HDL-FSM-Editor you create HDL designs 2 times faster compared to writing them manually in a text editor.
• When using HDL-FSM-Editor you implement less mistakes, as the state diagram provides a clear overview of the functionality of the FSM.
• When using HDL-FSM-Editor you will identify signals which are not read or not written easily, as they are highlighted.
• When using HDL-FSM-Editor your design can also be used as your documentation.
• When using HDL-FSM-Editor your colleagues can easily read, understand and modify the design you originally provided.
• When using HDL-FSM-Editor your HDL-Code will not contain any redundant HDL lines (which are often generated by other tools).
• When using HDL-FSM-Editor you will have immediate access to the generated HDL code inside HDL-FSM-Editor without using another tool.

Prerequisites:

• You must know how an FSM works, but you must not know the difference between a Moore and a Mealy machine (although it is better if you are aware of it).
• You must know a hardware description language such as VHDL or Verilog, as you have to write declarations, conditions and actions by yourself using the selected HDL.
• You must have an HDL-compiler and an HDL-simulator for the verification of your implemented design.

Command-line parameters:

You can use an existent HDL-FSM-Editor project file as command line parameter.

• Parameter "-no_version_check":

  HDL-FSM-Editor will not access the internet to check for a newer version.

• Parameter "-no_message":

  HDL-FSM-Editor will not print a message at start.

• Parameter "-generate_hdl":

  HDL-FSM-Editor will generate HDL for the given file and exit (batch-mode).

---

Control-Tab:

Here you define several items which control the generation of the HDL-design, which are:

• Module name:

  Will be used inside the generated HDL and for the filenames of the generated files.

• Language:

  Here you can select between VHDL, Verilog, System-Verilog.

• Path for generated HDL:

  In this folder you will find the generated HDL-files.

• Number of files:

  This is only relevant for VHDL design, where entity and architecture can be stored in different files.

• Name of asynchronous reset input port:

  The signal name specified here will be used as asynchronous reset signal name.

• Name of clock input port:

  The signal name specified here will be used as clock signal name.

• Compile command:

  Here you specify a system command which runs your HDL-compiler/simulator on the generated HDL-code.

• Edit command:

  Here you specify a system command which runs your favoured editor (by Ctrl+e) when editing any text box.
  For example:
  Windows: notepad++.exe -nosession -multiInst
  Linux : gvim -f

• Working directory:

  When the compile commands run they create some files. These files are stored in the working directory.

---

Interface-Tab:

Here you define the interface of your FSM, this means all inputs, outputs, parameters, libraries.

• When you have selected VHDL:

  There is a dedicated text entry field for package-, generic- and port-declarations.

• When you have selected Verilog:

  There is a dedicated text entry field for parameter- and port-declarations.

• When you have selected System-Verilog:

  There is a dedicated text entry field for parameter- and port-declarations.

---

Internals-Tab:

Here you define the internally used signals of your design.

• When you have selected VHDL:

  There is a text entry field for package-, architecture- (like “type”, “signal”), clocked process variable-, combinatorial process variable- declarations.

• When you have selected Verilog:

  There is a text entry field for internal declarations, clocked process local variable-, combinatorial process local variable- declarations.

• When you have selected System-Verilog:

  There is a text entry field for internal declarations, clocked process local variable-, combinatorial process local variable- declarations.

---

Diagram-Tab:

Here you draw the graphical representation of your FSM.
The following graphical elements are available:

• State:

  You define a state by clicking the “new State” button and placing the state into the diagram.
  You can edit the state name by double clicking it, “Return” ends editing, “Escape” aborts editing.

• State-Action:

  Once you have defined a state you can add a state-action for this state by clicking the right mouse button on the state.
  Then you get a state-action block where you can define actions which will be executed in a combinatorial way, when the FSM is in that state.

• State-Comment:

  Once you have defined a state you can add a comment for this state by clicking the right mouse button on the state.
  Then you get a state-comment window where you can put comments in (without comment characters). The comments will be visible in the generated HDL

• Transition:

  Once you have defined two states you can setup a transition between them by first clicking the “new Transition” button and
  then clicking the start state of the transition and then clicking at the end state of the transition.
  If the FSM is in the start state of the transition, at the next positive clock edge the FSM will jump into the end state of the transition,
  if you do not define any condition for the transition.
  When you have implemented several transitions which leave all the same start state, then you must define the transition priority order:
  By editing the numbers provided in the transition (double-click), you define the priorities (“Return” ends editing, “Escape” aborts editing).
  Priority 1 is the highest priority.

• Condition/Action:

  Once you have defined a transition you can setup a condition and/or an action for that transition by clicking the right mouse button on the transition.
  When you have defined a condition, the transition will only fire, if the condition is fulfilled.
  If you have defined an action, this action will be executed in a clocked way, when the transition fires.

• Connector:

  You can add a connector by clicking the “new Connector” button and placing it into the diagram.
  A connector is used to combine different transitions at their way from start state to end state.
  So conditions and actions along each possible path from a start state are executed at a single clock edge.

• Reset Entry:

  You can add exactly 1 reset entry to the diagram by clicking “Reset Entry” and placing it into the diagram.
  By connecting the reset entry element with a transition to a state, you define what happens when the reset input signal gets active.
  Which polarity of the reset input signal is the active polarity, is defined by the condition of this transition.
  In the action block of the transition you define which signals of the design are asynchronously reset to which value.

• Default State Actions:

  As state actions are combinatorial actions (without any storing flipflops),
  for each state all combinatorial state action signals must be assigned a value.
  This is sometime annoying and can be avoided, by inserting a default state action.
  There you define a default value for each state action signal and then you only need to define a state action,
  when a state action signal shall not have its default value.

• Global Actions Clocked:

  Often some clocked logic is needed, which does not depend on the active state of the FSM.
  For example, if you assign a default value to a signal in the global action clocked block,
  which is executed “before” the state machine, then you must specify in the transition actions
  only assignments to the signal, when the signal shall not have the default value.
  If you put an action into the global action block, which is executed “after” the state machine,
  you can for example “override” the signal changes which are provided by the FSM.

• Global Actions Combinatorial:

  Often some combinatorial logic is needed, which does not depend on the active state of the FSM.
  This logic must be put it into this action block.
  Hint: As the code of this block is not a part of the FSM, you can enter any legal HDL code.

The following editing actions are available:

• Using the right mouse button you can define a rectangle which defines the visible area in your editor window.
• Using “view area” you can define a rectangle which defines the visible area in your editor window.
• Using “view all” shows the complete diagram in your editor window.
• Using “+” or “-“ zooms in or out. Zooming center is the middle of your editor window.
• Using mouse wheel up or down you can scroll.
• Using “Ctrl” plus mouse wheel (up or down) zooms in or out.
• Using "Ctrl" plus holding the left mouse button, allows moving the visible area.
• Using "Ctrl+e" in a text box loads the text into your editor. After exiting your text editor the edited text is copied into the text box.
• “Undo” and “Redo” buttons are available. You can also use the shortcuts “Ctrl+z” and “Ctrl+Z”.
• A "File" menu for reading and writing files is available (shortcuts are implemented).
• A "HDL" menu for generating HDL and executing the compile-command is available (shortcuts are implemented).

---

Generated HDL-Tab:

Here the generated HDL files are displayed for reading.

Each generation replaces the old code with the new code.

The generated HDL can be loaded into an editor by "Ctrl-e".

When a code line is linked to the graph in the "Diagram-Tab", then the code line will be underlined, when the mouse pointer is at it.

To follow the link the user must press the left mouse button together with the Ctrl-key.

The diagram element which represents the code line will then be shown and highlighted.

---

Compile Messages Tab:

The STDOUT and STDERR messages of the compile command appear in this tab.

• The tab is only cleared at a new start of HDL-FSM-Editor, or when you switch to a new design (using “open” or “new”).
• The messages can be loaded into an editor by "Ctrl-e".
• When a line is linked to the "Generated HDL-Tab" and to the graph in the "Diagram-Tab", the line will be underlined, when the mouse pointer is at it.
• To follow the link to the "Diagram-Tab" the user must press the left mouse button together with the Ctrl-key.
• To follow the link to the "Generated HDL"-tab the user must press the left mouse button together with the Alt-key.
• Per default the links are based on the message format of the "GHDL" VHDL-Compiler or the "iverilog" Verilog-Compiler.
• The message format can be adapted by using the Button "Define Regex for Hyperlinks".

Adapting the regular expression for the links:

• Per default the links for VHDL are based on the messages of the GHDL-VHDL-Compiler which look like: "M:/test.vhd:59:5: < some error message >" .
• Per default the links for Verilog are based on the messages of the iverilog-VHDL-Compiler which look like: "M:/test.v:59: < some error message >" .
• For following the link, the file-name and the line-number must be extracted from this message.
• This is done by a regular expression which encloses the complete line and defines 2 groups.
• One group contains the file-name, the other group contains the linenumber.
• Then, to get the file-name, the complete line is replaced by the group which contains the file-name.
• Then, to get the line-number, the complete line is replaced by the group which contains the line-number.
• In order to adapt the regular expression to another HDL compiler the button "Define Regex for Hyperlinks" must be pressed.
• Then a dialog pops up, where the regular expression for the complete line and the 2 groups can be entered.
• In the 2 additional fields the group for the file-name and the group for the line-number must be specified.
• For the test of a different regular expression please use https://regex101.com.
• A debug mode for the regular expression can be activated, which gives information at STDOUT.

Here you can find links to 5 designs which I have created.
All designs are created by HDL-SCHEM-Editor and HDL-FSM-Editor and most of the designs are based at VHDL (only for division also Verilog is available).
By the link you will find all the needed source-files for both tools and also the generated VHDL/Verilog-files.

1. Cordic module
2. multiplication module
3. Karatsuba multiplication module
4. division module
5. division module at signed numbers
6. SRT division module

---

1. The Cordic module "rotate":

• The module "rotation" can rotate vectors by a given angle (Cordic rotation mode) or to the x-axis (Cordic vectoring mode).

• The module "rotation" can be configured by generics which define the number of bits of all the operands and which define the latency of the module (in clock cycles).

• The module "rotation" can be used to calculate the sine or cosine of an angle.

• The module "rotation" can be used to convert cartesian coordinates into polar coordinates and vice versa.

---

2. The multiplication module "multiply":

• The module "multiply" multiplies signed numbers.

• The module "multiply" can be configured by generics which define the number of bits of all the operands and which define the latency of the module (in clock cycles).

• The module "multiply" has an architecture "struct" which implements the classic written multiplication algorithm.

• The module "multiply" has an architecture "fpga" which uses the VHDL multiplication operator.

---

3. The Karatsuba multiplication module "multiply_karatsuba":

• The module "multiply_karatsuba" multiplies signed numbers.

• The module "multiply_karatsuba" can be configured by generics which define the number of bits of all the operands.

• The module "multiply_karatsuba" has an architecture "struct" which implements the Karatsuba multiplication algorithm.

• The module "multiply_karatsuba" has an architecture "mul_operator" which uses the VHDL multiplication operator.

---

4. The non restoring division module "division":

• The module "division" calculates quotient and remainder from signed dividend and signed divisor.

• The signs are removed before an unsigned division is executed and added afterwards.

• The module "division" is available as VHDL and as Verilog design.

• The module "division" can be configured by generics which define the number of bits of all the operands.

• The module "division" uses a non restoring division algorithm.

---

5. The non restoring division module "division_signed":

• The module "division_signed" calculates quotient and remainder from signed dividend and signed divisor.

• In contrary to the module division the signs are not removed before the division is executed.

• This leads to a quotient which is not coded as binary number with the bit weights 0 or 1,
  but to a number with bit weights +1 or -1. After the division this number is converted into a binary number.

• After the conversion the quotient and the remainder are fixed in some cases.

• The module "division_signed" can be configured by generics which define the number of bits of all the operands.

• The module "division_signed" uses a non restoring division algorithm.

---

6. The SRT division module "division_srt_radix2":

• The module "division_srt_radix2" calculates quotient and remainder from signed dividend and signed divisor.

• The module uses the SRT algorithm to make fast divisions possible even at operands which have a large number of bits.

• As a radix2 SRT algorithm is used the quotient is first not coded as binary number with the bit weights 0 or 1,
  but as a number with bit weights -1, 0 or -1. After the division this number is converted into a binary number.

• The module "division_srt_radix2" can be configured by generics which define the number of bits of all the operands.

License:

HDL-FSM-Editor
Copyright (c) 2024 Matthias Schweikart

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Files:

Python3 source code:
(Start the tool by "python3 hdl_fsm_editor.py" or create an executable with "pyinstaller --onefile hdl_fsm_editor.py")

• Download from this website: hdl-fsm-editor.zip (Number of downloads = 361 ).
  
• Download from GitHub: HDL-FSM-Editor-main.zip (Number of downloads = 49 ).
  
• Download from GitHub: HDL-FSM-Editor-<version>.tar.gz (Number of downloads = 53 ).
  
• See also GitHub project.

Executable for Windows 11:

• hdl_fsm_editor.exe (Number of downloads = 423 )

Executable for Linux (compiled with Linux-Mint):

• hdl_fsm_editor (Number of downloads = 314 )

Small example project:

• count10.hfe

Change log:

Version 4.4 (02.10.2024):

• The background color of the diagram can now be configured in the control tab.
• The color of a state can now be configured by using the right mouse button menu at the state.
• Since version 4.3 a state-name could no longer be changed to the name it had already. Fixed.
• When transition end points were moved from one state to another state, the priority rectangles were not shown or hidden accordingly. Fixed.
• Now also the priority rectangle of the transition from the reset-entry is hidden.
• States and Connectors can no longer be placed on top of each other (caused exceptions sometimes).
• When a design is opened always the diagram is shown, even if HDL is loaded into the "generated HDL" tab.
• A transition which starts at reset entry can no longer be ended at a connector.
• A start-point of a transition can no longer be moved to the reset-entry if there already another transition starts.

Version 4.3 (30.09.2024):

• Inserting a transition can now be aborted by "Escape".
• When a transition had the shape of the letter 'S', then only the end points of the transition could be moved by the mouse pointer. Fixed.
• There is the new menu entry "straighten shape" at the right mouse button menu of a transition which changes the shape of transition to a straight line.
• The priority boxes of outgoing transitions of a state are only shown if the state has more than 1 outgoing transition.
• When a transition is inserted, its priority is automatically set to the highest unused priority
• When a state-name is changed, it is now checked if the new state-name is already used.
• Generics/parameters- and ports-declaration lists are now allowed to have a list separator (;/,) even after the last entry of the list.
• When a hfe-file is read by HDL-FSM-Editor and the generated HDL is younger than the hfe-file, then the generated HDL is copied into the HDL-tab.
• Unread or unwritten signalnames were highlighted red in state comment blocks. Fixed.

Version 4.2 (05.09.2024):

• Adding comments to states in a comment-box is now supported.
• Sometimes the plausibility checks report unnecessarily an unknown tag named "current", which is a legal tag and must be ignored. Fixed.
• Sometimes comments in transition-conditions caused illegal HDL code. Fixed.
• After inserting the reset-entry it is not longer necessary to abort the reset-entry-insertion by Escape.

Version 4.1 (27.08.2024):

• At HDL generation the database is checked for plausibility.
  If any error is found an error-message is shown and the errors are listed at STDOUT.
  Errors could be introduced by program malfunction or by editing manually the hfe-file.
• When a condition-action window was removed, sometimes the connection-line of the window was not removed from the database. Fixed.
• When a connector box had no leaving transition and HDL was generated a Python exception happened. Fixed.

Version 4.0 (14.06.2024):

• Now Links from the HDL-code in the "generated HDL"-tab to the source in the "Diagram"-tab are supported.
• Now Links from the compiler messages in the "Compile Messages"-tab to the "generated HDL"-tab or the source in the "Diagram"-tab are supported.
• Local Variable Declarations for clocked always process were added to the HDL code in a wrong way. Fixed.
• Improved HDL formating when transition conditions are more than 1 line of code.

Version 3.11 (05.05.2024):

• In VHDL-mode the sensitivity list of the p_state_action process sometimes had duplicate entries. Fixed.
• In Verilog-mode the declaration of an integer variable caused an error message at HDL generation. Fixed.
• In Verilog-mode the linting (giving colors to not read or not written signal names) did not always use correct colors. Fixed.
• In Verilog-mode now reg/wire/logic can be declared as "signed" or "unsigned".
• The window title now has another format, so that the design name can be read, when the window is an icon.

Version 3.10 (13.03.2024):

• Loading a design into HDL-FSM-Editor by command line parameter did not work anymore in version 3.9. Fixed.
• Fixed wrong tool-name in the help-text shown by option "-h".
• Added new command-line parameter "-generate_hdl" for batch-mode HDL generation (used in HDL-SCHEM-Editor).

Version 3.9 (07.03.2024):

• The window-title was changed, so that the filename can be read, if the window is an icon.
• The checking of the command line parameters is now done by ArgParse.
• The new command-line switch -no_message was introduced to prevent HDL-FSM-Editor to print a message at start.

Version 3.8 (23.11.2023):

• Now also the Default State Action block can be moved by picking it inside.
• A working directory for the compile commands can now be specified in the control tab.

Version 3.7 (17.11.2023):

• All action blocks could only be moved by touching them near there border. Now they can be touched also inside.
• Connectors were not inserted with the right size after a zoom. Fixed.

Version 3.6 (08.11.2023):

• Using the "Edit command" (Control-e) under Linux did not work. Fixed.

Version 3.5 (23.10.2023):

• At HDL generation correctly defined functions and types caused the warning "There is an illegal signal declaration". Fixed.
• When a generic is read by an assignment it was colored red, as it was never written. Fixed.

Version 3.4 (21.10.2023):

• At HDL generation correctly defined HDL-constants caused the warning "There is an illegal signal declaration". Fixed.
• Constants were highlighted in red as "not written". Fixed.There is an illegal signal declaration

Version 3.3 (18.09.2023):

• Added command line switch "-no_version_check" to forbid HDL-FSM-Editor to access the internet at start.
• Removed a HDL generation crash, which was caused by a transition with no condition using a connector.

Version 3.2 (20.06.2023):

• Fixed uncritical key error (caused only error messages at StdOut) when using the Internals/Packages entry window. Error was introduced in version 2.0

Version 3.1 (19.06.2023):

• In HDL all actions of a transition from a start state to a target state were implemented in the last condition branch of the transition. Now actions which may not have to be executed in this last branch are "moved up" in the branch hierarchy, which leads to shorter and better readable code.

Version 3.0 (30.05.2023):

• A new algorithm for transforming the transition conditions and actions into HDL is now implemented. The old algorithm caused problems when connectors were used excessively.
• HDL-FSM-Editor now gives a hint, when a newer version is available.

Version 2.1 (12.05.2023):

• A Verilog wire declaration added in "Internal Declarations" will not cause an (unimportant) Error message anymore.

Version 2.0 (04.05.2023):

• Now the JSON format is used when a design is saved to a file. The file menu has a new entry for reading the old format of Version 1.
• "view area" can now be also done by the right mouse button.
• When a new design is opened by open-file dialog, the old design is not not removed, when the user aborts the opening.
• When selecting the path for the generated HDL, an abort does not remove the old path entry anymore.
• Now also in any Interface/Internals text field Control-o opens a file-dialog, instead of inserting a new line.
• Fixed loading a design by a command line with "hdl_fsm_editor design-file.hfe". This did not work since version 1.4.
• Deleting empty condition&action- and state-action- windows now works.
• After inserting Default-State-Actions, Global-Actions and Global Actions-Combinatorial the escape key must not be pressed anymore.

Version 1.9 (09.01.2023):

• The error message, which occurs when the reset condition is missing, now gives the user a hint, where the reset condition must be specified.

Version 1.8 (07.01.2023):

• In Verilog-mode now the temporay file (which is created when ctrl+e is used in a textbox) has the extension ".v" instead of ".vhd".
• The time stamp format used in generated HDL and in the "Compile Messages" tab is now better readable.

Version 1.7 (21.12.2022):

• Fixed: main_window.py from version 1.6 had a doubled "," in line 266 instead of a single one.

Version 1.6 (09.12.2022):

• Fixed a bug which showed, when a VHDL port name contains the string "out".
• For text fields now no default font is used anymore (keywords and non-keywords now always use the same font).

Version 1.5 (08.11.2022):

• A change of the path for the generated HDL is now handled as a design change.
• A bug at moving transitions was fixed.
• The print functionality was removed, as each action window is always printed as a black box.

Version 1.4 (25.10.2022):

• Several small bugs were fixed.
• Static code analysis was added: Not read signals appear in "orange", not written signals appear in "red".

Version 1.3 (10.10.2022):

• Bug at highlighting was fixed.
• Find-Button was added.
• When editing text boxes an external editor can be started by Control-e.
• Improvements for moving items in the diagram tab were added.

Version 1.2 (04.10.2022):

• SystemVerilog is now supported.
• Keyword highlighting is supported.
• Verilog: Asynchronous reset is now correct implemented.

Version 1.1 (29.09.2022):

• Verilog is now supported.
• VHDL or Verilog code using upper case characters is now handled correctly.
• When deleting windows from the state diagram, it is now easier to hit the target.
• HDL-Generation: 1 file mode now works.

Version 1.0 (25.09.2022):

• Initial version

If you detect any bugs or have any questions,
please send a mail to "matthias.schweikart@gmx.de".