--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Calypso-PWM-light	Sat May 29 07:07:05 2021 +0000
@@ -0,0 +1,62 @@
+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.