Libraries, subprograms,

and packages

Dr. Hakem Beitollahi

Computer Engineering Department

Elmo Sanat University
Outline
 Libraries
 Packages
 Subprograms
 Procedures
 Functions
 Data type conversion

2
Packages & Libraries
 Frequently used pieces of VHDL code are usually
written in the form of COMPONENTS,
FUNCTIONS, or PROCEDURES.
 Such codes are then placed inside a PACKAGE
and compiled into the destination LIBRARY
 A package can be shared across many VHDL
models.
 A package can also contains user defined data
types and constants.
 A library is a collection of related packages.
 Packages and libraries serve as repositories for
functions, procedures, and data types.
3
Packages & Libraries

4
Libraries
 Library is a place to which design units may be
compiled.

 Two predefined libraries are the STD and WORK

libraries.

 WORK and STD: you don’t need to call it.

 IEEE standard library contains the IEEE

standard design units. (e.g. the packages:
std_logic_1164, numeric_std).

5
Libraries (cntd.)
 VHDL knows library only by logical name

 A library is made visible using the library

clause.
 Library ieee;

 In standard VHDL both work and std

libraries are visible

6
Libraries (cntd.)
 LIBRARY std; (do not need to call)
 Contains the following packages

Standard (Types: Bit, Boolean,
Integer, Real, and Time. All operator
functions to support types)

Textio (File operations)

7
Libraries (cntd.)
 LIBRARY ieee; (need to call)
 Contains the following packages:

std_logic_1164 (std_logic types & related
functions)

std_logic_arith (arithmetic functions)

std_logic_signed (signed arithmetic
functions)

std_logic_unsigned (unsigned arithmetic
functions)

8
Libraries (cntd.)
 How to call a library
LIBRARY <any_name>;
USE <any_name>.<package_name>.all;
 Example
LIBRARY ieee;
USE ieee.std_logic_1164.all;

9
Packages

10
Packages
 A VHDL package is simply a way of grouping a collection
of related declarations that serve a common purpose

 Allows data types, subprograms, object declarations

(signal, constants, shared variables and files), component
declarations etc. to be shared by multiple design units.

 Syntax package my_package is

package identifier is type binary is (onn, off);
declarations signal a: std_logic_vector(3 downto 0);
end [package] [identifier]; constant pi : real := 3.14;
 Example function Min1 (X, Y : Integer range 0
to 30) return Integer;
end my_package;

11
Package body
 The package declaration contains only the declarations of the various
items
The package body contains subprogram bodies and other declarations

not intended for use by other VHDL entities

Example

package body my_package is

function Min1 (X, Y : Integer range 0 to 30) return
Integer is
variable temp : integer range 0 to 30;
begin
if (X < Y) then
temp:= X;
else
temp:= Y;
end if;
return temp;
end Min1;
end my_package;
12
Package
 How to use?
 A package is made visible using the use
clause.
use work.my_package.binary, my_package.Min;
... entity declaration ...
... architecture declaration ...

use the binary and Min declarations only

use work.my_package.all;
... entity declaration ...
... architecture declaration ...

use all of the declarations in package my_package

13
Subprograms

14
Subprograms
 Subprograms are of two types :
functions and procedures

 A subprogram consists of a sequence of

declarations and statements which can be
repeated from different locations in VHDL
descriptions

 A subprogram can be separated into its

subprogram declaration and subprogram body

15
Subprograms
 Full form of subprogram body is
subprogram-specification is
declarations
begin
statements
end identifier;

16
Functions

17
Subprograms (Functions)
 A function computes and returns a value of
specified type using the input parameters.
 Can be defined locally to an architecture or more
commonly in a package
 Function parameters can only be inputs and
they cannot be modified.
 I.e., you cannot change the value of inputs inside the
function body
 Functions are restricted to substitute
components with only one output
 Statements within a function must be sequential.
18
Function (Syntax)

