Fork me on GitHub

pixhdl

A command-line tool that produces graphical representations of entities from VHDL source files.

Generate entity diagrams effortlessly, whether you're working with simple entities...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;


entity ALU is
    port (
        OP : in std_logic_vector (1 downto 0);
        A, B : in std_logic_vector (31 downto 0);
        O : out std_logic_vector (31 downto 0);
        N : out std_logic
    );
end entity;

...
ALU diagram 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;


entity ALU is
    port (
        OP : in std_logic_vector (1 downto 0);
        A, B : in std_logic_vector (31 downto 0);
        O : out std_logic_vector (31 downto 0);
        N : out std_logic
    );
end entity;

...
ALU diagram

... or more abstract, generic ones:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;


entity MUX is
    generic (
        N : integer range 0 to 32;
        M : time 0.2 ns
    );

    port (
        A, B : in std_logic_vector (N - 1 downto 0);
        COM : in std_logic;
        Y : out std_logic_vector (N - 1 downto 0);
        F : inout std_logic_vector (10 downto 0)
    );
end entity;

...
MUX diagram 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;


entity MUX is
    generic (
        N : integer range 0 to 32;
        M : time 0.2 ns
    );

    port (
        A, B : in std_logic_vector (N - 1 downto 0);
        COM : in std_logic;
        Y : out std_logic_vector (N - 1 downto 0);
        F : inout std_logic_vector (10 downto 0)
    );
end entity;

...
MUX diagram

Getting started

To get started, first of all you have to install pixhdl. After downloading the latest release you can install it as so:

$ tar xvzf pixhdl-X.Y.Z.tar.gz # for example pixhdl-1.1.1.tar.gz
$ cd pixhdl-X.Y.Z/
$ make
$ sudo make install
$ cd ..
$ rm -rf pixhdl-X.Y.Z/

After having successfully installed pixhdl, you can now use it from anywhere on your computer. Say for example that you want to extract the entity diagram from a file called CPU.vhdl, all you have to do is:

$ pixhdl CPU.vhdl CPU_diagram.svg

This will produce a file called CPU_diagram.svg that will contain an image of the diagram of the CPU entity.

You can also specify the output explicitly by using the -o or --output options:

$ pixhdl --output CPU_diagram.svg CPU.vhdl

This will produce the exact same result as before.

If you want, you can also choose to print the entity’s signals in the terminal. By adding the -p or --print options, you don’t have to specify an output file (SVG generation is optional). Here is some example output of the print option:

$ pixhdl -p ALU.vhdl
---------------------------------------------------------------
| Entity ALU                                                  |
---------------------------------------------------------------
Signal # | Name | Value (generics) / Length (bits) | Direction
===============================================================
---------------------------------------------------------------
1        | OP   | 2                                | IN
2        | A    | 32                               | IN
3        | B    | 32                               | IN
---------------------------------------------------------------
1        | O    | 32                               | OUT
2        | N    | 1                                | OUT
---------------------------------------------------------------

If you also specify an output file (either implicitly or explicitly, by adding either one of the output options), an SVG output file will be generated as well.

There is also the possibility of specifying a clock input. Many entities are (partially or fully) synchronous, so they accept a clock input. In order to simplify the entity diagram, there is a norm that dictates that the clock signal can be replaced by a small triangle on the bottom left of the entity rectangle. So if you have, for example, an entity with a clock input called CLK, you can do:

$ pixhdl myEntity.vhdl myEntityDiagram.svg --clock-name CLK

And that will draw that triangle for you, instead of the traditional input signal with an arrow.

If you want to check for updates, you can use the -u or --update options:

$ pixhdl --update

If a newer version is available, you will be asked if you want to install it. You must then type ‘yes’ to accept the installation or ‘no’ to abort it.

To get a more comprehensive list of commands, run:

$ pixhdl -h

About

Pixhdl is a command-line tool that takes VHDL source code as input and produces SVG images as output. It is open source, and it is written entirely in C by Dimitri Kokkonis (@kokkonisd).