--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Flash-write-protection	Mon Dec 04 01:42:35 2023 +0000
@@ -0,0 +1,81 @@
+Some Calypso-based GSM MS designs (phones, modems, development boards) use
+AMD-style (Spansion or Samsung) flash chips, while others use Intel flash.
+In the case of Calypso devices that use Spansion or Samsung flash chips, all of
+those chips support a rarely used feature: an ability to write-protect selected
+flash sectors, disallowing erase and program operations in those areas.  With
+earlier AMD-style flash chips (actual AMD-branded ones prior to introduction of
+Spansion brand, as well as Samsung K5A32xx used in Openmoko devices) this
+sector-level write protection can only be applied or lifted by way of external
+programming equipment, executing special commands with a high voltage applied
+to one of the pins - hence when the chip resides on a product board, no new
+sector locks can be applied.  (We are not aware of any Calypso GSM device manuf
+who locked some flash sectors and then populated the chip onto the board in
+that state.)
+
+With newer Spansion and Samsung flash families, however, sector locks became
+more easily accessible: they have Persistent Protection Bits (PPBs) which can
+be programmed (locking a sector or a group of sectors) and erased (removing all
+such locks) in-system under normal operating conditions, using only special
+software commands.  These flash chips also have "hard" locking modes: a Password
+Sector Protection mode in which PPBs can only be modified after feeding a
+matching 64-bit key to the chip, and an OTP "master lock" mode in which the
+ability to erase PPBs is irreversibly disabled, locking all write-protected
+sectors forever - but so far we (FreeCalypso community) have not yet encountered
+any devices in which any of these "hard" locks have been activated.  There is,
+however, at least one Calypso-based phone out there (Sony Ericsson K2x0 family)
+in which the shipping state of the device includes some flash sector locks -
+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.
+
+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)
+for the purpose of write protection control.  All of these PPBs are contained
+in one special-purpose non-volatile memory element inside the flash chip, and
+this NV memory element behaves like a little flash sector of its own: it has a
+program operation, affecting each PPB individually, and an erase operation that
+affects all PPBs across the chip at once.  (See How-flash-really-works article
+for an explanation of program and erase operations.)  The programmed state of a
+PPB corresponds to the associated flash sector or sector group being locked
+(write-protected), and the erased state of a PPB corresponds to the flash
+location being unlocked (free to erase and program at will).
+
+fc-loadtool commands for manipulating PPBs are flash ppb-program and flash
+ppb-erase-all; they are named in this manner (as opposed to a naming scheme
+based on "lock/unlock" or "protect/unprotect") to emphasize the physical nature
+of what they actually do in the flash chip.  flash ppb-program command (or
+flash2 ppb-program for the second bank of 16 MiB flash chips) addresses a
+specific sector and programs that sector's PPB, causing the sector to become
+write-protected; flash ppb-erase-all erases all PPBs across the flash chip,
+causing the entire main flash array to become unlocked for write operations.
+
+The internal implementation of these PPB manipulation commands is very different
+between PL-J and PL-N flash types, as required by the respective flash chip
+families presenting a very different type of command interface for PPB
+operations.  The command interface implemented on Spansion PL-J family and at
+least some Samsung flash chips (K5L29xx in particular) exposes the raw physics
+of the flash (see How-flash-really-works article) to the user for PPB
+operations, requiring flashing software tool developers to understand all of
+that theory and implement it in practice.  OTOH, the command interface for PPB
+program and erase operations implemented on Spansion PL-N family (of which only
+PL129N is usable with Calypso) brings these special operations into harmony with
+ordinary flash programming and erasure procedures.  We don't know (and may never
+know) if Spansion aimed to simplify life for flash low-level driver implementors
+or if internal advancements from PL-J to PL-N flash necessitated some changes
+in physics-level program/erase algorithms and Spansion didn't feel like exposing
+the internal details of their newer flash - but the practical implication for us
+is that we had to implement two different code paths to support both ways of
+performing these operations, as we need to support all flash chip types that are
+found in Calypso GSM devices of different ages.
+
+It also needs to be noted that at least in Spansion PL-J and Samsung flash chips
+the special non-volatile memory element that holds PPBs has a *very* limited
+number of program-erase cycles: the datasheets we were able to find give a limit
+of 100 (1e2) cycles for this special NV memory element, compared to 1e5 cycles
+promised by the same datasheets for the main flash array.  So please beware,
+and avoid needlessly cycling these write protection bits.