Best Practices

Name: Best Practices
Author: Dangremont Jayson

By Dangremont JaysonAbout the author (in French)

Naming conventions, prefixes, and best practices for readable and maintainable VHDL code.

A consistent name lets you understand a signal's role before finding its declaration. A regular structure also helps locate errors and review code as a team.

Give names a role

Port prefixes indicate direction:

Prefix	VHDL Mode	Meaning	Example
`i_`

Prefix	Meaning	Example
`c_`	Constant	`c_CLK_FREQ`, `c_MAX_COUNT`
`g_`	Generic (entity parameter)	`g_WIDTH`, `g_DEPTH`
`t_`	User-defined type	`t_state`, `t_data_array`
`v_`	Variable (inside a process)	`v_temp`, `v_index`
`P_`	Process (label)	`P_WRITE_FSM`, `P_READ_DATA`
`f_`	Function	`f_log2`, `f_parity`

entity uart_tx is
  generic (
    g_CLK_FREQ  : integer := 100_000_000;  -- g_ for generic
    g_BAUD_RATE : integer := 115_200
  );
  port (
    i_clk   : in  std_logic;               -- i_ input
    i_rst   : in  std_logic;               -- i_ input
    i_data  : in  std_logic_vector(7 downto 0);
    i_valid : in  std_logic;
    o_tx    : out std_logic;               -- o_ output
    o_ready : out std_logic
  );
end entity uart_tx;
 
architecture rtl of uart_tx is
  constant c_BIT_PERIOD : integer := g_CLK_FREQ / g_BAUD_RATE;  -- c_ constant
 
  type t_state is (IDLE, START, DATA, STOP);  -- t_ type
 
  signal r_state   : t_state;                         -- r_ registered
  signal r_counter : integer range 0 to c_BIT_PERIOD; -- r_ registered
  signal r_shift   : std_logic_vector(7 downto 0);    -- r_ registered
  signal w_tx_bit  : std_logic;                       -- w_ combinational
 
  -- f_ for a function
  function f_parity(v_data : std_logic_vector) return std_logic is
    variable v_p : std_logic := '0';
  begin
    for i in v_data'range loop
      v_p := v_p xor v_data(i);
    end loop;
    return v_p;
  end function f_parity;
 
begin
 
  P_TX_FSM : process (i_clk)  -- P_ for processes
  begin
    -- ...
  end process P_TX_FSM;
 
end architecture rtl;

-- VHDL keywords: lowercase
entity, architecture, process, signal, begin, end, if, then, else
 
-- Constants and generics: UPPERCASE or mixed
constant c_MAX_VALUE : integer := 255;
generic (g_DATA_WIDTH : integer := 8);
 
-- Types: t_ + snake_case
type t_uart_state is (IDLE, START, DATA, STOP);
 
-- FSM states: UPPERCASE
type t_state is (IDLE, WAIT_START, SEND_DATA, DONE);

-- BAD : non-descriptive names
signal a, b, c, x : std_logic;
signal temp1, temp2 : unsigned(7 downto 0);
 
-- BAD : mixed styles
signal DATA_OUT : std_logic;    -- inconsistent
signal data_in  : std_logic;
 
-- BAD : no prefix -> impossible to know if it's a register
signal counter  : unsigned(7 downto 0);   -- registered or combinational?
 
-- GOOD : clear prefixes
signal r_counter : unsigned(7 downto 0);  -- clearly a register
signal w_carry   : std_logic;             -- clearly combinational

Prefix	Type	Direction / Nature
`i_`	Port	Input (`in`)
`o_`	Port	Output (`out`)
`io_`	Port	Bidirectional (`inout`)
`w_`	Signal	Combinational (wire)
`r_`	Signal	Registered (flip-flop)
`c_`	Constant	Fixed value
`g_`	Generic	Entity parameter
`t_`	Type	User type
`v_`	Variable	Local process variable
`P_`	Process	Process label
`f_`	Function	VHDL function

Best Practices

Give names a role

Organize files

Review names before delivery

Prefix	Meaning	Example
`w_`	Unregistered signal - wire, combinational	`w_sum`, `w_mux_out`
`r_`	Registered signal - flip-flop, D latch	`r_counter`, `r_data`