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.