Functions are subprograms in VHDL which can be used for implementing frequently used algorithms. A function takes zero or more input values, and it always returns a value. In addition to the return value, what sets a function apart from a procedure, is that it cannot contain Wait-statements. This means that functions always consume zero simulation time.
If you are familiar with functions or methods from other programming languages, VHDL functions should be easy to grasp. In VHDL we cannot omit the return value or return void, a function always has to return something and the return value has to be assigned to something.
This blog post is part of the Basic VHDL Tutorials series.
In VHDL, there are two types of functions, pure and impure functions. That a function is pure means that it will not be allowed to modify or read any external signal. We can be certain that when we call a pure function with certain arguments, it will always return the same value. We say that the function doesn’t have any side effects.
The syntax for declaring a function in VHDL is:
[pure|impure] function <function_name> (<parameter1_name> : <parameter1_type> := <default_value>;
<parameter2_name> : <parameter2_type> := <default_value>;
... ) return <return_type> is
<constant_or_variable_declaration>
begin
<code_performed_by_the_function>
return <value>
end function;
The pure/impure keyword is optional, although it will default to pure if the keyword is omitted. All parameters are treated as constants inside of the function. Thus, they cannot be changed. The default values are optional, and the function must always terminate at a return
statement.
Functions have their own declarative region between the is
and begin
keywords. Constants, signals or variables declared here are valid only within the function itself, and they will not retain their values through subsequent calls to the function.
Exercise
In this tutorial, we are going to focus on the pure function, impure functions will be covered in a later tutorial in this series.
In the previous tutorial, we created a traffic lights controller module using a finite-state machine (FSM). We copy-pasted many of the lines containing timer calculations from one state to another, only changing one constant slightly.
Find out how you can simplify the state machine code by using a function:
The final code for the function testbench:
library ieee; use ieee.std_logic_1164.all; use ieee.numeric_std.all; entity T21_FunctionTb is end entity; architecture sim of T21_FunctionTb is -- We are using a low clock frequency to speed up the simulation constant ClockFrequencyHz : integer := 100; -- 100 Hz constant ClockPeriod : time := 1000 ms / ClockFrequencyHz; signal Clk : std_logic := '1'; signal nRst : std_logic := '0'; signal NorthRed : std_logic; signal NorthYellow : std_logic; signal NorthGreen : std_logic; signal WestRed : std_logic; signal WestYellow : std_logic; signal WestGreen : std_logic; begin -- The Device Under Test (DUT) i_TrafficLights : entity work.T21_TrafficLights(rtl) generic map(ClockFrequencyHz => ClockFrequencyHz) port map ( Clk => Clk, nRst => nRst, NorthRed => NorthRed, NorthYellow => NorthYellow, NorthGreen => NorthGreen, WestRed => WestRed, WestYellow => WestYellow, WestGreen => WestGreen); -- Process for generating clock Clk <= not Clk after ClockPeriod / 2; -- Testbench sequence process is begin wait until rising_edge(Clk); wait until rising_edge(Clk); -- Take the DUT out of reset nRst <= '1'; wait; end process; end architecture;
The final code for the traffic lights module:
library ieee; use ieee.std_logic_1164.all; use ieee.numeric_std.all; entity T21_TrafficLights is generic(ClockFrequencyHz : natural); port( Clk : in std_logic; nRst : in std_logic; -- Negative reset NorthRed : out std_logic; NorthYellow : out std_logic; NorthGreen : out std_logic; WestRed : out std_logic; WestYellow : out std_logic; WestGreen : out std_logic); end entity; architecture rtl of T21_TrafficLights is -- Enumerated type declaration and state signal declaration type t_State is (NorthNext, StartNorth, North, StopNorth, WestNext, StartWest, West, StopWest); signal State : t_State; -- Calculate the number of clock cycles in minutes/seconds function CounterVal(Minutes : integer := 0; Seconds : integer := 0) return integer is variable TotalSeconds : integer; begin TotalSeconds := Seconds + Minutes * 60; return TotalSeconds * ClockFrequencyHz -1; end function; -- Counter for counting clock periods, 1 minute max signal Counter : integer range 0 to CounterVal(Minutes => 1) +1; begin process(Clk) is begin if rising_edge(Clk) then if nRst = '0' then -- Reset values NorthRed <= '1'; NorthYellow <= '0'; NorthGreen <= '0'; WestRed <= '1'; WestYellow <= '0'; WestGreen <= '0'; State <= NorthNext; Counter <= 0; else -- Default values NorthRed <= '0'; NorthYellow <= '0'; NorthGreen <= '0'; WestRed <= '0'; WestYellow <= '0'; WestGreen <= '0'; Counter <= Counter + 1; case State is -- Red light in all directions when NorthNext => NorthRed <= '1'; WestRed <= '1'; -- If 5 seconds have passed if Counter = CounterVal(Seconds => 5) then Counter <= 0; State <= StartNorth; end if; -- Yellow light in north/south directions when StartNorth => NorthRed <= '1'; NorthYellow <= '1'; WestRed <= '1'; -- If 5 seconds have passed if Counter = CounterVal(Seconds => 5) then Counter <= 0; State <= North; end if; -- Green light in north/south directions when North => NorthGreen <= '1'; WestRed <= '1'; -- If 1 minute has passed if Counter = CounterVal(Minutes => 1) then Counter <= 0; State <= StopNorth; end if; -- Red and yellow light in north/south direction when StopNorth => NorthYellow <= '1'; WestRed <= '1'; -- If 5 seconds have passed if Counter = CounterVal(Seconds => 5) then Counter <= 0; State <= WestNext; end if; -- Red light in all directions when WestNext => NorthRed <= '1'; WestRed <= '1'; -- If 5 seconds have passedf if Counter = CounterVal(Seconds => 5) then Counter <= 0; State <= StartWest; end if; -- Yellow light in west/east direction when StartWest => NorthRed <= '1'; WestRed <= '1'; WestYellow <= '1'; -- If 5 seconds have passed if Counter = CounterVal(Seconds => 5) then Counter <= 0; State <= West; end if; -- Green light in west/east direction when West => NorthRed <= '1'; WestGreen <= '1'; -- If 1 minute has passed if Counter = CounterVal(Minutes => 1) then Counter <= 0; State <= StopWest; end if; -- Red and yellow light in west/east direction when StopWest => NorthRed <= '1'; WestYellow <= '1'; -- If 5 seconds have passed if Counter = CounterVal(Seconds => 5) then Counter <= 0; State <= NorthNext; end if; end case; end if; end if; end process; end architecture;
The waveform after we entered the run 5 min
command in the ModelSim console:
The waveform with cursors added at the transitions to and from the StartNorth
state:
Analysis
We replaced the timer calculations from the previous tutorial if Counter = ClockFrequencyHz * 5 -1 then
with a call to the new CounterVal
function we created: if Counter = CounterVal(Seconds => 5) then
.
We can see from the first waveform screenshot that the module’s function is unchanged. Using functions for repetitive tasks is good design practice. Especially if you can replace calculations with more readable lines containing terms like Minutes
and Seconds
.
Another advantage of using functions is that we can change the implementation of all the timers at once, instead of doing it line by line. For example, if we had written return TotalSeconds * ClockFrequencyHz;
in the CounterVal
function, all the timers would have lasted one clock cycle too long. We could then change this to return TotalSeconds * ClockFrequencyHz -1;
in the CounterVal
function, and all the timers would be fixed at once.
If we examine the last waveform screenshot, we can see why we need to subtract 1 from the timer value that is returned from the CounterVal
function. This waveform examines the duration of the StartNorth
state, it should last for exactly five seconds. When the State
signal changes to StartNorth
, the Counter
value is 0, and it only changes after the next clock cycle. So, if we had counted up to 500 clock cycles, the StartNorth
state would have actually lasted for 501 cycles. With our testbench running at 100 Hz, 500 clock cycles is exactly five seconds.
Takeaway
- Functions can take zero or more parameters, but they always return a value
- Functions cannot contain
wait
statements - Pure functions cannot have side effects, while impure functions can.
Hi, You have nice tutorials. I have one question on functions.
Can we put process in a function. Generally I observed that its only arithmetic operations in the function. Below is my code using a process( ) in function.
But the synthesizer throws errors
Hello, Ravi. No, you can’t have a process inside of a subprogram like a function. Furthermore, functions can’t contain WAIT statements (rising_edge is a shorthand notation containing a WAIT statement).
You can use a procedure to create a reusable process, which is what I think you are trying to do. In the listing below I have modified (but not tested) your example code.
You can then call
edg_detect
multiple times to operate on different signals in your architecture.But if you only want to operate on one set of signals, it’s straightforward to just use a regular process.
Just a small note, Jonas. Near the end of the blog post, you have…
“Functions have their own declarative region between the in and begin keywords.”
I think that should be “between the *is* and begin keywords”.
Love the tutorials. The veil is lifting and I’m starting to see the light! 🙂
Thanks, Larry. I’ve fixed the typo now.
By the way, I plan on running all of these older articles through the new spellchecker that I’m using. I have created the task, but I’ve yet to find the time. 😅
Hi,
I’m new to VHDL and learn a lot from your tutorials. Thank you!
Is there any way to watch function variable, in this example TotalSeconds, in the Modelsim waveform? I tried method you’ve described in your tutorial “Using Variables for Registers or Memory in VHDL” but it looks like it doesn’t work for functions. In my version of Modelsim (it’s FPGA Lattice edition) functions just don’t appear anywhere in the GUI so there is nothing to click at. Or perhaps I’m doing something wrong. If you’re aware of any solution, please advise. Thank you!
You can set a breakpoint in the function. When the simulation pauses on it you should be able to hover the mouse over the variable to see its value.