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

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Calypso-buzzer-output	Sat May 29 07:07:05 2021 +0000
@@ -0,0 +1,91 @@
+Our dear Calypso has a dedicated digital output for driving old-fashioned
+cellphone buzzers - I (Mother Mychaela) previously assumed those buzzers to be
+piezoelectric, but now it appears that they are actually magnetic buzzers, not
+piezo.  But irrespective of the physics of the actual transducer that is
+ultimately controlled by Calypso BU/PWT output, the Calypso output itself is
+purely digital, producing digital waveforms, and we (FreeCalypso) need to
+understand exactly what the chip puts out.  The findings presented here have
+been obtained by observing Calypso BU/PWT output with an oscilloscope; the hw
+platform used by the Mother for these experiments was a BenQ M32 module - this
+module has the familiar Calypso+Iota chipset inside, it has BU/PWT brought out,
+and the breakout board supplied with these modules allowed for very quick
+experimentation.
+
+BU mode
+=======
+
+BU functionality of the BU/PWT output is implemented in the ARMIO block,
+together with GPIO and keypad functions.  Here are the new findings which were
+previously unknowable without oscilloscope observation:
+
+* In "normal" buzzer operation when ARMIO_LOAD_TIM is in the [1,255] range
+  (i.e., not 0), the output frequency is 13 MHz / 512 / (ARMIO_LOAD_TIM + 1).
+  This part matches our previous understanding.  The highest frequency that can
+  be produced is 12.6953125 kHz, and the lowest is 99.182129 Hz.
+
+* When ARMIO_LOAD_TIM is set to 0 and the buzzer is enabled, BU output is NOT a
+  25.390625 kHz tone (per the formula above) as we previously thought - instead
+  BU output will be constant high if BUZZER_LEVEL_REG is set to maximum 63, or
+  pure 203.125 kHz PWM exactly like LT otherwise.
+
+* PWM power level control for BU works exactly like the one for LT - see the
+  companion Calypso-PWM-light article.
+
+* The interesting question is exactly how PWM power level control and tone
+  generation combine, and the answer turned out to match the terse description
+  in CAL207: BU is the output of an AND gate; one input to this AND gate is the
+  output of the timer that produces tones between 99 Hz and 12.7 kHz (or
+  constant high if ARMIO_LOAD_TIM is set to 0), and the other input to the AND
+  gate is a PWM block strictly identical to LT.
+
+* For a practical example, consider what happens when a 12.7 kHz (max frequency)
+  tone is emitted in combination with PWM.  The "on" part of the waveform at
+  this tone frequency equals 512 periods of CLK13M, whereas the full cycle of
+  LT-like PWM is 64 periods of CLK13M.  Thus the waveform seen on an o'scope
+  consists of 8 repeated PWM cycles, then a "pause" of 512 CLK13M periods (the
+  "off" part of the tone waveform), then the full cycle repeats.  Furthermore,
+  the tone waveform and the PWM waveform fed to the internal AND gate are not
+  synchronized, and the resulting slight misalignment is easily visible on an
+  o'scope.
+
+Pirelli DP-L10
+==============
+
+In the Pirelli DP-L10 phone Calypso BU output is repurposed to control the
+vibrator.  Pirelli's official fw sets ARMIO_LOAD_TIM to 0 and BUZZER_LEVEL_REG
+to 63; when operated in this manner, BU becomes a mere on/off output under
+software control just like a GPIO.  If someone wishes to run the vibrating motor
+at a lower speed (i.e., exercise a form of "analog" control), the correct way to
+perform such feat would be by dialing down BUZZER_LEVEL_REG (PWM control between
+1/64 and 64/64) - setting ARMIO_LOAD_TIM to a nonzero value does not seem to
+make any sense when the buzzer has been replaced with a vibrator.
+
+PWT mode
+========
+
+The principal difference between BU and PWT modes is that BU mode generates
+"arbitrary" tone frequencies by dividing from CLK13M/512, whereas PWT mode
+generates predefined musical note frequencies, specifically 48 notes of the
+chromatic scale from F4 through E8 in the scientific pitch notation.  The
+frequency range of PWT mode is narrower than BU mode (349 Hz to 5274 Hz, as
+opposed to 99 Hz to 12.7 kHz), and PWT does not support constant high output
+for Pirelli-style vibrator driving - however, BU mode suffers from a major
+problem in that its repertoire of possible tone frequencies does not correspond
+to musical notes.  Given the desire to have ringtone melodies that are composed
+of standard musical notes, TI added the new PWT hardware block that is
+specifically designed to produce musical note frequencies.
+
+Here are some observations about PWT made with o'scope experiments:
+
+* The description of FRC_REG in CAL207 is correct: bits [1:0] select the octave,
+  bits [5:2] select the semitone within the octave.  The definitions in the
+  non-functional (not actually used) mmiBuzzer.h header file in TI's BMI source
+  are wrong - or more precisely, the definitions under #if 0 are the correct
+  ones, whereas the enabled-for-compilation definitions are wrong.
+
+* PWM power control works on the same principle as in BU mode: the output of
+  the musical tone frequency generator and the output of the PWM block are
+  simply ANDed together.  The 64-level PWM block itself is very similar to the
+  ones in LT and BU, but it runs 8 times slower, i.e., one PWM period is 512
+  cycles of CLK13M, as opposed to 64 cycles of CLK13M in BU and LT, and each
+  "quantum" of this slower PWM equals 8 cycles of CLK13M.