-- Altera Microperipheral Reference Design Version 0802
--------------------------------------------------------------------------------
--  File Name: l_conversions_p.vhd
--------------------------------------------------------------------------------
--  Copyright (C) 1997, 1998 Free Model Foundation
-- 
--  This program is free software; you can redistribute it and/or modify
--  it under the terms of the GNU General Public License version 2 as
--  published by the Free Software Foundation.
-- 
--  This package was written by SEVA Technologies, Inc. and donated to the FMF.
--  www.seva.com
--
--  MODIFICATION HISTORY:
-- 
--  version: |  author:  | mod date: | changes made:
--    V1.0     R. Steele   97 DEC 05   Added header and formatting to SEVA file
--    V1.1     R. Munden   98 NOV 28   Corrected some comments
-- 
--------------------------------------------------------------------------------

LIBRARY IEEE;   
USE IEEE.std_logic_1164.ALL;

--------------------------------------------------------------------------------
--  CONVERSION FUNCTION SELECTION TABLES
--------------------------------------------------------------------------------
-- 
--  FROM         TO: std_logic_vector std_logic  natural     time     string
--  -----------------|---------------|---------|---------|---------|-----------
--  std_logic_vector |      N/A      |   N/A   |  to_nat | combine | see below
--  std_logic        |      N/A      |   N/A   |  to_nat | combine | see below
--  natural          |     to_slv    |  to_sl  |   N/A   | to_time | see below
--  time             |      N/A      |   N/A   |  to_nat | N/A     | to_time_str
--  hex string       |       h       |   N/A   |    h    | combine | N/A
--  decimal string   |       d       |   N/A   |    d    | combine | N/A
--  octal string     |       o       |   N/A   |    o    | combine | N/A
--  binary string    |       b       |   N/A   |    b    | combine | N/A
--  -----------------|---------------|---------|---------|---------|-----------
--
--  FROM           TO: hex string decimal string octal string  binary string 
--  -----------------|------------|-------------|------------|----------------
--  std_logic_vector | to_hex_str | to_int_str  | to_oct_str |  to_bin_str
--  std_logic        |    N/A     |    N/A      |    N/A     |  to_bin_str
--  natural          | to_hex_str | to_int_str  | to_oct_str |  to_bin_str
--  -----------------|------------|-------------|------------|----------------
-- 
--------------------------------------------------------------------------------

