mock: Update README.md with design pattern

Add the reasoning behind the design pattern of
placing all params in one struct.

BRANCH=none
BUG=none
TEST=Examined in Gitlies

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

1 files changed, 32 insertions, 5 deletions

diff --git a/common/mock/README.md b/common/mock/README.md
index e1962651a6..df984c3314 100644
--- a/common/mock/README.md
+++ b/common/mock/README.md
@@ -10,7 +10,9 @@ from unit tests and fuzzers' `.mocklist` file.
 * 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.
+  [mock control](#mock-controls) functions/variables.
+  See the [Design Patterns](#design-patterns) section
+  for more detail on design patterns.
 * Add an new entry in [common/mock/build.mk](build.mk)
   that is conditioned on your mock's name.
 
@@ -46,15 +48,40 @@ Example `.mocklist`:
 	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/`.
+If you need additional [mock control](#mock-controls) functionality,
+you may need to include the mock's header file, which is prepended
+with `mock/` in the include line.
 
 For example, to control the return values of the rollback mock:
 
 ```c
 #include "mock/rollback_mock.h"
 
-void somefunc() {
+void yourfunction() {
 	mock_ctrl_rollback.get_secret_fail = true;
 }
-```
\ No newline at end of file
+```
+
+## Mock Controls
+Mocks can change their behavior by exposing "mock controls".
+
+We do this, most commonly, by exposing an additional global struct
+per mock that acts as the settings for the mock implementation.
+The mock user can then modify fields of the struct to change the mock's behavior.
+For example, the `fp_sensor_init_return` field may control what value
+the mocked `fp_sensor_init` function returns.
+
+The declaration for these controls are specified in the mock's header file,
+which resides in [include/mock](/include/mock).
+
+## Design Patterns
+* When creating mock controls, consider placing all your mock parameters in
+  one externally facing struct, like in
+  [fp_sensor_mock.h](/include/mock/fp_sensor_mock.h).
+  The primary reason for this is to allow the mock to be easily used
+  by a fuzzer (write random bytes into the struct with memcpy).
+* When following the above pattern, please provide a macro for resetting
+  default values for this struct, like in
+  [fp_sensor_mock.h](/include/mock/fp_sensor_mock.h).
+  This allows unit tests to quickly reset the mock state/parameters
+  before each unrelated unit test.