<parameter list> specifies the function’s input parameters

<parameter list> = [CONSTANT] constant_name: constant_type;

<parameter list> = SIGNAL signal_name: signal_type;

VARIABLES are not allowed

No range specification should be included
do NOT enter RANGE when using INTEGER, or TO/
DOWNTO when using STD_LOGIC_VECTOR
However, you can use range as well, but it is better to 19
 Functions (II)

 Function declaration:
 function rising_edge(signal clock: in std_logic) return Boolean;

function rising_edge(signal clock: std_logic)

return Boolean is
--
-- declarative region: declare variables local to the
function
--
begin
--
-- body
--
return (value);
end function rising_edge;

20
Functions (III)

FUNCTION f1 (a, b: INTEGER; SIGNAL c: STD_LOGIC_VECTOR)

RETURN BOOLEAN IS
BEGIN
(sequential statements)
END f1;

a and b are CONSTANTS (notice that the word CONSTANT can be

omitted,
for it is the default object),
c is a SIGNAL

Notice that neither RANGE nor DOWNTO was specified

21
Functions (IV)
 The function is called with the actual parameters.

Example: rising_edge(enable);
 Types of formal and actual parameters must
match.
 Actual parameters could be signal, constant or an
expression.

 WAIT, SIGNAL declarations, and COMPONENTS

are not synthesizable when used in a FUNCTION.

Wait statements, signal declarations and components
cannot be used in functions’ body.

 Parameters have to be mode in.

22
Function call (Examples)

x <= conv_integer(a); -- converts a to an integer

y <= maximum(a, b); -- returns the largest of a and b

IF x > maximum(a, b) ... -- compares x to the largest of a, b

expression appears by itself

23
 Function: Examples (I)
