IEEE P1164 Working Group - Change Proposal

ID:       CP-010

Proposer: Peter Ashenden <peter@ashenden.com.au>

Status:   Proposed (17-Nov-2002)
          Analyzed (17-Nov-2002, 27-Jan-2003)
          Resolved (17-Feb-2003)

Summary:  Add match functions like numeric_std.std_match

Detail:

        The package ieee.numeric_std provides functions named
        std_match that compare values ignoring strength and taking
        into account "don't care" values.  These functions logically
        belong in the std_logic_1164 package.  It would be desirable
        to include such function in std_logic_1164.


Analysis:

        By Peter Ashenden <peter@ashenden.com.au>, 17-Nov-2002

        Match functions could be included in std_logic_1164, but they
        should not be homographs of the functions declared in
        ieee.numeric_std.  If they were, then models that currently
        use all of both packages (a common thing to do) would break,
        since the effect would be to make none of the homographs
        directly visible.

        To avoid this problem, the functions included in
        std_logic_1164 should simply be named match instead of
        std_match.  That way, old models that refer to std_match from
        numeric_std will still work, and new models can just refer to
        match from the revised version of std_logic_1164.

        Changes to 1164-1993:

        Add the following function declarations to the end of the
        package declaration:

    -------------------------------------------------------------------
    -- match functions
    -------------------------------------------------------------------
    FUNCTION match ( l, r : std_ulogic        ) RETURN BOOLEAN;
    FUNCTION match ( l, r : std_logic_vector  ) RETURN BOOLEAN;
    FUNCTION match ( l, r : std_ulogic_vector ) RETURN BOOLEAN;

        Add the following function bodies to the end of the package
        body:

    -------------------------------------------------------------------
    -- match table
    -------------------------------------------------------------------
    TYPE boolean_table IS ARRAY (std_ulogic, std_ulogic) OF BOOLEAN;
    CONSTANT match_table : boolean_table := (
        -------------------------------------------------------------------------
        -- U      X      0      1      Z      W      L      H      -        |   |
        -------------------------------------------------------------------------
        (FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE,  TRUE), -- | U |
        (FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE,  TRUE), -- | X |
        (FALSE, FALSE,  TRUE, FALSE, FALSE, FALSE,  TRUE, FALSE,  TRUE), -- | 0 |
        (FALSE, FALSE, FALSE,  TRUE, FALSE, FALSE, FALSE,  TRUE,  TRUE), -- | 1 |
        (FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE,  TRUE), -- | Z |
        (FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE,  TRUE), -- | W |
        (FALSE, FALSE,  TRUE, FALSE, FALSE, FALSE,  TRUE, FALSE,  TRUE), -- | L |
        (FALSE, FALSE, FALSE,  TRUE, FALSE, FALSE, FALSE,  TRUE,  TRUE), -- | H |
        ( TRUE,  TRUE,  TRUE,  TRUE,  TRUE,  TRUE,  TRUE,  TRUE,  TRUE)  -- | - |
        );
  
    -------------------------------------------------------------------
    -- match functions
    -------------------------------------------------------------------
    FUNCTION match ( l, r : std_ulogic        ) RETURN BOOLEAN IS
        VARIABLE value : std_ulogic;
    BEGIN
        RETURN match_table (l, r);
    END match;
    -------------------------------------------------------------------
    FUNCTION match ( l, r : std_logic_vector  ) RETURN BOOLEAN IS
      ALIAS lv : std_logic_vector(1 TO l'LENGTH) IS l;
      ALIAS rv : std_logic_vector(1 TO r'LENGTH) IS r;
    BEGIN
        IF ((l'LENGTH < 1) OR (r'LENGTH < 1)) THEN
            ASSERT FALSE
                REPORT "STD_LOGIC_1164.MATCH: null detected, returning FALSE"
                SEVERITY WARNING;
            RETURN FALSE;
        END IF;
        IF lv'LENGTH /= rv'LENGTH THEN
            ASSERT FALSE
                REPORT "STD_LOGIC_1164.MATCH: L'LENGTH /= R'LENGTH, returning FALSE"
                SEVERITY WARNING;
            RETURN FALSE;
        ELSE
            FOR i IN lv'LOW TO lv'HIGH LOOP
                IF NOT (match_table(lv(i), rv(i))) THEN
                    RETURN FALSE;
                END IF;
            END LOOP;
            RETURN TRUE;
        END IF;
    END match;
    -------------------------------------------------------------------
    FUNCTION match ( l, r : std_ulogic_vector ) RETURN BOOLEAN IS
      ALIAS lv : std_ulogic_vector(1 TO l'LENGTH) IS l;
      ALIAS rv : std_ulogic_vector(1 TO r'LENGTH) IS r;
    BEGIN
        IF ((l'LENGTH < 1) OR (r'LENGTH < 1)) THEN
            ASSERT FALSE
                REPORT "STD_LOGIC_1164.MATCH: null detected, returning FALSE"
                SEVERITY WARNING;
            RETURN FALSE;
        END IF;
        IF lv'LENGTH /= rv'LENGTH THEN
            ASSERT FALSE
                REPORT "STD_LOGIC_1164.MATCH: L'LENGTH /= R'LENGTH, returning FALSE"
                SEVERITY WARNING;
            RETURN FALSE;
        ELSE
            FOR i IN lv'LOW TO lv'HIGH LOOP
                IF NOT (match_table(lv(i), rv(i))) THEN
                    RETURN FALSE;
                END IF;
            END LOOP;
            RETURN TRUE;
        END IF;
    END match;

        Insert the following clause (based on clause 5 of Std
        1076.3-1997) after A.8 and renumber subsequent clauses
        accordingly:

        A.9 The match functions

        The match functions provide wild-card matching for the "don't
        care" value.  They also ignore strength when comparing
        well-defined logic values.  Whenever the match function
        compares two std_ulogic values, the function returns true if
        and only if:

        --- both values are well defined and are the same value, or

        --- one value is '0' and the other is 'L', or

        --- one value is '1' and the other is 'H', or

        --- at least one of the values is the "don't care" value '-'.

        Whenever the match function compares two std_logic_vector
        values or two std_ulogic_vector values, the function returns
        true if and only if

        --- the operands are both non-null and have the same length,
            and

        --- the match function applied to each pair of corresponding
            elements returns true.

        When one of the vector arguments to the match function is a
        static value and the other is not, a synthesis tool should
        interpret the call to the match function as equivalent to an
        equality test on corresponding elements of the arguments,
        excepting those elements of the static value that are equal to
        '-'.


Further Analysis:

        By Peter Ashenden <peter@ashenden.com.au>, 27-Jan-2003

        Discussion on the vhdl-std-logic@eda.org list suggests that
        having the match function disallow null arrays is draconian.
        Furthermore, yielding a false result for the case of both
        actual parameters being null arrays is wrong.  The code for
        the vector versions of match should be:

    FUNCTION match ( l, r : std_logic_vector  ) RETURN BOOLEAN IS
      ALIAS lv : std_logic_vector(1 TO l'LENGTH) IS l;
      ALIAS rv : std_logic_vector(1 TO r'LENGTH) IS r;
    BEGIN
        IF lv'LENGTH /= rv'LENGTH THEN
            ASSERT FALSE
                REPORT "STD_LOGIC_1164.MATCH: L'LENGTH /= R'LENGTH, returning FALSE"
                SEVERITY WARNING;
            RETURN FALSE;
        ELSE
            FOR i IN lv'LOW TO lv'HIGH LOOP
                IF NOT (match_table(lv(i), rv(i))) THEN
                    RETURN FALSE;
                END IF;
            END LOOP;
            RETURN TRUE;
        END IF;
    END match;
    -------------------------------------------------------------------
    FUNCTION match ( l, r : std_ulogic_vector ) RETURN BOOLEAN IS
      ALIAS lv : std_ulogic_vector(1 TO l'LENGTH) IS l;
      ALIAS rv : std_ulogic_vector(1 TO r'LENGTH) IS r;
    BEGIN
        IF lv'LENGTH /= rv'LENGTH THEN
            ASSERT FALSE
                REPORT "STD_LOGIC_1164.MATCH: L'LENGTH /= R'LENGTH, returning FALSE"
                SEVERITY WARNING;
            RETURN FALSE;
        ELSE
            FOR i IN lv'LOW TO lv'HIGH LOOP
                IF NOT (match_table(lv(i), rv(i))) THEN
                    RETURN FALSE;
                END IF;
            END LOOP;
            RETURN TRUE;
        END IF;
    END match;


        The text in clause A.9 referring to the vector version of
        match should be:

        Whenever the match function compares two std_logic_vector
        values or two std_ulogic_vector values, the function returns
        true if and only if

        --- the operands have the same length, and

        --- both operands are null arrays, or both are non-null
            arrays and the match function applied to each pair of
            corresponding elements returns true.


Resolution:

  Analysis accepted

  Member votes: Accept 13 (100%)   Reject 0 (0%)   Abstain 0 (0%)
  All votes:    Accept 15 (100%)   Reject 0 (0%)   Abstain 0 (0%)

  From Egbert Molenkamp

  match /= std_match if both are null arrays. Maybe we should pass it
  also to the WG1076.3 for inclusion of match for signed/unsigned in
  the numeric packages.