--- a/CHANGES	Tue Mar 29 19:38:28 2022 +0000
+++ b/CHANGES	Wed Mar 30 06:25:47 2022 +0000
@@ -1,8 +1,16 @@
 Changes in the current code since fc-host-tools-r16:
 
-* New fc-pwt-comp utility compiles PWT buzzer melodies from our ASCII source
-  format (same as for fc-buzplay) into the new binary format we are defining
-  for the new BUZM melody player engine in FC Tourmaline firmware.
+* New utilities have been added for working with FreeCalypso PWT melodies,
+  to be played via the buzzer on those FC phones and development boards that
+  are equipped with such - see doc/Buzzer-melodies article for further details.
+  The new utilities are:
+
+  + fc-pwt-comp compiles PWT buzzer melodies from our ASCII source format (same
+    as for fc-buzplay) into the binary format read by the new BUZM melody player
+    engine in FC Tourmaline firmware.
+
+  + fc-ringlist-comp compiles melody lists into the binary format that will be
+    read by our phone UI firmware at a later stage of integration.
 
 * New l1trace-filter program connects to rvinterf as a client and displays only
   certain filtered L1 traces; it was written for the purpose of isolating

--- a/doc/Buzzer-melodies	Tue Mar 29 19:38:28 2022 +0000
+++ b/doc/Buzzer-melodies	Wed Mar 30 06:25:47 2022 +0000
@@ -124,6 +124,47 @@
 The format of ASCII source files for PWT melodies is best documented by
 examples: see several in the ringtools/examples directory.
 
+Organization of melodies in FC device FFS
+=========================================
+
+We shall have two types of ringtone melodies in FreeCalypso: PWT melodies to be
+played via the buzzer, and E1 melodies to be played via the voice path
+loudspeaker.  Naturally, buzzer melodies can only be played on hardware
+platforms that have a buzzer, and voice path loudspeaker melodies can only be
+played on hw platforms that have such a speaker.  The only platforms that can
+be expected to have both hw provisions are development boards like D-Sample and
+FC Venus - but even on those development boards, each given UI firmware build
+will support one or the other ringing type, but not both at the same time.
+
+We shall have two separate FFS subtrees for these two melody types: PWT melodies
+for the buzzer will be stored under /buz, whereas E1 melodies for the voice path
+will be stored under /mel.  Both trees will be constructed on the host system
+under /opt/freecalypso/buz and /opt/freecalypso/mel, and they will be uploaded
+into FC device FFS with fc-fsio:
+
+upload-subtree /opt/freecalypso/buz /buz
+upload-subtree /opt/freecalypso/mel /mel
+
+Individual melody files (compiled binary formats produced by fc-pwt-comp and
+fc-e1gen) will be stored as /buz/melodyname.bz and /mel/melodyname.e1 for the
+two types.  There will also be melody list or index files:
+
+/buz/ringtones.mls
+/buz/msgtones.mls
+/mel/ringtones.mls
+/mel/msgtones.mls
+
+Each ringtones.mls file (for the buzzer or for Melody E1) will list the
+available melodies for the continuous play-until-answer ringing tone, and each
+msgtones.mls file will list the available melodies for the non-repeating message
+alert tone.  The melody list (.mls) file format is defined by us: it is a binary
+format consisting of fixed-length records, one 80-byte record for each listed
+melody.  Each record consists of two fields: the FFS pathname (always absolute
+as required by the RTOS environment without current directories) of the melody
+file and the name of the melody for the selection menu in the phone UI.  Melody
+lists are compiled from line-based ASCII source into this binary format by our
+fc-ringlist-comp utility.
+
 Standalone buzzer exercising (outside of FC firmware)
 =====================================================
 

--- a/doc/Host-tools-overview	Tue Mar 29 19:38:28 2022 +0000
+++ b/doc/Host-tools-overview	Wed Mar 30 06:25:47 2022 +0000
@@ -193,6 +193,13 @@
 		values between human-intuitive 8:8:8 format and the 5:6:5 format
 		used by the color LCDs in the phones targeted by FreeCalypso.
 
+fc-ringlist-comp
+		This program compiles a list of ringing tone or message alert
+		tone melodies from ASCII source into the binary format (.mls)
+		that will be uploaded into FreeCalypso device FFS and read by
+		the UI layer of FC phone firmwares.  See the Buzzer-melodies
+		article for more details.
+
 fc-serterm	This tool is a trivial serial terminal program.  Its special
 		feature is that any output coming from the serial port that
 		isn't printable ASCII is displayed as by cat -v.  It is useful