function Min (X, Y : Integer) return Integer is
variable temp : integer;
begin
if (X < Y) then
temp:= X;
else
temp:= Y;
end if;
return temp; function inc (a: bit_vector) return bit_vector is
variable s: bit_vector (a'range);
end Min; variable carry: bit;
begin
carry := '1';
for i in a'low to a'high loop
s(i) := a(i) xor carry;
carry := a(i) and carry;
end loop
return (s);
end inc;

24
Pure vs. Impure Function

25
Pure vs. Impure Function

[pure | impure] function identifier [( parameter_interface_list )]

return type_mark is
{ subprogram_declarative_item }
begin
{ sequential_statements }
end [ function ] [ identifier ];

26
Pure vs. Impure function (I)
 By default, functions are declared as pure;
 In pure functions, the only accessible data are
the input arguments; and the only returned
information from this function is the returned
value. Pure functions do not have access to
objects outside the function.

 VHDL’93 introduces impure declaration;

 Impure functions must be explicitly declared;
 Impure functions can modify data outside their
own scope.
27
 Pure vs. Impure function (II)

Example:

The file bit_file is an outside object.

Since the function is impure, accessing to the file bit_file is possible.
Function Location

29
 Function Location

Function is usually placed in a PACKAGE (for code partitioning,

code reuse, and code sharing purposes)
When placed in a PACKAGE, then a PACKAGE BODY is necessary,
which must contain the body of each FUNCTION

Function can also be located in the main code (either inside the
ARCHITECTURE or inside the ENTITY).

30
Function: Examples (Locate inside arch.)

library IEEE;
use IEEE.std_logic_1164.all;
entity dff is
port(d, clock: in std_logic; q, qbar: out std_logic);
end entity dff;

architecture beh of dff is

function rising_edge(signal clock:std_logic) return Boolean is Declarative

variable edge: Boolean:=FALSE; part of
begin
edge:= (clock = ‘1’ and clock’event); architecture
return (edge);
end function rising_edge;

begin
output: process is
begin
wait until (rising_edge(clock)); Either True or False
q <= d after 5 ns;
qbar <= not d after 5 ns;
end process output;
end architecture beh;
31
 Function: Examples (Locate inside
Entity)
library ieee;
use ieee.std_logic_1164.all;

entity test is
port(a,b: in integer;
C: out integer);
function Min (signal X, Y : Integer) return Integer is
variable temp : integer;

begin
Function if (X < Y) then Entity Part
declaration temp:= X;
and body else
temp:= Y;
end if;
return temp;
end Min;
end test;

architecture test1 of test is

begin
C<=Min(a,b);
end architecture;

32
FUNCTION Located in a Package
 FUNCTION located in a PACKAGE can be
reused and shared by other projects.

 when placed in a PACKAGE, the function

is indeed declared in the PACKAGE, but
described in the PACKAGE BODY

33
Function Located inside package: Example

LIBRARY ieee;
USE ieee.std_logic_1164.all;
PACKAGE my_package IS
FUNCTION positive_edge(SIGNAL s: STD_LOGIC) RETURN BOOLEAN;
END my_package;

PACKAGE BODY my_package IS

FUNCTION positive_edge(SIGNAL s: STD_LOGIC) RETURN BOOLEAN IS
BEGIN
RETURN s'EVENT AND s='1';
END positive_edge;
END my_package;

34
Function Located inside package: Example

LIBRARY ieee;
USE ieee.std_logic_1164.all;
USE work.my_package.all; Invoke the package
----------------------------------------------
ENTITY dff IS
PORT ( d, clk, rst: IN STD_LOGIC;
q: OUT STD_LOGIC);
END dff;
----------------------------------------------
ARCHITECTURE my_arch OF dff IS
BEGIN
PROCESS (clk, rst)
BEGIN
IF (rst='1') THEN q <= '0';
ELSIF positive_edge(clk) THEN q <= d;
END IF;
END PROCESS;
END my_arch;
35
Function Overloading

36
Subprogram Overloading
 Subprograms
 functions and procedures
 Sometimes, it is convenient to have two or
more subprograms with the same name
 function count (oranges: integer) return integer;
function count (apples: bit) return integer;
 dff(clk, d, q, qbar);
dff(clk, d, q, qbar, reset, clear);
 In this case, subprograms are overloaded.
 compiler will decide which subprogram to call
based on the number and type of arguments.

37
Function Overloading-Example
library ieee;
use ieee.std_logic_1164.all;
entity overloading is
port(a: in std_logic_vector(7 downto 0);
b: in bit_vector(3 downto 0); Input:std_logic_vector
c1,c2: out integer range 0 to 30);
end entity;
architecture beh of overloading is
function f1 (x: std_logic_vector(7 downto 0)) return integer is
variable temp: integer:=0;
begin
for i in 0 to 7 loop
if (x(i)='1') then
temp := temp+1;
end if;
end loop;
return temp;
end f1;
function f1(x: bit_vector(3 downto 0)) return integer is
variable temp: integer:=0;
begin Input:bit_vector
for i in 0 to 3 loop
if x(i)='1' then
temp := temp+1;
end if;
end loop; If you change the bit_vector to
return temp; std_logic_vector in the second f1, you
end f1; will get the error of homograph of
begin
another object
c1<=f1(a);
c2<=f1(b); 38
end architecture;
Operator overloading using Functions

39
Example: Overloaded ‘‘+’’ Operator
 Recall that the + operator accepts only
INTEGER, SIGNED, or UNSIGNED values
 We are interested in writing a function
which should allow the sum of
STD_LOGIC_VECTOR values as well
 Thus overloading the ‘‘+’’ operator

40
Example: Overloaded ‘‘+’’ Operator (II)
PACKAGE my_package IS
FUNCTION "+" (a, b: STD_LOGIC_VECTOR)
RETURN STD_LOGIC_VECTOR;
END my_package;
----------------------------------------------
PACKAGE BODY my_package IS
FUNCTION "+" (a, b: STD_LOGIC_VECTOR)
RETURN STD_LOGIC_VECTOR IS
VARIABLE result: STD_LOGIC_VECTOR;
VARIABLE carry: STD_LOGIC;
BEGIN
carry := '0';
FOR i IN a'REVERSE_RANGE LOOP
result(i) := a(i) XOR b(i) XOR carry;
carry := (a(i) AND b(i)) OR (a(i) AND carry) OR
(b(i) AND carry);
END LOOP;
RETURN result;
END "+";
END my_package; 41
Example: Overloaded ‘‘+’’ Operator (III)
LIBRARY ieee;
USE ieee.std_logic_1164.all;
USE work.my_package.all; Invoke the package
----------------------------------------------
ENTITY add_bit IS
PORT ( a: IN STD_LOGIC_VECTOR(3 DOWNTO 0);
y: OUT STD_LOGIC_VECTOR(3 DOWNTO 0));
END add_bit;
----------------------------------------------
ARCHITECTURE my_arch OF add_bit IS
CONSTANT b: STD_LOGIC_VECTOR(3 DOWNTO 0) := "0011";
CONSTANT c: STD_LOGIC_VECTOR(3 DOWNTO 0) := "0110";
BEGIN
y <= a + b + c; -- overloaded "+" operator
END my_arch;

42
Recursive Functions in VHDL

43
Recursive Functions in VHDL (I)
 Recursion is a method of defining
functions in which the function being
defined calls itself.
 The idea is to execute a task in a loop, in a
self similar way
 Recursion is possible in VHDL

However, recursive logic has the disadvantage
of eating up lot of resources in FPGA

You cannot blindly write a recursive code in
your design
44
Recursive Functions in VHDL (II)
 Example: Repetitive XOR operation on a 16 bit signal,
until the result obtained is 2 bit.
 For example if the signal is "1111001100010101“

MSB 8 bits of signal : 11110011

LSB 8 bits of signal : 00010101

XOR operation : 11100110 ( call this signal as 'x1')


MSB 4 bits of x1 : 1110

LSB 4 bits of x1 : 0110

XOR operation : 1000 ( call this signal as 'x2')


MSB 2 bits of x2 : 10

LSB 2 bits of x2 : 00

XOR operation : 10 ( this should be the result obtained when the
code is simulated)

45
 Recursive Functions in VHDL (III)
library IEEE;
use IEEE.STD_LOGIC_1164.ALL;
The num'length attribute is used to get the size of the
entity recursion is input argument
port ( num : in std_logic_vector(15 downto 0);
exor_out : out std_logic_vector(1 downto 0)
);
The signal on which XOR operation has to be
end recursion;
performed
architecture Behavioral of recursion is

function exor( num : std_logic_vector ) return std_logic_vector is

variable numf : std_logic_vector(num'length-1 downto 0):=(others => '0');
variable exorf : std_logic_vector((num'length/2)-1 downto 0):=(others => '0');

begin
numf := num; the result of XOR operation
if (num'length = 4) then
exorf := numf(1 downto 0) xor numf(3 downto 2); the stop condition
else
exorf := exor(numf(num'length-1 downto num'length/2)) xor exor(numf((num'length/2)-1 downto 0));
end if;
return exorf;
end exor; The left half The right half
begin
exor_out <= exor(num); The recursive call is continued until the size of the
end Behavioral; signal becomes 4 46
Recursive Functions in VHDL (IV)
 Let us see how this code is synthesized
 The Technology schematic view of the design is
shown below

47
 Recursive Functions in VHDL (V)
There are 4 LUT's used to implement the logic-Two 4 input LUT's and two
5 input LUT's.

For implementing the logic relatively more resources are used

This is the disadvantage of recursive functions in VHDL

48
Recursive Functions in VHDL (VI)
 In C and other high level languages recursion is
implemented using stack and, there the main
issue is stack overflow
 In a HDL like VHDL, the resources may get
heavily used for even simple codes
 The synthesis tool implements the logic by
replicating the function in separate hardware
component.
 If a function calls 10 times itself, then the resources
will be used nearly 10 times than that , when an
individual block is implemented

49
Some useful functions

50
Type conversion
 VHDL is strongly depends to data types
 Sometimes data type conversion is
necessary
 For type conversion you should the
following library
 Use ieee.std_logic_arith.all
Std_logic bit
Std_logic_vector bit_vector

Std_logic_vector integer

51
Type conversion
 Functions:

Function to_stdlogicvector(s:bit_vector) return
std_logic_vector;

Function conv_integer(arg:std_logic_vector) return integer;

Function conv_std_logic_vector(arg:integer, size:integer)
return std_logic_vector;
 Examples
1.
a,b : bit_vector(3 downto 0);
q : std_logic_vector(3 downto 0);
q<= a and b (error)
q<=to_stdlogicvector(a and b); (correct)
Convert to integer
2.

a: integer range 0 to 15;

c: std_logic_vector(3 downto 0);
q : std_logic_vector (3 downto 0);
q<= conv_std_logic_vector(a, 4) when conv_integer(c)=8;

52
Procedures

53
 Procedures (I)
 Procedures are allowed to change the values of
the objects associated with its formal parameters
 Parameters of procedures may of mode in, out
or inout
 If no mode is specified the parameter is
interpreted as having mode in.
 If no class is specified parameters of mode in are
interpreted as being of class constant and
parameters of mode out or inout are interpreted
as being of class variable.
 A procedure can return more than one value

54
Procedure Syntax

<parameter list> = [CONSTANT] constant_name: mode type;

<parameter list> = SIGNAL signal_name: mode type; or

<parameter list> = VARIABLE variable_name: mode type;

55
Procedures (II)
 Similar to functions, WAIT, SIGNAL
declarations, and COMPONENTS are not
synthesizable when used in a procedure

 BUT, a SIGNAL can be declared, but then

the PROCEDURE must be declared in a
PROCESS.

56
 Procecdure:
Mode
Examples
Procedure ModTwo (X : inout Integer) is
begin Here, X is a variable
because class has
case X is
not been specified
When 0 | 1 => null;
When others => X := X mod 2;
end case;
end ModTwo;

procedure dff (signal d: bit_vector; signal clk: bit;

signal q, q_bar: out bit_vector) is
Here d and clk
are input begin
because mode if clk'event and clk = '1' then
has not been q <= d; q_bar <= not(d);
specified end if;
end dff;

57
Procedure Example

architecture beh of CPU is

procedure mread(
address: in std_logic_vector(2 downto 0);
signal R: out std_logic;
signal S: in std_logic;
signal ADDR: out std_logic_vector(2 downto 0);
signal data: out std_logic_vector(31 downto 0)) is
begin
ADDR <= address;
R <= ‘1’;
data <= read_data;
end procedure mread;
...
end architecture beh;

58
Procedures (III)
 Signals can be passed to procedures and
updated within procedures
 Signals cannot be declared within procedures
 Visibility rules apply here (scope)
 Procedure can update signals visible to it even if
these signals do not appear in the parameter list.
 This is sometimes called as side effect of
procedure.
 updating signals that do not appear in the
parameter list is a poor programming practice.

59
Procedure Call

compute_min_max(in1, in2, 1n3, out1, out2); -- statement by

itself

divide(dividend, divisor, quotient, remainder); -- statement by

itself

IF (a>b) THEN compute_min_max(in1, in2, 1n3, out1, out2);

-- procedure call associated to another statement

60
Concurrent vs. Sequential Procedure Calls
 Concurrent procedure call
 Procedure calls can be made in concurrent
signal assignments
 Execution of a procedure is concurrent with
other concurrent procedures, CSA statements,
or processes.
 The procedure is invoked when there is an
event on a signal that is a parameter to the
procedure.
 Sequential procedure call
 Executed within the body of a process.

61
Example: Concurrent Procedure Call
entity serial_adder is
port(a, b, clk, reset: in std_logic; z: out std_logic);
end entity;

architecture structural of serial adder is

component comb is
port(a, b, c_in: in std_logic; z, carry: out std_logic);
end component;

procedure dff(signal d, clk, reset: in std_logic;

signal q, qbar: out std_logic) is
begin
if(reset =‘0’) then behaviora
q <= ‘0’ after 5 ns; qbar <= ‘1’ after 5 ns;
elsif(rising_edge(clk)) then l
q <= d after 5 ns; qbar <= not d after 5 ns; descriptio
end if; n
end procedure;

signal s1, s2: std_logic;

begin
C1: comb port(a=>a, b=>b, c_in=>s1, z=>z, carry=>s2);
dff(clk=>clk, reset=>reset, d=>s2, q=>s1, qbar=>open);
end architecture structural;
62
 Example: Sequential Procedure Call
entity serial_adder is
port(a, b, clk, reset: in std_logic; z: out std_logic);
end entity;
architecture structural of serial adder is
component comb is
port(a, b, c_in: in std_logic; z, carry: out std_logic);
end component;

procedure dff(signal d, clk, reset: in std_logic;

signal q, qbar: out std_logic) is
...
end procedure;

signal s1, s2: std_logic;

begin
C1: comb port(a=>a, b=>b, c_in=>s1, z=>z, carry=>s2);
process
begin
dff(clk=>clk, reset=>reset, d=>s2, q=>s1, qbar=>open);
wait on clk, reset, s2;
end process;
end architecture structural;
63
Procedure Location
 See the figure presented for Functions
 Procedure is usually placed in a PACKAGE
 it can also be located in the main code (either
in the ENTITY or in the declarative part of the
ARCHITECTURE).

64
FUNCTION versus PROCEDURE

65
FUNCTION versus PROCEDURE (I)
 A FUNCTION has zero or more input parameters
and a single return value. The input parameters
can only be CONSTANTS (default) or SIGNALS
(VARIABLES are not allowed).

 A PROCEDURE can have any number of IN,

OUT, and INOUT parameters, which can be
SIGNALS, VARIABLES, or CONSTANTS. For
input parameters (mode IN) the default is
CONSTANT, whereas for output parameters
(mode OUT or INOUT) the default is VARIABLE.
66
FUNCTION versus PROCEDURE (II)
 A FUNCTION is called as part of an expression,
while a PROCEDURE is a statement on its own.
 In both, WAIT and COMPONENTS are not
synthesizable.
 The possible locations of FUNCTIONS and
PROCEDURES are the same.

Though they are usually placed in PACKAGES, they can
also be located in the main code (either inside the
ARCHITECTURE or inside the ENTITY).

When placed in a PACKAGE, then a PACKAGE BODY is
necessary, which should contain the body of each
FUNCTION and/or PROCEDURE declared in the
PACKAGE.
67
ASSERT
68
ASSERT (I)
 ASSERT is a non-synthesizable statement
 The purpose is to write out messages (on the
screen) when problems are found during simulation
 Depending on the severity of the problem, the
simulator is instructed to halt.
 The Syntax
ASSERT condition
[REPORT "message"]
 The severitylevel can be:
[SEVERITY Note, Warning,
severity_level];Error
(default), or Failure
 The message is written when the condition is
FALSE.
69
Assert: Example
 Suppose we have written a function to add two binary
numbers
 It was assumed that the input parameters must have the
same number of bits
 In order to check such an assumption, the following
ASSERT statement could be included in the function
body
ASSERT a'LENGTH = b'LENGTH
REPORT "Error: vectors do not have same
length!"
SEVERITY failure;

 ASSERT does not generate hardware. Synthesis tools

will simply ignore it or give a warning.

70