[flashrom-gerrit] [S] Change in flashrom[main]: how_to_add_new_chip: Add a section for feature bits and WRSR handling

[Anastasia Klimchuk (Code Review)]

Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/82908?usp=email )

Change subject: how_to_add_new_chip: Add a section for feature bits and WRSR handling
......................................................................

how_to_add_new_chip: Add a section for feature bits and WRSR handling

Feature bits are too complicated to understand if we only read the
codes/datasheets. Add a new section in how_to_add_new_chip to add more
details about each feature bits.

Add the detailed explanation for WRSR handling first. If this new
section looks good, I'll try to add some more sections in further
commits.

BUG=b:345154585
TEST=meson compile -C builddir and view the doc.

Change-Id: I34c20933a375380c8702f79ac637595cd3466000
Signed-off-by: Hsuan Ting Chen 
Reviewed-on: https://review.coreboot.org/c/flashrom/+/82908
Tested-by: build bot (Jenkins) 
Reviewed-by: Anastasia Klimchuk 
---
M doc/contrib_howtos/how_to_add_new_chip.rst
1 file changed, 26 insertions(+), 2 deletions(-)

Approvals:
  build bot (Jenkins): Verified
  Anastasia Klimchuk: Looks good to me, approved

diff --git a/doc/contrib_howtos/how_to_add_new_chip.rst b/doc/contrib_howtos/how_to_add_new_chip.rst
index b046ac3..8aad324 100644
--- a/doc/contrib_howtos/how_to_add_new_chip.rst
+++ b/doc/contrib_howtos/how_to_add_new_chip.rst
@@ -96,12 +96,36 @@
 * ``.page_size`` is really hard.
   Please read this `long explanation https://mail.coreboot.org/pipermail/flashrom/2013-April/010817.html`_,
   or ignore it for now and set it to 256.
-* We encode various features of flash chips in a bitmask named ``.feature_bits``.
-  Available options can be found in ``include/flash.h``, look for macros defined by the pattern ``#define FEATURE_XXX``.
 * ``.tested`` is used to indicate if the code was tested to work with real hardware, its possible values are defined
   in ``include/flash.h``. Without any tests it should be set to ``TEST_UNTESTED``.
   See also another doc :doc:`how_to_mark_chip_tested`.

+Feature Bits
+============
+
+We encode various features of flash chips in a bitmask named ``.feature_bits``.
+Available options can be found in ``include/flash.h``, look for macros defined by the pattern ``#define FEATURE_XXX``.
+
+Some of the feature bits have more detailed docs, see below.
+
+Write-Status-Register (WRSR) Handling
+-------------------------------------
+
+The Write Status Register (WRSR) is used exclusively in SPI flash chips to configure various settings within the flash chip,
+including write protection and other features.
+The way WRSR is accessed varies between SPI flash chips, leading to the need for these feature bits.
+
+* ``FEATURE_WRSR_EWSR``
+  indicates that we need an **Enable-Write-Status-Register** (EWSR) instruction which opens the status register for the
+  immediately-followed next WRSR instruction. Usually, the opcode is **0x50**.
+
+* ``FEATURE_WRSR_WREN``
+  indicates that we need an **Write-Enable** (WREN) instruction to set the Write Enable Latch (WEL) bit. The WEL bit
+  must be set prior to every WRSR command. Usually, the opcode is **0x06**.
+
+* ``FEATURE_WRSR_EITHER``
+  indicates that either EWSR or WREN is supported in this chip.
+
 Operations
 ==========