# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1701722450 0
# Node ID 30fad2b3afd2dcab44c5c7f8ad4f290ee25c8254
# Parent  fb7442e3d430f7673dd2ddd4cae0d01f61b41c0e
doc/Flash-write-protection: document flash lock-state retrieval

diff -r fb7442e3d430 -r 30fad2b3afd2 doc/Flash-write-protection
--- a/doc/Flash-write-protection	Mon Dec 04 02:17:54 2023 +0000
+++ b/doc/Flash-write-protection	Mon Dec 04 20:40:50 2023 +0000
@@ -27,11 +27,37 @@
 but these locks are of the "soft" kind, removable by performing a PPB erase
 operation which is not further blocked.
 
-As of fc-host-tools-r21, fc-loadtool provides support for programming and
-erasing PPBs on select Spansion and Samsung flash chips, primarily aimed at
-unlocking flash regions that have been write-protected by previous parties.
-It is very helpful, however, to understand some theory before using these
-commands, which the present document aims to explain.
+fc-loadtool support for sector write-protection
+===============================================
+
+As of fc-host-tools-r21, fc-loadtool provides the following facilities in
+relation to sector write-protection features on AMD-style flash chips:
+
+* flash lock-state command is available when operating on those flash chips for
+  which we've implemented the necessary table, listing how sectors are grouped
+  for the purpose of write protection, how they are grouped for the purpose of
+  lock status retrieval via Autoselect read mode, and what additional lock
+  status words should be checked.  We have implemented the necessary knowledge
+  tables for all chips on which we support PPB manipulation (see below), but
+  also for some chips on which sector lock state can be modified only by high-
+  voltage methods - on the latter chips we can examine the lock state, but not
+  modify it.
+
+* flash ppb-* commands actively alter sector write protection state by
+  programming and erasing PPBs on those Spansion and Samsung flash chips that
+  allow these PPB alterations by software commands alone (without high-voltage
+  circuits) and for which we have implemented the necessary knowledge tables.
+  The set of flash chips for which we have implemented these active commands is
+  a proper subset of those for which we have implemented flash lock-state
+  retrieval.
+
+These commands are primarily aimed at unlocking flash regions that have been
+write-protected by previous parties.  It is very helpful, however, to understand
+some theory before using these commands, which the present document aims to
+explain.
+
+How PPBs work
+=============
 
 Spansion and Samsung flash chips that feature PPBs have one PPB per sector or
 per sector group - some sectors are aggregated into groups (of 4 sectors max)