# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1701644404 0
# Node ID 162d2cf394e24abcbff4ec1c7edb6151be90fbcf
# Parent  74024eb17e04f29e4d9f4417929f3239c4fd9dfe
fc-loadtool help: document new commands for sector lock/unlock

diff -r 74024eb17e04 -r 162d2cf394e2 loadtools/loadtool.help
--- a/loadtools/loadtool.help	Sun Dec 03 21:11:12 2023 +0000
+++ b/loadtools/loadtool.help	Sun Dec 03 23:00:04 2023 +0000
@@ -170,6 +170,13 @@
 flash status		Intel-style flash only: read Status Register
 flash unlock		Intel-style flash only: unlock flash sectors
 
+Additional operations for select Spansion and Samsung flash chips:
+
+flash lock-state	Retrieve and display sector write-protection state
+flash ppb-program	Program Persistent Protection Bit for one sector
+flash ppb-program-all	Program all PPBs in the addressed flash bank
+flash ppb-erase-all	Erase all PPBs in the flash chip, unlocking all sectors
+
 Additional operations for Compal targets only:
 
 flash compal-imei		Read IMEI from OTP protection register
@@ -277,6 +284,53 @@
 geometry information; these functions have been moved to the new flash id and
 flash geom commands.
 
+=== flash:lock-state
+This command is only implemented for certain specific Spansion and Samsung
+flash chip types that have lockable sectors, i.e., an ability to write-protect
+certain flash sectors in a persistent, non-volatile manner.  This command
+retrieves and displays the lock state of every sector in the addressed flash
+bank, as well as some chip-global lock status words.  (The details are highly
+chip-dependent.)
+
+In the case of 16 MiB flash chips, you need to execute flash lock-state to see
+the lock state of sectors in the first flash bank and flash2 lock-state to see
+the lock state of sectors in the second flash bank.
+
+=== flash:ppb-program
+flash[2] ppb-program sector-offset
+
+This command (implemented only for certain specific Spansion and Samsung flash
+chip types) programs the Persistent Protection Bit (PPB) for the specified
+sector, causing that sector to become persistently write-protected.  Note that
+on many flash chips sectors are aggregated into groups for the purpose of write
+protection, with a group of up to 4 sectors sharing the same PPB - once that
+per-group PPB is programmed, all sectors in that group become write-protected.
+
+Use flash ppb-erase-all command to clear all write protection locks created by
+this command.
+
+=== flash:ppb-program-all
+This command is implemented only for those flash chip types whose PPB program
+and erase commands follow the model of Spansion PL-J, rather than that of
+Spansion PL-N.  It programs all PPBs that reside in the addressed flash bank,
+which will be the entire chip in the case of S71PL064J or half of the chip in
+the case of S71PL129J or its Samsung equivalent.  There is no anticipated need
+for this command to ever be invoked by end users of fc-loadtool - instead it is
+best seen as a made-accessible internal function of the tool, the internal
+function that is primarily needed as part of flash ppb-erase-all implementation.
+
+=== flash:ppb-erase-all
+This command erases the special-purpose non-volatile memory element inside the
+flash chip that stores all Persistent Protection Bits (PPBs) for this chip.
+Because the erased state of a PPB corresponds to the associated flash sector or
+group of sectors being unlocked, the present operation clears all write
+protection locks in the entire chip, making all flash unlocked.
+
+Special note for 16 MiB flash chips: because there is only one dedicated NV
+memory element in the entire flash chip for storing all PPBs, erasable only as
+a unit, this command operates on the entire chip rather than per-bank.  There
+is no flash2 ppb-erase-all command for this reason.
+
 === flash:program-bin
 flash[2] program-bin flash-offset binfile [file-offset [length]]