Change in flashrom[master]: tests: Add comprehensive comment for chip.c

[Anastasia Klimchuk (Code Review)]

Anastasia Klimchuk has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/59238 )

Change subject: tests: Add comprehensive comment for chip.c
......................................................................

tests: Add comprehensive comment for chip.c

Change-Id: Ie498ec55cce8460fc0b2e1fe27254d3a9f763fac
Signed-off-by: Anastasia Klimchuk 
---
M tests/chip.c
1 file changed, 21 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/flashrom refs/changes/38/59238/1

diff --git a/tests/chip.c b/tests/chip.c
index a166bb6..f5110c0 100644
--- a/tests/chip.c
+++ b/tests/chip.c
@@ -24,6 +24,27 @@
 #define MOCK_CHIP_SIZE (8*MiB)
 #define MOCK_CHIP_CONTENT 0xff

+/*
+ * This file contains tests for operations on flash chip.
+ *
+ * All of the tests emulate operations on flash chip. Importantly
+ * there are two types of tests here, corresponding to two ways of
+ * emulating a chip:
+ *
+ * 1) Tests which use mock chip struct (chip_8MiB for example). In the
+ * struct all operations read/write/unlock/erase are delegated to mock
+ * functions defined in this file. Mock functions are using g_chip_state
+ * as representation of flash chip.
+ * Example of test: erase_chip_test_success.
+ *
+ * 2) Tests which use dummyflasher's capabilities to emulate operations
+ * on flash chip. Chip struct looks very close to a real flashchip struct
+ * as it is defined in flashchip.c (chip_W25Q128_V for example).
+ * Dummyflasher controls chip state and emulates read/write/unlock/erase.
+ * g_chip_state is NOT used for these type of tests.
+ * Example of test: erase_chip_with_dummyflasher_test_success.
+ */
+
 static struct {
    unsigned int unlock_calls; /* how many times unlock function was called */
    uint8_t buf[MOCK_CHIP_SIZE]; /* buffer of total size of chip, to emulate a chip */