.. _Diagrams:

Diagrams
========

Specador has the ability to automatically generate diagrams after the compilation is done.

.. tip::
    Diagrams can be zoomed, panned or opened in full screen for better inspection.
    Click on a class or block to jump to the chapter where it is documented.

.. list-table::
    :widths: 20 40 40
    :header-rows: 1

    *   - Type
        - Diagram
        - Observations
    *   - Block Diagram
        - .. image:: ../../images/specador_block_diagram.svg
            :align: center
        - | Presents all the ports and parameters, highlighting busses and clocks
    *   - Flow Diagram
        - .. image:: ../../images/specador_flow_diagram.svg
            :align: center
        - | Presents a high level view of internal connectivity. Multiple connections from one instance to another are collapsed in a single directional edge
    *   - Schematic Diagram
        - .. image:: ../../images/specador_schematic_diagram.png
            :align: center
        - | Presents the internal structure (ports, sub-instances, combinational and sequential logic and connections)
    *   - Sub-Instances Diagram
        - .. image:: ../../images/specador_subinstances_diagram.png
            :align: center
        - | Presents the internal structure without combinational and sequential logic
    *   - Finite State Machine Diagram
        - .. image:: ../../images/specador_fsm_diagram.svg
            :align: center
        - | Presents states and transitions by analyzing all the assignments and conditions in which a state variable is used
    *   - WaveDrom Diagram
        - .. image:: ../../images/specador_wavedrom_diagram.svg
            :align: center
        - | `WaveDrom <https://wavedrom.com/>`_ is a tool that draws timing diagrams (waveforms) from a simple textual description written in `JSON <https://www.json.org/>`_.
          | To export such diagrams, they must be enclosed between ``@WAVEDROM_START`` and ``@WAVEDROM_END`` pragmas inside comments.

          .. note::
          
            Specador uses WaveDrom **3.5.0**.
    *   - Bit Field Diagram
        - .. image:: ../../images/specador_bitfield_diagram.svg
            :align: center
        - Available for packed data types and UVM registers.

          .. note::

            Diagrams are rendered using the `BitField <https://github.com/drom/bitfield>`_ library.

    *   - UML Inheritance Diagram
        - .. image:: ../../images/specador_inheritance_diagram.svg
        - Presents the inheritance hierarchy including the derived classes and the members of the class
    *   - UML Collaboration Diagram
        - .. image:: ../../images/specador_collaboration_diagram.svg
        - Presents all associations with other classes
    *   - UVM Components Diagram
        - .. image:: ../../images/specador_uvm_test_diagram.svg
            :align: center
        - | UVM Components Diagrams help you inspect and document the structure of a verification environment
    *   - External Generated Diagram
        - .. image:: ../../images/specador_external_diagram.svg
            :align: center
        - In order to generate diagrams using external scripts, the description needs to be enclosed between ``@DVT_DIAGRAM_START`` and ``@DVT_DIAGRAM_END`` pragmas:

          .. code-block:: java

            //  @DVT_DIAGRAM_START
            //      @program my_plant_uml_wrapper.sh
            //      @output_file out/my_wave.svg
            //      @input
            //            @startuml
            //            node foo
            //            foo --> bar          : ∅
            //            foo -[bold]-> bar1   : bold
            //            foo -[dashed]-> bar2 : dashed
            //            foo -[dotted]-> bar3 : dotted
            //            foo -[hidden]-> bar4 : hidden
            //            foo -[plain]-> bar5  : plain
            //            @enduml
            //  @DVT_DIAGRAM_END
            //  The end
            class spi_ctrl_reg_model;
            // ...
            endclass

          Available options when writing custom diagram descriptions: 
  
          ``@program``        
            **MANDATORY** Absolute path to the external diagram generator or the name of the diagram generator to be searched in $PATH (environment variables are supported)
          ``@input_file``
            *OPTIONAL*  The diagram description input, which will be passed to the program. Absolute path or relative to the current source file.
          ``@input``          
            *OPTIONAL*  In the absence of an input file, you can write diagram description inline.
          ``@output_file``    
            *OPTIONAL*  Path to the generated diagram. Absolute path or relative to the current source file. If not specified it will be generated under a temporary directory.
          ``@args``           
            *OPTIONAL*  Additional arguments for the program.
          ``@replace_params`` 
            *OPTIONAL*  Replace module parameters and macros with their default value. Default value: false.
 
          .. important::

            Specador will invoke the generator as follows: *@program @input_file @output_file @args*

          SystemVerilog module parameters and macros default values can also be passed to the input description using the following syntax:

          - \#PARAMETER_NAME
          - \`MACRO_NAME
