VHDL package?

Question

What is it for and what are some VHDL package examples?

Answer 1

A VHDL package is somewhat like a '.h' header file in C. It's basically a collection of procedures , functions , constants , files , aliases , types , components and attributes. The usage of packages allows grouping various types of functionally and is a good way of organizing code in a cleaner and more structural manner.

Example :

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

package package_functions_general is

    function log_n
    (
        data        : positive   ;
        number_base : positive
    )
    return natural ;

    function one_hot_to_binary
    (
        vector_one_hot : std_logic_vector
    )
    return std_logic_vector ;

    function count_ones
    (
        input : std_logic_vector
    )
    return natural ;

end package package_functions_general ;

package body package_functions_general is

function log_n
(
  data        : positive   ;
  number_base : positive
)
return natural is
variable temp : natural := data ;
variable n : natural := 0 ;
begin

  while temp > 1 loop
    temp := temp / number_base ;
    n := n + 1 ;
  end loop ;
  return n ;

end function log_n ;

function one_hot_to_binary
(
  vector_one_hot : std_logic_vector
)
return std_logic_vector is
variable vector_binary : std_logic_vector ( positive ( ceil ( log2 ( real ( vector_one_hot ' length ) ) ) ) - 1 downto 0 ) := ( others => '0' ) ;
begin

  for index in vector_one_hot ' range
  loop
    if vector_one_hot ( index ) = '1' then
      vector_binary := vector_binary or std_logic_vector ( to_unsigned ( index , vector_binary ' length ) ) ;
    end if ;
  end loop ;
  return vector_binary ;

end function ;

function count_ones
(
  input : std_logic_vector
)
return natural is
variable counter : natural := 0 ;
begin

  for index in input ' range
  loop
    if input ( index ) = '1' then
      counter := counter + 1 ;
    end if ;
  end loop ;
  return counter ;

end function ;

end package body package_functions_general ;

Answer 2

The package is a unit that groups various declarations (types, signals, constants, subprograms, component, etc). These declarations can be shared between multiple independent designs. A package consists of a mandatory package declaration and optional package body.

To make items declared in a packages are visible in other design units you need to use a use clause (use <library>.<package>.(<item_name> | all))

Syntax from VHDL Standard:

package_declaration ::=
package identi?er is
package_declarative_part
end [ package ] [ package_simple_name ] ;

package_declarative_part ::=
{ package_declarative_item }

package_declarative_item ::=
subprogram_declaration
| type_declaration
| subtype_declaration
| constant_declaration
| signal_declaration
| shared_variable_declaration
| ?le_declaration
| alias_declaration
| component_declaration
| attribute_declaration
| attribute_speci?cation
| disconnection_speci?cation
| use_clause
| group_template_declaration
| group_declaration

package_body ::=
package body package_simple_name is
package_body_declarative_part
end [ package body ] [ package_simple_name ] ;

package_body_declarative_part ::=
{ package_body_declarative_item }

package_body_declarative_item ::=
subprogram_declaration
| subprogram_body
| type_declaration
| subtype_declaration
| constant_declaration
| shared_variable_declaration
| ?le_declaration
| alias_declaration
| use_clause
| group_template_declaration
| group_declaration

Example:

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

package math_pkg is

  pure function integer_log2(v : in natural) return integer;
  pure function or_reduce(s : in std_logic_vector) return std_logic;

end package math_pkg;

package body math_pkg is

  pure function integer_log2(v : in natural) return integer is
  variable log2count : integer := 0;
  variable x : integer := v;
begin
  while x > 1 loop
    log2count := log2count + 1;
    x := (x + 1) / 2;
  end loop;
  return log2count;
end function integer_log2;

  pure function or_reduce(s : in std_logic_vector) return std_logic is
    variable v : std_logic_vector(s'length-1 downto 0);
    variable r : std_logic;
  begin
    v := s;
    r := '0';
    for i in v'range loop
      r := r or v(i);
    end loop;
    return r;
  end function;

end package body math_pkg;

So I can type use work.math_pkg.all and use integer_log2 function. For example to port the declaration:

entity dev_entity is
  generic (
    depth : integer := 8
  );
  port (
    addr : in std_logic_vector(integer_log2(depth)-1 downto 0);
    ...
  );
end entity;