User HDL

Introduction link

Principle of Operation link

User HDL lets you drop a hand-written VHDL entity straight into a schematic. You do three things:

1. Type (or paste) one VHDL file into the built-in editor.
2. Name the entity in that file — the Main Entity Name.
3. Declare that entity’s ports, one row per port, in the table next to the editor.

The block then draws itself: one pin per declared port, input pins on the left, output pins on the right. At compile time the code is written out into the project’s pcores folder and instantiated, with your pins connected to the ports of the same name.

The code lives inside the project file (base64-encoded in a property), so a project is self-contained: no external folder to keep in step.

Relationship to Custom HDL (NEW) link

This block predates Custom HDL (NEW) (Custom HDL (NEW), version 2.0.0.0) and both are still registered and shipped in the same plugin. Nothing was removed and nothing was deprecated in code: a design that uses User HDL keeps compiling exactly as before.

That said, the newer block is a strict superset for anything new, and the differences are not cosmetic:

Which one to use: for a new design, use Custom HDL (NEW). Reach for User HDL only when you are maintaining an existing block, or when you want the simplest possible thing: one small entity, no generics, no sub-components. There is no automatic converter — migrating means creating a new block and re-entering the code and the port table.

If you would rather keep the HDL in files on disk, under your own version control, use User HDL Link instead: same idea, but the sources stay in an external folder.

Pin Description link

Properties link

⚙️ Detailed Operation link

The editor link

Double-click the block to open the HDL editor. It has three parts:

• a Scintilla code editor with VHDL syntax colouring;
• a Main Entity Name box and a Code Language selector (VHDL / Verilog);
• the port table, with Add / Delete buttons.

Editor shortcuts:

A convenience worth knowing: on save, every occurrence of the literal token <NAME> in your code is replaced by the text in the Main Entity Name box. Writing entity <NAME> is … end <NAME>; means you only have to rename the block in one place.

Saving is refused, with You must define an entity as TOP, if the Main Entity Name box is empty.

The port table link

One row per port of your entity. The columns map one-to-one onto what the compiler does:

A new row is created as Port / PORT1 / 32 / IN / STD_LOGIC_VECTOR / not any-size / TM 0 / no default.

Function decides what happens when a pin is left unconnected on the schematic:

• Port — the pin is tied to the Default Value you typed.
• Clock — the pin is tied to the project’s acquisition clock.
• Reset — the pin is tied to the project’s global reset.

Clock and Reset ports must be STD_LOGIC, or STD_LOGIC_VECTOR of size 1. Anything else is a compile error (see the message table below).

Time-multiplexed ports. A port declared STD_LOGIC_VECTOR_TM with a TM factor of k appears on the symbol as a TM pin, but is instantiated as a plain STD_LOGIC_VECTOR of Port Size × k bits. Your entity must declare it that way: the TM packing is a schematic-level convention, the block passes the flat vector.

Any Size. Ticking it makes the pin adopt the width of the net it is connected to. Your entity still has to be able to take that width — there are no generics in this block, so in practice this is only useful for a port whose width you already know matches.

What the compiler does link

For a block with designator U12, component name UserHDL and Main Entity Name my_filter, the compiler:

1. Base64-decodes your file (as ASCII).

2. Collapses every run of two or more spaces into one. This normalised text is both what the parser searches and, importantly, what is written to disk — so aligned columns in your source come out squashed in the generated file. Tabs and newlines are untouched.

3. Checks that all three of the following appear, case-insensitively:

     entity my_filter is
   end my_filter;          (or  end my_filter ;)
   of my_filter is
     

4. Renames all three to the unique name U12_UserHDL_my_filter, so two copies of the same block in one design do not collide.

5. Writes pcores/U12_UserHDL_my_filter.vhd.

6. Emits the instantiation, connecting each declared port to its pin (or to the default / clock / reset if the pin is open).

Compiler messages link

Example link

A small counter, written so that the <NAME> trick does the renaming:

  library IEEE;
use IEEE.STD_LOGIC_1164.ALL;
use IEEE.NUMERIC_STD.ALL;

entity <NAME> is
    Port (
        CLK    : in  STD_LOGIC;
        RESET  : in  STD_LOGIC;
        ENABLE : in  STD_LOGIC_VECTOR(0 downto 0);
        COUNT  : out STD_LOGIC_VECTOR(15 downto 0)
    );
end <NAME>;

architecture Behavioral of <NAME> is
    signal cnt : unsigned(15 downto 0) := (others => '0');
begin
    process(CLK)
    begin
        if rising_edge(CLK) then
            if RESET = '1' then
                cnt <= (others => '0');
            elsif ENABLE(0) = '1' then
                cnt <= cnt + 1;
            end if;
        end if;
    end process;

    COUNT <= std_logic_vector(cnt);
end Behavioral;
  

The matching port table:

With CLK and RESET marked as Clock and Reset, those two pins can simply be left open on the schematic and they will pick up the project clock and reset.

Where it can be used link

The block is available on every board, on subpages, and inside state machines. It owns no endpoint and no registers: it is pure logic, invisible to software.

Quick reference link

Resources & Timing link

• The block adds no logic of its own: resource usage is exactly that of the entity you wrote, plus any width adaptation the schematic wiring needs.
• The source is written to pcores/ on every compile, so editing the block is enough — there is nothing to copy by hand.
• The generated file is the whitespace-normalised copy of your code (runs of two or more spaces collapsed to one), not a byte-for-byte copy.
• No endpoint, no registers, no SDK output.