tests,base: Added GTests for base/condcodes.hh
The documentation for the "findParity" and "findCarry" functions in
base/condcodes.hh has been enhanced to better explain their behavior.
Change-Id: I9ba3bf68eb56529a3030e965ec21e41d2dacfad6
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/21639
Reviewed-by: Gabe Black <gabeblack@google.com>
Reviewed-by: Bobby R. Bruce <bbruce@ucdavis.edu>
Maintainer: Bobby R. Bruce <bbruce@ucdavis.edu>
Tested-by: kokoro <noreply+kokoro@google.com>
diff --git a/src/base/SConscript b/src/base/SConscript
index 07a76cb..b11775d 100644
--- a/src/base/SConscript
+++ b/src/base/SConscript
@@ -100,6 +100,7 @@
GTest('circular_queue.test', 'circular_queue.test.cc')
GTest('sat_counter.test', 'sat_counter.test.cc')
GTest('refcnt.test','refcnt.test.cc')
+GTest('condcodes.test', 'condcodes.test.cc')
DebugFlag('Annotate', "State machine annotation debugging")
DebugFlag('AnnotateQ', "State machine annotation queue debugging")
diff --git a/src/base/condcodes.hh b/src/base/condcodes.hh
index 986e8d3..d15e832 100644
--- a/src/base/condcodes.hh
+++ b/src/base/condcodes.hh
@@ -37,6 +37,46 @@
/**
* Calculate the carry flag from an addition. This should work even when
* a carry value is also added in.
+ *
+ * Parameters:
+ * dest: The result value of the addition.
+ * src1: One of the addends that was added.
+ * src2: The other addend that was added in.
+ *
+ * Rationale:
+ * This code analyzes the most sig. bits of the source addends and result,
+ * and deduces the carry out flag from them without needing the carry in bit.
+ *
+ * Observe that we have four cases after an addition regarding the carry
+ * in and carry out bits:
+ *
+ * If we have no carry in but a carry out:
+ * src1 and src2 must both be 1, with the result bit being 0. Hence,
+ * ~0 + 1 + 1 => 11, which has a high second bit. We return true.
+ *
+ * If we have a carry in and a carry out:
+ * src1 and src2 can either be 1 and 0, or vice versa. In this case,
+ * the addition with the carry in gives a result bit of 0 but a carry out.
+ * Hence,
+ * ~0 + 1 + 0 => 10, or ~0 + 0 + 1 => 10. We return true.
+ *
+ * Or, src1 and src2 can both be one. Along with the carry, this gives
+ * a result of 1 and a carry out of 1. Hence,
+ * ~1 + 1 + 1 => 10. We return true.
+ *
+ * If we have no carry in and no carry out:
+ * src1 and src2 can either be 1 and 0, 0 and 1, or 0 and 0.
+ * In the first two cases the result bit is 1, which when negated does not
+ * contribute to the sum algorithm at all. In the last case the result bit
+ * is zero, but neither src1 nor src2 contribute to the sum either. Hence,
+ * ~1 + 1 + 0 => 1,
+ * ~1 + 0 + 1 => 1,
+ * ~0 + 0 + 0 => 1.
+ * So we return false for all of these cases.
+ *
+ * If we have a carry in, but no carry out:
+ * src1 and src2 can neither be 1. So the overall result bit is 1. Hence:
+ * ~1 + 0 + 0 => 0. We return false.
*/
inline
bool
@@ -59,6 +99,19 @@
/**
* Calculate the parity of a value. 1 is for odd parity and 0 is for even.
+ *
+ * Parameters:
+ * dest: a value to be tested.
+ *
+ * Rationale:
+ * findParity simply performs bitwise XOR operations on each "pair" of bits
+ * in the dest parameter; the procedure being that a pair of ones will be
+ * XOR'ed out of the intermediate value.
+ *
+ * This process is repeated until one last pair of bits are XOR'ed together.
+ * If the intermediate is still one, then there is exactly one high bit
+ * which does not have a corresponding high bit. Therefore, the value must
+ * have odd parity, and we return 1 accordingly. Otherwise we return 0.
*/
inline
bool
diff --git a/src/base/condcodes.test.cc b/src/base/condcodes.test.cc
new file mode 100644
index 0000000..d9863be
--- /dev/null
+++ b/src/base/condcodes.test.cc
@@ -0,0 +1,263 @@
+/*
+ * Copyright (c) 2019 The Regents of the University of California
+ * All rights reserved
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met: redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer;
+ * redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution;
+ * neither the name of the copyright holders nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * Authors: Bobby R. Bruce
+ * Jared J. Barocsi
+ */
+
+#include <gtest/gtest.h>
+
+#include "base/condcodes.hh"
+
+/*
+ * Add 0x80 + 0x80 to get 0x100. findCarry should report a carry flag after
+ * this operation.
+ */
+TEST(CondCodes, FindCarryWithNoCarryIn8Bit)
+{
+ EXPECT_TRUE(findCarry(8, 0x100, 0x80, 0x80));
+}
+
+/*
+ * Add 0xf0 + 0x0f to get 0xff. findCarry should not report a carry flag after
+ * this operation.
+ */
+TEST(CondCodes, FindNoCarryWithNoCarryIn8Bit)
+{
+ EXPECT_FALSE(findCarry(8, 0xff, 0xf0, 0x0f));
+}
+
+/*
+ * Add 0x7f + 0x80 + 0x01 to get 0x100. findCarry should report a carry flag
+ * after this operation.
+ */
+TEST(CondCodes, FindCarryWithCarryIn8Bit)
+{
+ EXPECT_TRUE(findCarry(8, 0x100, 0x80, 0x7f));
+}
+
+/*
+ * Add 0x80 + 0x7e + 0x01 to get 0xff. findCarry should not report a carry
+ * flag after this operation.
+ */
+TEST(CondCodes, FindNoCarryWithCarryIn8Bit)
+{
+ EXPECT_FALSE(findCarry(8, 0xff, 0x80, 0x7e));
+}
+
+/*
+ * Add 0x80000000 + 0x80000000 to get 0x100000000. findCarry should report a
+ * carry flag after this operation.
+ */
+TEST(CondCodes, FindCarryWithNoCarryIn32Bit)
+{
+ EXPECT_TRUE(findCarry(32, 0x100000000, 0x80000000, 0x80000000));
+}
+
+/*
+ * Add 0xffff0000 + 0x0000ffff to get 0xffffffff. findCarry should not report a
+ * carry flag after this operation.
+ */
+TEST(CondCodes, FindNoCarryWithNoCarryIn32Bit)
+{
+ EXPECT_FALSE(findCarry(32, 0xffffffff, 0xffff0000, 0x0000ffff));
+}
+
+TEST(CondCodes, FindCarryWithCarryIn32Bit)
+{
+ /*
+ * Add 0x80000000 + 0x7fffffff + 0x00000001 to get 0x100000000,
+ * resulting in a carry
+ */
+ EXPECT_TRUE(findCarry(32, 0x100000000, 0x80000000, 0x7fffffff));
+ // Add 0x80000000 + 0x7ffffffe + 0x00000001 to get 0xffffffff,
+ // resulting in no carry
+ EXPECT_FALSE(findCarry(32, 0xffffffff, 0x80000000, 0x7ffffffe));
+ // Add 0xffffffff + 0x00000000 + 0x00000001 to get 0x100000000,
+ // resulting in a carry
+ EXPECT_TRUE(findCarry(32, 0x100000000, 0xffffffff, 0x00000000));
+}
+
+TEST(CondCodes, FindCarryWithNoCarryIn64Bit)
+{
+ // Add 0x8000000000000000 + 0x8000000000000000 to get 0x10000000000000000,
+ // (unrepresentable with uint64_t), resulting in a carry
+ EXPECT_TRUE(findCarry(64, 0x0000000000000000,
+ 0x8000000000000000,
+ 0x8000000000000000));
+ /*
+ * Add 0x0000000000000000 + 0x0000000000000000 to get 0x0000000000000000
+ * resulting in no carry
+ * We get the same sum as above case due to unrepresentability, but we
+ * should still expect no carry
+ */
+ EXPECT_FALSE(findCarry(64, 0x0000000000000000,
+ 0x0000000000000000,
+ 0x0000000000000000));
+ /*
+ * Add 0x8000000000000000 + 0x7fffffffffffffff to get 0xffffffffffffffff,
+ * resulting in no carry
+ */
+ EXPECT_FALSE(findCarry(64, 0xffffffffffffffff,
+ 0x8000000000000000,
+ 0x7fffffffffffffff));
+ /*
+ * Add 0xffffffff00000000 + 0x00000000ffffffff to get 0xffffffffffffffff,
+ * resulting in no carry
+ */
+ EXPECT_FALSE(findCarry(64, 0xffffffffffffffff,
+ 0xffffffff00000000,
+ 0x00000000ffffffff));
+}
+
+TEST(CondCodes, FindCarryWithCarryIn64Bit)
+{
+ /* Add 0x8000000000000000 + 0x8000000000000000 + 0x0000000000000001
+ * to get 0x1 000000000000001 (unrepresentable with uint64_t),
+ * resulting in a carry
+ */
+ EXPECT_TRUE(findCarry(64, 0x0000000000000000,
+ 0x8000000000000000,
+ 0x7fffffffffffffff));
+ /*
+ * Add 0x0000000000000000 + 0x0000000000000000 + 0x0000000000000001
+ * resulting in no carry
+ * We get the same sum as the above case due to unrepresentability, but we
+ * should still expect no carry
+ */
+ EXPECT_FALSE(findCarry(64, 0x0000000000000001,
+ 0x0000000000000000,
+ 0x0000000000000000));
+ /*
+ * Add 0x8000000000000000 + 0x7fffffffffffffff + 0x0000000000000001
+ * to get 0x1 0000000000000000 (unrepresentable with uint64_t),
+ * resulting in a carry
+ */
+ EXPECT_TRUE(findCarry(64, 0x0000000000000000,
+ 0x8000000000000000,
+ 0x7fffffffffffffff));
+ /*
+ * Add 0xffffffff00000000 + 0x000000000000000 + 0x0000000000000001
+ * to get 0x1 0000000000000000 (unrepresentable with uint64_t),
+ * resulting in a carry
+ */
+ EXPECT_TRUE(findCarry(64, 0x0000000000000000,
+ 0xffffffffffffffff,
+ 0x0000000000000001));
+}
+
+TEST(CondCodes, FindOverflow8Bit)
+{
+ /*
+ * Addition of 127 + 1 = 128 or -128 as signed two's complement.
+ * Overflow occurs in this case
+ */
+ EXPECT_TRUE(findOverflow(8, 0x80, 0x7f, 0x01));
+ /*
+ * Addition of 64 + 63 = 127, or 127 as signed two's complement.
+ * No overflow occurs
+ */
+ EXPECT_FALSE(findOverflow(8, 0x7f, 0x40, 0x3f));
+}
+
+TEST(CondCodes, FindOverflow32Bit)
+{
+ /*
+ * Addition of 2,147,483,647 + 1 = 2,147,483,648, or -2,147,483,648 as
+ * signed two's complement. Overflow occurs in this case
+ */
+ EXPECT_TRUE(findOverflow(32, 0x80000000, 0x7fffffff, 0x00000001));
+ /*
+ * Addition of 1,073,741,824 + 1,073,741,823 = 2,147,483,647, or
+ * 2,147,483,647 as signed two's complement. No overflow occurs
+ */
+ EXPECT_FALSE(findOverflow(32, 0x7fffffff, 0x40000000, 0x3fffffff));
+}
+
+TEST(CondCodes, FindOverflow64Bit)
+{
+ /*
+ * Addition of 0x7fffffffffffffff + 0x0000000000000001 =
+ * 0x8000000000000000, or -9,223,372,036,854,775,808 as signed two's
+ * complement. Overflow occurs in this case
+ */
+ EXPECT_TRUE(findOverflow(64, 0x8000000000000000,
+ 0x7fffffffffffffff,
+ 0x0000000000000001));
+ /* Addition of 0x4000000000000000 + 0x3fffffffffffffff =
+ * 0x7fffffffffffffff, or 9,223,372,036,854,775,807 as signed two's
+ * complement. No overflow occurs
+ */
+ EXPECT_FALSE(findOverflow(64, 0x7fffffffffffffff,
+ 0x4000000000000000,
+ 0x3fffffffffffffff));
+}
+
+TEST(CondCodes, OddParity)
+{
+ EXPECT_EQ(1, findParity(8, 1));
+}
+
+TEST(CondCodes, EvenParity)
+{
+ EXPECT_EQ(0, findParity(8, 3));
+}
+
+TEST(CondCodes, OddParityOverflow)
+{
+ EXPECT_EQ(1, findParity(8, 0x102));
+}
+
+TEST(CondCodes, EvenParityOverflow)
+{
+ EXPECT_EQ(0, findParity(4,0x43));
+}
+
+TEST(CondCodes, IsNegative)
+{
+ EXPECT_EQ(1, findNegative(8, 128));
+}
+
+TEST(CondCodes, IsNotNegative)
+{
+ EXPECT_EQ(0, findNegative(8, 127));
+}
+
+TEST(CondCodes, IsZero)
+{
+ EXPECT_EQ(1, findZero(8, 0));
+}
+
+TEST(CondCodes, IsNotZero)
+{
+ EXPECT_EQ(0, findZero(8, 1));
+}
+
+TEST(CondCodes, IsZeroOverflow)
+{
+ EXPECT_EQ(1, findZero(8,0x100));
+}
