Fuck it, we're doing it live

6 files changed, 656 insertions, 0 deletions

diff --git a/doc/api-asm.68k b/doc/api-asm.68k
new file mode 100644
index 0000000..e6f466c
--- /dev/null
+++ b/doc/api-asm.68k
@@ -0,0 +1,104 @@
+=============================================================================
+
+*** How to use ***
+
+You need to take "src-68k/echo.68k" and include it in your program. Then you
+need to take "built/prog-z80.bin" (or if you built Echo from source, the
+generated binary). Finally, go to the echo.68k file, look for @Z80Program
+(should be near the end of the file) and change the filename to point where
+the prog-z80.bin file is.
+
+Echo should now be inside your program. Now call Echo_Init (see below) to
+initialize Echo and load the instrument list, and then you can proceed to use
+Echo as needed (e.g. call Echo_PlayBGM to start playing music).
+
+Unless stated otherwise, calling the API subroutines will *not* modify the
+68000 registers.
+
+=============================================================================
+
+*** Initialization ***
+
+Echo_Init
+
+   Initializes Echo. Loads the instrument list, loads the Z80 engine and gets
+   it running. You need to call this before you can use Echo (usually when
+   the program is just starting).
+   
+   The address of the instrument list is given in register a0. The instrument
+   list can be built using the Echo_List* macros. An example of a short
+   instrument list is as follows:
+   
+   Echo_ListEntry instrument1
+   Echo_ListEntry instrument2
+   Echo_ListEntry instrument3
+   Echo_ListEnd
+   
+   Where the parameter for Echo_ListEntry is the address (e.g. a label) to
+   the EIF/EEF/EWF data of the instrument.
+
+=============================================================================
+
+*** Background music ***
+
+Echo_PlayBGM
+
+   Starts playback of the specified background music. The register a0 points
+   to the ESF data for the background music.
+
+Echo_StopBGM
+
+   Stops playback of background music. Used both to stop and to pause music
+   (the latter can be undone with Echo_ResumeBGM, see below).
+
+Echo_ResumeBGM
+
+   Resumes playback of whatever background music was playing last time before
+   Echo_StopBGM was called. Used when you want to unpause music.
+
+=============================================================================
+
+*** Sound effects ***
+
+Echo_PlaySFX
+
+   Starts playback of the specified sound effect. The register a0 points to
+   the ESF data for the sound effect.
+
+Echo_StopSFX
+
+   Stops playback of sound effects.
+
+=============================================================================
+
+*** Control ***
+
+Echo_GetStatus
+
+   Gets the current status of Echo. The status is returned as a word in d0,
+   with the following bits set as relevant:
+   
+   Bit 0 .... Sound effect is playing
+   Bit 1 .... Background music is playing
+   Bit 15 ... Echo is busy (can't take commands)
+   
+   The API will automatically wait if you try to send a command while Echo is
+   busy, so the only reason to check for that is if you don't want to halt
+   the 68000 until Echo is ready to take more commands.
+
+=============================================================================
+
+*** Raw access ***
+
+Echo_SendCommand
+
+   Sends an argument-less command to Echo. The command ID is given as a byte
+   in register d0.
+
+Echo_SendCommandEx
+
+   Sends a command to Echo that takes an address as its argument. The command
+   ID is given as a byte in register d0, while the address argument is given
+   in register a0.
+
+=============================================================================
diff --git a/doc/api-c.txt b/doc/api-c.txt
new file mode 100644
index 0000000..fcfd07b
--- /dev/null
+++ b/doc/api-c.txt
@@ -0,0 +1,120 @@
+=============================================================================
+
+*** How to use ***
+
+Add "echo.c" and "echoblob.h" in your program files. Then include the header
+"echo.h" in whatever source files you need to access the Echo API, i.e.
+
+   #include "echo.h"
+
+(these files are present in the "c" directory)
+
+Then use echo_init to initialize Echo and load the instrument list (see
+below). After that you can use Echo as needed (e.g. call echo_play_bgm to
+start playing music, etc.).
+
+The file "echoblob.h" is the Z80 binary turned into a C array. If you want to
+change the blob, just use the included blob2c tool. It's invoked as follows:
+
+   blob2c «input.bin» «output.h»
+
+=============================================================================
+
+*** Initialization ***
+
+void echo_init(const void **list)
+
+   Initializes Echo. Loads the instrument list, loads the Z80 engine and gets
+   it running. You need to call this before you can use Echo (usually when
+   the program is just starting).
+   
+   The parameter 'list' is a pointer to an array of pointers, where each
+   entry points to the EIF/EEF/EWF data of each instrument. The list ends
+   with a NULL pointer. For example:
+   
+   const void* const list[] = {
+      instrument1,
+      instrument2,
+      instrument3,
+      NULL
+   };
+   
+   (if NULL isn't defined for whatever reason just use 0 instead)
+
+=============================================================================
+
+*** Background music ***
+
+void echo_play_bgm(const void *esf)
+
+   Starts playback of the specified background music. The parameter 'esf'
+   points to the ESF data for the background music.
+
+void echo_stop_bgm()
+
+   Stops playback of background music. Used both to stop and to pause music
+   (the latter can be undone with echo_resume_bgm, see below).
+
+void echo_resume_bgm()
+
+   Resumes playback of whatever background music was playing last time before
+   echo_stop_bgm was called. Used when you want to unpause music.
+
+=============================================================================
+
+*** Sound effects ***
+
+void echo_play_sfx(const void *esf)
+
+   Starts playback of the specified sound effect. The parameter 'esf' points
+   to the ESF data for the sound effect.
+
+void echo_stop_sfx()
+
+   Stops playback of sound effects.
+
+=============================================================================
+
+*** Control ***
+
+uint16_t echo_get_status()
+
+   Gets the current status of Echo. Returns an OR of the following flags,
+   as relevant:
+   
+   ECHO_STAT_BGM .... Background music is playing
+   ECHO_STAT_SFX .... Sound effect is playing
+   ECHO_STAT_BUSY ... Echo is busy (can't take commands)
+   
+   The API will automatically wait if you try to send a command while Echo is
+   busy, so the only reason to check for that is if you don't want to halt
+   the 68000 until Echo is ready to take more commands.
+
+=============================================================================
+
+*** Raw access ***
+
+void echo_send_command(uint8_t command)
+
+   Sends an argument-less command to Echo. The parameter 'command' is the
+   command to send, and may be one of the following:
+   
+   ECHO_CMD_STOPBGM ..... Stop background music playback
+   ECHO_CMD_RESUMEBGM ... Resume background music playback
+   ECHO_CMD_STOPSFX ..... Stop sound effect playback
+
+void echo_send_command_ex(uint8_t command, const void *address)
+
+   Sends a command to Echo that takes an address as its argument. The
+   parameter 'command' is the command to send, while the parameter 'address'
+   is the address to use as argument. The command may be one of these:
+   
+   ECHO_CMD_PLAYBGM .... Start background music playback
+   ECHO_CMD_PLAYSFX .... Start sound effect playback
+   ECHO_CMD_LOADLIST ... Load instrument list (warning: see below)
+   
+   Do *NOT* use ECHO_CMD_LOADLIST unless you *REALLY* know you're doing, this
+   makes Echo load the instrument list by itself and it expects a different
+   format from the one used by the C API.
+
+=============================================================================
diff --git a/doc/eef.txt b/doc/eef.txt
new file mode 100644
index 0000000..c3ab92e
--- /dev/null
+++ b/doc/eef.txt
@@ -0,0 +1,35 @@
+=============================================================================
+
+OVERVIEW
+
+    EEF stands for "Echo Envelope Format" and it's the format in which PSG
+    instruments are stored.
+
+FORMAT
+
+    EEF instruments consist of a list of volume levels. Each byte represents
+    a different volume level, and the value ranges from $00 (loudest) to $0F
+    (quietest). Each byte represents one tick (i.e. 1/60th of a second).
+    
+    Looping is possible. The start of the loop is marked by a byte with value
+    $FE, while the end of the loop is marked by a byte with value $FF. There
+    must be at least one volume byte between them or Echo will hang.
+    
+    To make a non-looping PSG instrument, just put the last volume value
+    inside the loop.
+
+=============================================================================
+
+NOTES
+
+    Yes, this format was kind of an afterthought. Later I may improve it to
+    provide at least some kind of RLE-like compression, but for now you'll
+    have to stick with this :P
+    
+    Also, since PSG instruments are required to use PSG channels and I know
+    many of you don't want to mess with them at all, here's a flat PSG
+    instrument (i.e. no envelope):
+    
+        $FE,$00,$FF
+
+=============================================================================
diff --git a/doc/eif.txt b/doc/eif.txt
new file mode 100644
index 0000000..3d1f27d
--- /dev/null
+++ b/doc/eif.txt
@@ -0,0 +1,27 @@
+=============================================================================
+
+OVERVIEW
+
+    EIF stands for "Echo Instrument Format" and it's the format in which FM
+    instruments are stored.
+
+FORMAT
+
+    EIF instruments are essentially raw dumps of the YM2612 registers. They
+    consist of 29 bytes, where each byte belongs to a different YM2612
+    register. The registers are stored in the following order (assuming the
+    first FM channel):
+    
+        $B4                     -- Algorithm and feedback
+        $30, $34, $38, $3C      -- Multiplier and detune
+        $40, $44, $48, $4C      -- Total level
+        $50, $54, $58, $5C      -- Attack rate
+        $60, $64, $68, $6C      -- Decay rate
+        $70, $74, $78, $7C      -- Sustain rate
+        $80, $84, $88, $8C      -- Release rate and sustain level
+        $90, $94, $98, $9C      -- SSG-EG
+    
+    Some bits are unused and ignored by the YM2612. In an EIF instrument,
+    they *must* be 0, since Echo will rely on this for optimization purposes.
+
+=============================================================================
diff --git a/doc/esf.txt b/doc/esf.txt
new file mode 100644
index 0000000..a7b833e
--- /dev/null
+++ b/doc/esf.txt
@@ -0,0 +1,355 @@
+=============================================================================
+
+OVERVIEW
+
+    ESF stands for "Echo Stream Format". This is the format in which BGM and
+    SFX sequences are stored. Essentially this is the music arrangement data.
+    The format is mostly the same for both BGM and SFX, with just a few
+    exceptions.
+
+FORMAT
+
+    ESF is a streamed format (think MIDI without the useless complexity).
+    It's stored as a sequence of events, where each event takes up between
+    one and three bytes. An event could be something like "note on", "set
+    volume", "stop", etc.
+
+CHANNEL LOCKING
+
+    When both BGM and SFX are being played, it's likely that some channels
+    may get used by both. In this case, Echo will give the SFX privilege over
+    those channels.
+    
+    This is achieved by channel "locking". When the SFX starts, it first
+    locks the channels it needs to use. When the SFX ends, those channels get
+    unlocked. BGM won't play on the locked channels while the SFX is playing.
+
+=============================================================================
+
+EVENT LIST
+
+    $00nn ..... Note on FM channel #1
+    $01nn ..... Note on FM channel #2
+    $02nn ..... Note on FM channel #3
+    $04nn ..... Note on FM channel #4
+    $05nn ..... Note on FM channel #5
+    $06nn ..... Note on FM channel #6
+    $08nn ..... Note on PSG channel #1
+    $09nn ..... Note on PSG channel #2
+    $0Ann ..... Note on PSG channel #3
+    $0Bnn ..... Note on PSG channel #4
+    $0Cnn ..... Note on PCM channel
+    
+    $10 ....... Note off FM channel #1
+    $11 ....... Note off FM channel #2
+    $12 ....... Note off FM channel #3
+    $14 ....... Note off FM channel #4
+    $15 ....... Note off FM channel #5
+    $16 ....... Note off FM channel #6
+    $18 ....... Note off PSG channel #1
+    $19 ....... Note off PSG channel #2
+    $1A ....... Note off PSG channel #3
+    $1B ....... Note off PSG channel #4
+    $1C ....... Note off PCM channel
+    
+    $20nn ..... Set volume FM channel #1
+    $21nn ..... Set volume FM channel #2
+    $22nn ..... Set volume FM channel #3
+    $24nn ..... Set volume FM channel #4
+    $25nn ..... Set volume FM channel #5
+    $26nn ..... Set volume FM channel #6
+    $28nn ..... Set volume PSG channel #1
+    $29nn ..... Set volume PSG channel #2
+    $2Ann ..... Set volume PSG channel #3
+    $2Bnn ..... Set volume PSG channel #4
+    
+    $30nnnn ... Set frequency FM channel #1
+    $31nnnn ... Set frequency FM channel #2
+    $32nnnn ... Set frequency FM channel #3
+    $34nnnn ... Set frequency FM channel #4
+    $35nnnn ... Set frequency FM channel #5
+    $36nnnn ... Set frequency FM channel #6
+    $38nnnn ... Set frequency PSG channel #1
+    $39nnnn ... Set frequency PSG channel #2
+    $3Annnn ... Set frequency PSG channel #3
+    $3Bnn ..... Set noise type PSG channel #4
+    
+    $40nn ..... Set instrument FM channel #1
+    $41nn ..... Set instrument FM channel #2
+    $42nn ..... Set instrument FM channel #3
+    $44nn ..... Set instrument FM channel #4
+    $45nn ..... Set instrument FM channel #5
+    $46nn ..... Set instrument FM channel #6
+    $48nn ..... Set instrument PSG channel #1
+    $49nn ..... Set instrument PSG channel #2
+    $4Ann ..... Set instrument PSG channel #3
+    $4Bnn ..... Set instrument PSG channel #4
+    
+    $E0 ....... [SFX] Lock FM channel #1
+    $E1 ....... [SFX] Lock FM channel #2
+    $E2 ....... [SFX] Lock FM channel #3
+    $E4 ....... [SFX] Lock FM channel #4
+    $E5 ....... [SFX] Lock FM channel #5
+    $E6 ....... [SFX] Lock FM channel #6
+    $E8 ....... [SFX] Lock PSG channel #1
+    $E9 ....... [SFX] Lock PSG channel #2
+    $EA ....... [SFX] Lock PSG channel #3
+    $EB ....... [SFX] Lock PSG channel #4
+    
+    $F0nn ..... Set parameters FM channel #1
+    $F1nn ..... Set parameters FM channel #2
+    $F2nn ..... Set parameters FM channel #3
+    $F4nn ..... Set parameters FM channel #4
+    $F5nn ..... Set parameters FM channel #5
+    $F6nn ..... Set parameters FM channel #6
+    
+    $FC ....... [BGM] Go to loop
+    $FD ....... [BGM] Set loop point
+    $FEnn ..... Delay ticks
+    $FF ....... Stop playback
+
+=============================================================================
+
+$00nn: Note on FM channel #1
+$01nn: Note on FM channel #2
+$02nn: Note on FM channel #3
+$04nn: Note on FM channel #4
+$05nn: Note on FM channel #5
+$06nn: Note on FM channel #6
+
+    These events do a "note on" at the specified FM channel. The event is
+    followed by a byte, which indicates which note to play. The value is as
+    follows, where "octave" ranges from 0 to 7 and "semitone" ranges from 0
+    to 11:
+    
+        32 * octave + 2 * semitone + 1
+
+$08nn: Note on PSG channel #1
+$09nn: Note on PSG channel #2
+$0Ann: Note on PSG channel #3
+
+    These events do a "note on" at the specified square wave PSG channel.
+    The event is followed by a byte, which indicates which note to play. The
+    value is as follows, where "octave" ranges from 0 to 5 and "semitone"
+    ranges from 0 to 11:
+    
+        24 * octave + 2 * semitone
+
+$0Bnn: Note on PSG channel #4
+
+    This event does a "note on" at the noise PSG channel. The event is
+    followed by a byte, which indicates what kind of noise to play. The
+    following values are valid:
+    
+        $00 ... Periodic noise, high pitch
+        $01 ... Periodic noise, medium pitch
+        $02 ... Periodic noise, low pitch
+        $03 ... Periodic noise, PSG3 frequency
+        $04 ... White noise, high pitch
+        $05 ... White noise, medium pitch
+        $06 ... White noise, low pitch
+        $07 ... White noise, PSG3 frequency
+    
+    When using values $03 and $07, the third square wave PSG channel controls
+    the noise frequency. You can change this frequency using the events to
+    change the frequency of that channel (usually you'd use event type $3A).
+
+$0Cnn: Note on PCM channel
+
+    This event does a "note on" at the PCM channel. More specifically, it
+    starts playback of a PCM sample. This event is followed by a byte, that
+    specifies an index in the pointer list indicating where's the sample
+    data. Samples are stored as EWF (Echo Waveform Format).
+    
+    NOTE: FM channel #6 will be disabled. That channel will be re-enabled
+    when PCM playback is over (either because the waveform is over or because
+    the channel is stopped explicitly).
+
+=============================================================================
+
+$10: Note off FM channel #1
+$11: Note off FM channel #2
+$12: Note off FM channel #3
+$14: Note off FM channel #4
+$15: Note off FM channel #5
+$16: Note off FM channel #6
+$18: Note off PSG channel #1
+$19: Note off PSG channel #2
+$1A: Note off PSG channel #3
+$1B: Note off PSG channel #4
+
+    These events do a "note off" at the specified channel.
+
+$1C: Note off PCM channel
+
+    This event does a "note off" at the PCM channel. This means that any PCM
+    playback is immediately stopped. FM channel #6 is immediately enabled as
+    well.
+
+=============================================================================
+
+$20nn: Set volume FM channel #1
+$21nn: Set volume FM channel #2
+$22nn: Set volume FM channel #3
+$24nn: Set volume FM channel #4
+$25nn: Set volume FM channel #5
+$26nn: Set volume FM channel #6
+
+    These events set the volume of a specific FM channel. The event is
+    followed by a byte, which indicates the new volume. A value of $00 is the
+    loudest, a value of $7F is the quietest.
+
+$28nn: Set volume PSG channel #1
+$29nn: Set volume PSG channel #2
+$2Ann: Set volume PSG channel #3
+$2Bnn: Set volume PSG channel #4
+
+    These events set the volume of a specific PSG channel. The event is
+    followed by a byte, which indicates the new volume. A value of $00 is the
+    loudest, a value of $0F is the quietest.
+
+=============================================================================
+
+$30nnnn: Set frequency FM channel #1
+$31nnnn: Set frequency FM channel #2
+$32nnnn: Set frequency FM channel #3
+$34nnnn: Set frequency FM channel #4
+$35nnnn: Set frequency FM channel #5
+$36nnnn: Set frequency FM channel #6
+
+    These events set the raw frequency of a specific FM channel, without
+    triggering a new note. Meant for note slides. The following two bytes
+    specify the new frequency in the same format as the YM2612 expects. The
+    first byte is register +$A4, the second byte is register +$A0.
+    
+    Echo uses the following frequency values for each semitone:
+    
+        C  - 644 | E  - 810 | G# - 1021
+        C# - 681 | F  - 858 | A  - 1081
+        D  - 722 | F# - 910 | A# - 1146
+        D# - 765 | G  - 964 | B  - 1214
+
+$38nnnn: Set frequency PSG channel #1
+$39nnnn: Set frequency PSG channel #2
+$3Annnn: Set frequency PSG channel #3
+
+    These events set the raw frequency of a specific square wave PSG channel,
+    without triggering a new note. Meant for note slides. The following two
+    bytes specify the new frequency, the first byte containing the four least
+    significant bits (LSB aligned), and the next byte containing the six most
+    significant bits (LSB aligned too).
+
+    Echo uses the following frequency values for each semitone:
+    
+           |Oct.0|Oct.1|Oct.2|Oct.3|Oct.4|Oct.5
+        ---|-----|-----|-----|-----|-----|-----
+        C  | 851 | 425 | 212 | 106 |  53 |  26
+        C# | 803 | 401 | 200 | 100 |  50 |  25
+        D  | 758 | 379 | 189 |  94 |  47 |  23
+        D# | 715 | 357 | 178 |  89 |  44 |  22
+        E  | 675 | 337 | 168 |  84 |  42 |  21
+        F  | 637 | 318 | 159 |  79 |  39 |  19
+        F# | 601 | 300 | 150 |  75 |  37 |  18
+        G  | 568 | 284 | 142 |  71 |  35 |  17
+        G# | 536 | 268 | 134 |  67 |  33 |  16
+        A  | 506 | 253 | 126 |  63 |  31 |  15
+        A# | 477 | 238 | 119 |  59 |  29 |  14
+        B  | 450 | 225 | 112 |  56 |  28 |  14
+
+$3Bnn: Set noise type PSG channel #4
+
+    This event works like event $0Bnn, but it doesn't trigger a note attack
+    (i.e. instrument envelope won't be reset, note won't start playing if it
+    wasn't already).
+
+=============================================================================
+
+$40nn: Set instrument FM channel #1
+$41nn: Set instrument FM channel #2
+$42nn: Set instrument FM channel #3
+$44nn: Set instrument FM channel #4
+$45nn: Set instrument FM channel #5
+$46nn: Set instrument FM channel #6
+
+    These events are used to set the instrument to be used by a specific FM
+    channel. The event is followed by a byte, which has an index in the
+    pointer list that indicates where's the FM instrument data. Instruments
+    are stored as EIF (Echo Instrument Format).
+
+$48nn: Set instrument PSG channel #1
+$49nn: Set instrument PSG channel #2
+$4Ann: Set instrument PSG channel #3
+$4Bnn: Set instrument PSG channel #4
+
+    These events are used to set the instrument to be used by a specific PSG
+    channel. The event is followed by a byte, which has an index in the
+    pointer list that indicates where's the PSG instrument data. Instruments
+    are stored as EEF (Echo Envelope Format).
+
+=============================================================================
+
+$E0: Lock FM channel #1 [SFX ONLY]
+$E1: Lock FM channel #2 [SFX ONLY]
+$E2: Lock FM channel #3 [SFX ONLY]
+$E4: Lock FM channel #4 [SFX ONLY]
+$E5: Lock FM channel #5 [SFX ONLY]
+$E6: Lock FM channel #6 [SFX ONLY]
+$E8: Lock PSG channel #1 [SFX ONLY]
+$E9: Lock PSG channel #1 [SFX ONLY]
+$EA: Lock PSG channel #1 [SFX ONLY]
+$EB: Lock PSG channel #1 [SFX ONLY]
+
+    These events are used to "lock" specific channels. When a channel is
+    locked, BGM can't mess up with it. All channels used by a SFX must be
+    locked before they're used. Channels get unlocked when the SFX stream is
+    over.
+    
+    To lock the PCM channel, you need to lock FM channel #6 (event $E6). Echo
+    will behave accordingly.
+
+=============================================================================
+
+$F0: Set parameters FM channel #1
+$F1: Set parameters FM channel #2
+$F2: Set parameters FM channel #3
+$F4: Set parameters FM channel #4
+$F5: Set parameters FM channel #5
+$F6: Set parameters FM channel #6
+
+    These events set up some miscellaneous parameters for the FM channels.
+    The event is followed by a byte, which speficies the new parameters to be
+    used. The format of this byte is as follows:
+    
+        Bit 7 ..... 1 to enable left speaker, 0 to mute it
+        Bit 6 ..... 1 to enable right speaker, 0 to mute it
+        Bit 5-0 ... Must be 0
+
+=============================================================================
+
+$FC: Go to loop [BGM ONLY]
+$FD: Set loop point [BGM ONLY]
+
+    This event are used in BGM streams to loop music. Put event $FD where the
+    loop starts, and then end the stream using event $FC (don't use event
+    $FF). This will tell Echo to loop the song instead of stopping playback.
+
+$FEnn: Delay ticks
+
+    This event is used for timing. It tells Echo to wait a specific amount of
+    ticks before continuing with the stream. A byte follows this event, it's
+    the amount of ticks to wait. If it's $00, then Echo waits 256 ticks
+    instead.
+    
+    If you need to wait more than 256 ticks, you can trigger this event
+    several times in a row. For example, to wait 320 ticks, use this event
+    twice: $FE00FE40 --> 256 ticks + 64 ticks = 320 ticks.
+    
+    One tick lasts 1/60th of a second.
+
+$FF: Stop playback
+
+    This event indicates the end of the stream and tells Echo to stop
+    playback from this stream. If the stream was a SFX, then any locked
+    channels will be unlocked as well.
+
+=============================================================================
diff --git a/doc/ewf.txt b/doc/ewf.txt
new file mode 100644
index 0000000..e83dbbe
--- /dev/null
+++ b/doc/ewf.txt
@@ -0,0 +1,15 @@
+=============================================================================
+
+OVERVIEW
+
+    EWF stands for "Echo Waveform Format" and it's the format in which PCM
+    instruments are stored.
+
+FORMAT
+
+    There isn't much to it. PCM data is stored as unsigned 8-bit, 10250 Hz,
+    mono. The bytes specifying the waveform data contain values ranging from
+    $00 to $FE. When a byte with value $FF is found, this is the end of the
+    waveform.
+
+=============================================================================