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 K2xx 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.

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)
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.