The Calypso chip has a PWM light output called LT/PWL - a digital output pin
that can be configured as either LT or PWL.  The documentation we got from TI
is not exhaustively complete in describing the exact behaviour and output
waveforms of these two modes, thus I (Mother Mychaela) did a little bit of lab
experimentation to complete the picture.  All experimental observations were
made with an oscilloscope probe placed on the LT/PWL signal on a FreeCalypso
Caramel2 board.

LT mode
=======

LT functionality of the LT/PWL output is implemented in the ARMIO block,
together with GPIO and keypad functions.  LT output stays at constant low level
(zero light) only when the LIGHT bit in BUZZ_LIGHT_REG (FFFE:480E) is cleared;
if the LIGHT bit is set, then a small amount of light will be emitted even if
LIGHT_LEVEL_REG is set to 0, contrary to CAL207 document saying "no light" in
this case.  Light levels 0 through 63 as written into LIGHT_LEVEL_REG really
correspond to 1/64 through 64/64 in terms of the actual emitted PWM duty cycles.
If the register is written with the maximum light level of 63, then LT output
is a continuous high level, with no o'scope-observable PWM activity.  If the
register is written with any other value, then PWM activity becomes visible on
an oscilloscope, with each full cycle period equal to 64 periods of CLK13M,
i.e., PWM frequency equals 203.125 kHz, the master 13 MHz clock divided by 64.
The shape of this PWM output is totally straightforward: if LIGHT_LEVEL_REG is
set to 0, LT output is high for one CLK13M period and low for 63 periods, then
repeat; if LIGHT_LEVEL_REG is set to 1, LT output is high for 2 CLK13M periods
and low for 62 periods, and so forth, with LIGHT_LEVEL_REG set to 63 resulting
in LT being high in all 64 slots, i.e., continuous high output with no visible
PWM activity.

PWL mode
========

The description of PWL in the CAL207 document is reasonably good; only a few
additional notes need to be made:

* By the fundamental principles of how all LFSRs work, an LFSR of N bits CANNOT
  have a period of 2**N, instead the greatest period that can be achieved with
  careful choice of polynomial is 2**N-1.  Calypso PWL block features an 8-bit
  LFSR, TI's choice of polynomial (hard-wired in the silicon) is a proper one,
  thus the period is 255.

* Two alternate hw implementations are possible: XOR implementation would
  produce an LFSR with valid values [1,255], whereas XNOR implementation would
  produce an LFSR with valid values [0,254].  Obviously we have no way to look
  inside Calypso silicon, but the visible behaviour with different comparator
  values suggests that the internal LFSR runs in the [1,255] range.  There must
  be some reset logic in the hw that prevents a stuck value of 0.

* The visible output on the PWL pin repeats every 255 cycles of CLK32K, and the
  average light intensity ranges from 0/255 to 254/255 in 1/255 steps.  If
  PWL_LEVEL_REG is set to either 0 or 1, PWL output is continuous low; if the
  register is set to 2, PWL output is 1/255 (on for just one CLK32K cycle out of
  255), and if the register is set to maximum of 255, PWL output is NOT
  continuous high as CAL207 claims, but instead it is 254/255, i.e., on for 254
  out of every 255 CLK32K periods.

Deep sleep interaction
======================

LT mode uses CLK13M, thus it is incompatible with deep sleep.  PWL uses CLK32K
instead, thus deep sleep is perfectly OK with this light on.