PACKAGE conversions IS
  
    ----------------------------------------------------------------------------
    -- the conversions in this package are not guaranteed to be synthesizable.
    --
    -- others functions available
    -- fill         creates a variable length string of the fill character
    --
    -- 
    --
    -- input parameters of type natural or integer can be in the form:
    --    normal              -> 8, 99, 4_237
    --    base#value#         -> 2#0101#, 16#fa4C#,  8#6_734#
    --    with exponents(x10) -> 8e4, 16#2e#E4
    --
    -- input parameters of type string can be in the form:
    --    "99", "4_237", "0101", "1010_1010"
    --
    -- for bit/bit_vector <-> std_logic/std_logic_vector conversions use 
    --   package std_logic_1164
    --     to_bit(std_logic)
    --     to_bitvector(std_logic_vector)
    --     to_stdlogic(bit)
    --     to_stdlogicvector(bit_vector)
    --
    -- for "synthesizable" signed/unsigned/std_logic_vector/integer
    -- conversions use
    --   package std_logic_arith 
    --     conv_integer(signed/unsigned)
    --     conv_unsigned(integer/signed,size)
    --     conv_signed(integer/unsigned,size)
    --     conv_std_logic_vector(integer/signed/unsigned,size)
    --
    -- for "synthesizable" std_logic_vector -> integer conversions use
    --   package std_logic_unsigned/std_logic_signed
    --            <these packages are mutually exclusive>
    --     conv_integer(std_logic_vector)
    --            <except for this conversion, these packages are unnecessary)
    --     to minimize compile problems write:
    --       use std_logic_unsigned.conv_integer;
    --       use std_logic_signed.conv_integer;
    --
    -- std_logic_vector, signed and unsigned types are "closely related"
    -- no type conversion functions are needed, use type casting or qualified
    -- expressions
    --
    --   type1(object of type2)          <type casting>
    --   type1'(expression of type2)     <qualified expression>
    --
    -- most conversions have 4 parmeters:
    --   x         : value to be converted 
    --   rtn_len   : size of the return value
    --   justify   : justify value 'left' or 'right', default is right
    --   basespec  : print the base of the value - 'yes'/'no', default is yes
    --
    -- Typical ways to call these functions:
    --     simple, all defaults used
    --     to_bin_str(x)
    --         x will be converted to a string of minimum size with a 
    --           base specification appended for clarity
    --         if x is 10101 then return is b"10101" 
    --
    --   to control size of return string
    --     to_hex_str(x,                
    --                6)                
    --         length of string returned will be 6 characters
    --         value will be right justified in the field  
    --         if x is 10101 then return is ....h"15"
    --          where '.' represents a blank 
    --          if 'rtn_len' parm defaults or is set to 0 then
    --           return string will always be minimum size
    --
    --   to left justify and suppress base specification
    --     to_int_str(x,
    --                6,
    --                justify => left, 
    --                basespec => yes)
    --         length of return string will be 6 characters
    --         the base specification will be suppressed
    --         if x is 10101 then return is 21.... 
    --           where '.' represents a blank 
    --
    -- other usage notes
    --
    --   if rtn_len less than or equal to x'length then ignore 
    --      rtn_len and return string of x'length
    --   the 'justify' parm is effectively ignored in this case
    --
    --   if rtn_len greater than x'length then return string 
    --      of rtn_len with blanks based on 'justify' parm
    --
    -- these routines do not handle negative numbers
    ----------------------------------------------------------------------------

    type justify_side is (left, right);
    type b_spec       is (no  , yes);

    -- std_logic_vector to binary string
    function to_bin_str(x          : std_logic_vector;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes) 
      return string;

    -- std_logic to binary string
    function to_bin_str(x          : std_logic;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes)
      return string;

    -- natural to binary string
    function to_bin_str(x          : natural;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes) 
      return string;
      -- see note above regarding possible formats for x

    -- std_logic_vector to hex string
    function to_hex_str(x          : std_logic_vector;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes) 
      return string;

    -- natural to hex string
    function to_hex_str(x          : natural;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes) 
      return string;
      -- see note above regarding possible formats for x

    -- std_logic_vector to octal string
    function to_oct_str(x          : std_logic_vector;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes) 
      return string;

    -- natural to octal string
    function to_oct_str(x          : natural;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes) 
      return string;
      -- see note above regarding possible formats for x

    -- natural to integer string
    function to_int_str(x          : natural;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes) 
      return string;
      -- see note above regarding possible formats for x

    -- std_logic_vector to integer string
    function to_int_str(x          : std_logic_vector;
                        rtn_len    : natural      := 0;
                        justify    : justify_side := right;
                        basespec   : b_spec       := yes) 
      return string;

    -- time to string
    function to_time_str (x          : time) 
      return string;

    -- add characters to a string
    function fill        (fill_char  : character    := '*';
                          rtn_len    : integer      := 1) 
      return string;
      -- usage:
        -- fill
          -- returns *
        -- fill(' ',10)    
          -- returns ..........  when '.' represents a blank
        -- fill(lf) or fill(ht)  
          -- returns line feed character or tab character respectively

    -- std_logic_vector to natural
    function to_nat      (x        : std_logic_vector) 
      return natural;

    -- std_logic to natural
    function to_nat      (x        : std_logic) 
      return natural;

    -- time to natural
    function to_nat      (x        : time) 
      return natural;

    -- hex string to std_logic_vector
    function h         (x          : string;
                        rtn_len    : positive range 1 to 32 := 32)
      return std_logic_vector;
    -- if rtn_len is < than x'length*4, result will be truncated on the left
    -- if x is other than characters 0 to 9 or a,A to f,F 
    --   or x,X,z,Z,u,U,-,w,W, result will be 0

    -- decimal string to std_logic_vector
    function d         (x          : string;
                        rtn_len    : positive range 1 to 32 := 32)
      return std_logic_vector;
    -- if rtn_len is < than x'length*4, result will be truncated on the left
    -- if x is other than characters 0 to 9 or x,X,z,Z,u,U,-,w,W,
    --   result will be 0

    -- octal string to std_logic_vector
    function o         (x          : string;
                        rtn_len    : positive range 1 to 32 := 32)
      return std_logic_vector;
    -- if rtn_len is < than x'length*4, result will be truncated on the left
    -- if x is other than characters 0 to 7 or x,X,z,Z,u,U,-,w,W,
    --   result will be 0

    -- binary string to std_logic_vector
    function b         (x          : string;
                        rtn_len    : positive range 1 to 32 := 32)
      return std_logic_vector;
    -- if rtn_len is < than x'length*4, result will be truncated on the left
    -- if x is other than characters 0 to 1 or x,X,z,Z,u,U,-,w,W, 
    --   result will be 0

    -- hex string to natural
    function h         (x          : string)
      return natural;
    -- if x is other than characters 0 to 9 or a,A to f,F, result will be 0

    -- decimal string to natural
    function d         (x          : string)
      return natural;
    -- if x is other than characters 0 to 9, result will be 0

    -- octal string to natural
    function o         (x          : string)
      return natural;
    -- if x is other than characters 0 to 7, result will be 0

    -- binary string to natural
    function b         (x          : string)
      return natural;
    -- if x is other than characters 0 to 1, result will be 0

    -- natural to std_logic_vector
    function to_slv    (x          : natural;
                        rtn_len    : positive range 1 to 32 := 32) 
      return std_logic_vector;
      -- if rtn_len is < than sizeof(x), result will be truncated on the left
      -- see note above regarding possible formats for x

    -- natural to std_logic
    function to_sl     (x          : natural) 
      return std_logic;

    -- natural to time
    function to_time   (x          : natural)
      return time;
      -- see note above regarding possible formats for x

END conversions;