mock: Add mock structure for fuzzers and tests

This introduces the common/mock and include/mock directories
which hold mock implementations of other common libraries.

The general idea it to create mocks which can be used in
simple scenarios, by providing meaningful default return
values and functionality, and more complicated scenarios
like fuzzers, where the return values need to continuously change.

The build system has been adapted to allow the inclusion of
a new .mocklist file for tests and fuzzers. This file specifies
exactly which mocks will be pulled into the build for a given
test/fuzz. In order to maintain cleanliness, this file is optional.

Examples:
* http://crrev.com/c/1682945/17 makes use of three different mocks,
  one of which is the rollback mock.
* An upcoming rollback unit test ( http://crrev.com/c/1686460 ),
  needs to pull in mocks that support the rollback interface, but
  explicitly cannot pull in the rollback mock.

BRANCH=none
BUG=b:116065496
TEST=make buildall -j

Change-Id: Ib87b1a93b6d73309afaf7115276ead49218598ff
Signed-off-by: Craig Hesling <hesling@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1719569
Reviewed-by: Daisuke Nojiri <dnojiri@chromium.org>

2 files changed, 68 insertions, 0 deletions

diff --git a/common/mock/README.md b/common/mock/README.md
new file mode 100644
index 0000000000..e1962651a6
--- /dev/null
+++ b/common/mock/README.md
@@ -0,0 +1,60 @@
+# Common Mocks
+This directory holds mock implementations for use in fuzzers and tests.
+
+Each mock is given some friendly build name, like ROLLBACK or FP_SENSOR.
+This name is defined in [common/mock/build.mk](build.mk) and referenced
+from unit tests and fuzzers' `.mocklist` file.
+
+## Creating a new mock
+
+* Add the mock source to [common/mock](/common/mock) and the
+  optional header file to [include/mock](/include/mock).
+  Header files are only necessary if you want to expose additional
+  mock control functions/variables.
+* Add an new entry in [common/mock/build.mk](build.mk)
+  that is conditioned on your mock's name.
+
+If a unit test or fuzzer requests this mock, the build system will
+set the variable `HAS_MOCK_<BUILD_NAME>` to `y` at build time.
+This variable is used to conditionally include the the mock source
+in [common/mock/build.mk](build.mk).
+
+Example line from [common/mock/build.mk](build.mk):
+
+```make
+# Mocks
+mock-$(HAS_MOCK_ROLLBACK) += mock/rollback_mock.o
+```
+
+## Using a mock
+Unit tests and fuzzers can request a particular mock by adding an entry to
+their `.mocklist` file. The mocklist file is similar to a `.tasklist`
+file, where it is named according to the test/fuzz's name followed by
+`.mocklist`, like `fpsensor.mocklist`.
+The mocklist file is optional, so you may need to create one.
+
+Example `.mocklist`:
+
+```c
+/* Copyright 2019 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+ #define CONFIG_TEST_MOCK_LIST \
+	MOCK(ROLLBACK)         \
+	MOCK(FP_SENSOR)
+```
+
+If you need additional mock control functionality, you may need to include
+the mock's header file, which is prepended with `mock/`.
+
+For example, to control the return values of the rollback mock:
+
+```c
+#include "mock/rollback_mock.h"
+
+void somefunc() {
+	mock_ctrl_rollback.get_secret_fail = true;
+}
+```
\ No newline at end of file
diff --git a/common/mock/build.mk b/common/mock/build.mk
new file mode 100644
index 0000000000..190dde9be8
--- /dev/null
+++ b/common/mock/build.mk
@@ -0,0 +1,8 @@
+# Copyright 2019 The Chromium OS Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+# See common/mock/README.md for more information.
+
+# Example:
+# mock-$(HAS_MOCK_ROLLBACK) += rollback_mock.o
\ No newline at end of file