# OutRunners (MAME set 'orunners') - Z80 sound program symbols (epr-15550.ic31)
#
# Addresses and names only: no game data lives in this file.
# Format:  ADDRESS  KIND  NAME  [...]   [# comment]
#   func     a function entry
#   loop     the main loop's top: the program waits there for the board (a function entry)
#   code     a code label
#   jumps    NAME COUNT: a table of COUNT 16-bit code addresses
#   via      TABLE: the JP (HL), JP (IX) or JP (IY) at ADDRESS goes to an entry of TABLE
#   data     where a piece of data starts
# Addresses are the Z80's: 0000-9FFF is the start of the sound ROM, A000-BFFF a banked page of it (ports
# A0-AF), C000-DFFF the MultiPCM, E000-FFFF the RAM shared with the V70 (V70 700000-701FFF).
#
# Names for the decompiled C (tools/decompile_sound.py), as symbols.txt has them (disassemble.load_names):
#   ADDRESS  var    NAME TYPE [STRUCT]   a variable in the shared RAM (TYPE: u8 s8 u16 s16); a struct name
#                                        after the type: it holds the address of one
#   ADDRESS  table  NAME TYPE            data in the program ROM the code reads by index, TYPE per element
#   ADDRESS  io     NAME TYPE            a place of the MultiPCM's window, read and written through the bus
#   ADDRESS  port   NAME                 an I/O port
#   struct   NAME   SIZE                 a structure in the shared RAM (SIZE in hexadecimal)
#   array    STRUCT FIRST COUNT          COUNT of them one after another from FIRST (COUNT in decimal)
#   field    STRUCT OFFSET NAME TYPE [STRUCT]  one of its fields
#   param    FUNCTION REGISTER NAME      what a function takes or hands back in a register (bc, de, hl, ix,
#                                        iy, a)
#   result   FUNCTION REGISTER NAME      what a function nothing calls hands back in a register
#   local    FUNCTION WHERE REGISTER NAME  the local variable that holds what the instructions at WHERE
#                                        write in REGISTER; "entry" is what it holds when the function starts
# build/sound/listing.s and build/sound/index.txt (written with the C) are what naming works from.

# Functions and labels
0000  func  sound_reset          # DI; JP 0100 (name kept: runtime/src/sound_cpu.c calls it)
0038  func  sound_irq            # IM 1: the YM3438's timer; acknowledges the inputs (C1 = 0), rearms timer A (27 = 15) (name kept: sound_cpu.c calls it)
0100  code  sound_main           # IM 1, SP = FDFF, clears E000-FDFF, maps the interrupt inputs (D0-D2), sound_init, EI, then the loop
012D  loop  sound_main_loop      # waits while FFFF is not 0, then the main loop's calls (name kept: sound_cpu.c calls it)

# ======== the sound program's names (naming batch S) ========
#
# What the program is (read from build/sound/listing.s, the C and the ROM's tables): one driver for the two
# screens. Screen 1's sound commands (the V70's 700700, Z80 E700) start sequences on screen 1's eight sequence
# players (E900 the music, EA00-F000 the effects), which write MIDI messages into screen 1's queue E100-E1FF;
# screen 2's (700800, E800) do the same with the players F100-F800 and the queue E200-E2FF. Two copies of the
# MIDI handlers (screen 1's at 0372/03D3, screen 2's at 0BAD/0C0E) play both queues on one pool of 30 voice
# records (E410-E51D: 24 MultiPCM voices, then the YM3438's 6 channels), flags bit 3 marking screen 2's;
# screen 1's sound goes out on the right (MultiPCM pan 70, YM3438 B4 40), screen 2's on the left (pan 90,
# B4 80), screen 2's notes playing the samples from 100 on. Each screen also has an engine (MultiPCM voices 26
# and 27) and a tyre noise (24 and 25) the V70 drives itself through its page (E710-E71D, E810-E81D).
# "Screen 1" and "screen 2" are the game's words (symbols.txt: SOUND_700700 for screen 1, 700800 for
# screen 2); the test mode calls them MONITOR A and B.

# ======== functions (the 57 sound_XXXX) ========

0158  func  drum_timeout_tick
comment drum_timeout_tick The drum notes' time-out, on every timer tick: drum_timeout_wait counts 140 ticks, then a pass (drum_timeout_pass bit 0) visits the 24 MultiPCM voices, one a tick (drum_timeout_cursor, drum_timeout_voices_left): each one's drum_timeout goes down by one, and a sounding drum note (flags bits 6 and 4) whose count runs out, and that is not being stopped already, gets the stop flag (flags bit 0) for stop_flagged_voices. Instrument notes are counted down too, but never stopped by it.

01B4  func  sound_init
comment sound_init Sets the sound up at reset: the MultiPCM (init_pcm_chip) and the YM3438 (init_fm_chip); both screens' MIDI queues empty (screen_1_midi_write 0, screen_1_midi_read and screen_2_midi_read FF), next_voice the first voice, screen_1_tick_countdown 1, drum_timeout_wait 140 ticks, both music volumes FF; the voices' chip channels (init_voice_channels) and both screens' parts (init_parts); last, YM3438 register 27 = 15: timer A loaded and its interrupt on.

01ED  func  init_fm_chip
comment init_fm_chip Sets the YM3438 up: fm_global_init's 11 pairs on part I (the LFO on, timer A 3F0 and timer B FF, all six channels keyed off, the DAC off), then fm_operator_init's 36 pairs on both parts (every operator silent: total level 7F, release FF, no SSG-EG).

0212  func  write_fm_channel
comment write_fm_channel Writes value to the YM3438 register fm_register on the part fm_channel's bit 2 picks (write_fm_part2 when it is set, else write_fm); hands fm_register back with value in its high byte.

021C  func  write_fm
comment write_fm Writes value to the YM3438's register fm_register on part I (FM_ADDRESS, then FM_DATA), with the interrupts off between the two.

0228  func  write_fm_part2
comment write_fm_part2 Writes value to the YM3438's register fm_register on part II (FM_PART2_ADDRESS, then FM_PART2_DATA), with the interrupts off between the two.

0292  func  init_pcm_chip
comment init_pcm_chip Sets the MultiPCM up: 3 into its place C009 before and after (what for is not known: the chip as MAME has it ignores it), PCM_BANKS 1A (the first sample window on bank 2, the second on bank 3), then for the first 28 entries of voice_chip_channels: the voice selected, pan 80, keyed off, level FE (silent). The last 4 of those 28 are YM3438 codes (80-82, 84), so MultiPCM voices 0-2 and 4 are set up twice and voices 24-27 (the tyre noises' and the engines') not at all.

02CA  func  write_pcm_register
comment write_pcm_register Writes value to the register pcm_register of the MultiPCM voice selected in pcm_voice_select: waits while the chip is busy (pcm_data bit 0), puts the register number in pcm_register_select, waits again, then the value in pcm_data.

0302  func  init_voice_channels
comment init_voice_channels Gives the 30 voices their chip_channel from voice_chip_channels: voices 0-23 the MultiPCM voices (00-06, 08-0E, 10-16, 18-1A), voices 24-29 the YM3438's channels (80-82 on part I, 84-86 on part II).

0316  func  init_parts
comment init_parts Sets both screens' 13 parts from sound set 0 (part_templates[0]): its 8 music parts and, after its bank byte, the 5 parts of MIDI channels A-E (the effects' and the fades'), for screen 1 (midi_part 0-12) and screen 2 (midi_part 13-25); then every part's effective_volume: volume x (FF with flags bit 0, else screen_1_music_volume, for screen 2's parts too) / 256, + 1 if not 0. The set's bank byte does not go to PCM_BANKS here.

0366  func  read_table_word
comment read_table_word Hands back the 16-bit entry 'entry' of the table of words at 'table'.

0372  func  handle_midi_message_screen_1
comment handle_midi_message_screen_1 Takes one message off screen 1's MIDI queue each main loop pass, while screen_1_midi_count is not 0: its first byte (read_midi_byte_screen_1) is a new screen_1_midi_status, or a data byte under the last one; every part of screen 1 that plays (flags bit 7) on the message's channel gets it (play_midi_message_screen_1), each reading from the same place (screen_1_midi_read is put back after each); then skip_midi_data_screen_1 moves past the message.

03B7  func  skip_midi_data_screen_1
comment skip_midi_data_screen_1 Moves screen_1_midi_read to the last byte of the message that starts with first_byte: past a status byte, then past one data byte for C0 and D0 (program change, channel pressure) and two for the others. play_midi_message_screen_1 does the same for A0 and D0, which play nothing (handle_midi_message_screen_1 puts the place back and skips the message itself).

03D3  func  play_midi_message_screen_1
comment play_midi_message_screen_1 Plays one MIDI message of screen 1's queue for part, by screen_1_midi_status: 90 note on (velocity 0: note off): note_number (+ transpose) and its note_code, note_level from the velocity; a drum kit (program F0 on, drum_kits) gives drum_pitch, the drum_timeout and the sample (FF: no sound), and on channel 15 notes 2A and 2C (closed and pedal hi-hat) stop screen 1's open hi-hat (note code CA); an FM instrument (instruments' flags bit 1) takes a free FM voice for start_fm_note; else the instrument's key split for note_number gives sample_or_patch, split_tune and split_octave; the MultiPCM voice is the next free one from next_voice, or the oldest (allocation_order 0) taken over; its record (flags 40, + 10 for a drum note), then the pitch, the sample, the level (x the part's effective_volume), pan 70 (right) and key on. 80 note off: drum notes ignore it; the sounding voice of the note on the channel gets the stop flag (an FM one is freed and keyed off), or is held (flags bit 1) while the sustain pedal is down. E0 pitch bend: through bend_range_tables[bend_range] into pitch_bend and screen_1_pitch_bends, the channel's sounding voices retuned. B0 control change: 1 modulation (set_voice_modulation_screen_1), 7 the part's volume, 10 screen_1_music_volume for the 8 music parts, 40 sustain pedal, 7B all notes off, 50 stops all of the screen's MultiPCM voices (7E: all but drum notes on channels other than 15) and clears its channels' controls and half of their pitch bends, 20 a sound set (part_templates: the 8 music parts and screen 1's sample bank), 51 stops one note; a new volume reaches the sounding voices at once. C0 program change. A0 and D0 skipped.
comment cut_open_hi_hat_screen_1 A closed or pedal hi-hat (notes 2A and 2C on channel 15) stops screen 1's open hi-hat: each MultiPCM voice of screen 1 (flags bit 6, not bit 3) on channel 15 playing note code CA gets the stop flag (bit 0); then take_voice_screen_1 for the new note.
comment take_voice_screen_1 A MultiPCM voice for a note of screen 1 (play_midi_message_screen_1 and cut_open_hi_hat_screen_1 go on to it): the next free one from next_voice (reset_next_voice past the last), or else the oldest (allocation_order 0) taken over, the others' orders one down (none: no note); its record (flags 40, + 10 and the drum_timeout for a drum note), then the pitch (an instrument's through pcm_pitch_tables, with its channel's pitch bend, split_tune and split_octave; a drum's drum_pitch), the sample, the level (x the part's effective_volume), pan 70 (right) and key on.
comment release_note_screen_1 Releases a note of screen 1 (note off, or a note on at velocity 0: play_midi_message_screen_1 goes on to it): drum notes (program F0 on) ignore it; the voice playing the note on its channel (an FM voice for an FM instrument, else a MultiPCM one; screen 1's, sounding, not held) is held (flags bit 1) while the channel's sustain pedal is down, else the MultiPCM voice gets the stop flag (bit 0) and the FM voice is freed and keyed off.

06E3  func  retune_voice_screen_1
comment retune_voice_screen_1 Retunes a sounding voice after a pitch bend of screen 1: an FM voice through retune_fm_voice; a MultiPCM voice gets its note's pitch again from pcm_pitch_tables[semitone] at pitch_bend + its tune, its octave + octave_shift (registers 3 and 2). The same code as retune_voice_screen_2.

07BC  func  set_voice_modulation_screen_1
comment set_voice_modulation_screen_1 CC 1 of screen 1 for a sounding voice of the channel: a MultiPCM voice gets register 6 = voice_modulation | the part's lfo_frequency. For an FM voice the program means B4 = 40 | the depth, but takes the channel from voices_left, the caller's count of voices left, instead of the voice's chip_channel, and write_fm_channel hands the value back where that count was, so the caller's walk goes on past the 30 voices.

0A39  func  read_midi_byte_screen_1
comment read_midi_byte_screen_1 Moves screen_1_midi_read on by one and hands back the byte of screen_1_midi_queue there.

0A43  func  stop_flagged_voices
comment stop_flagged_voices Stops the MultiPCM voices flagged to stop (flags bit 0), first thing each main loop pass: the voice is freed (flags and midi_channel 0) and keyed off; unless it was a drum note on a channel other than 15 (which has no allocation order), pcm_voices_used goes down by one and the voices allocated after it move one down.

0B77  func  multiply_bytes
comment multiply_bytes Hands back the high byte of value times the low byte of factor (8 x 8 bits, shift and add); the callers keep the product's high byte: a level or a volume scaled by another.

0BA6  func  reset_next_voice
comment reset_next_voice Puts next_voice back on the first voice and hands it back: the free voice search wraps after the 24 MultiPCM voices.

0BAD  func  handle_midi_message_screen_2
comment handle_midi_message_screen_2 As handle_midi_message_screen_1 for screen 2: screen_2_midi_count, screen_2_midi_status, screen_2_midi_read, screen 2's parts (midi_part 13-25), play_midi_message_screen_2 and skip_midi_data_screen_2.

0BF2  func  skip_midi_data_screen_2
comment skip_midi_data_screen_2 As skip_midi_data_screen_1 on screen_2_midi_read and screen_2_midi_status.

0C0E  func  play_midi_message_screen_2
comment play_midi_message_screen_2 As play_midi_message_screen_1 for screen 2's queue and parts: its voices get flags bit 3 (48), and it only touches voices with that bit (screen 1's only those without); its notes play the samples from 100 on (MultiPCM register 2 bit 0) on the left (pan 90; FM B4 80); its channels' state is screen_2_channel_controls and screen_2_pitch_bends; CC 10 sets screen_2_music_volume and CC 20 screen 2's sample bank (pcm_banks bits 3-5).
comment cut_open_hi_hat_screen_2 As cut_open_hi_hat_screen_1 for screen 2's voices (flags bit 3); then take_voice_screen_2.
comment take_voice_screen_2 As take_voice_screen_1 for a note of screen 2 (play_midi_message_screen_2 and cut_open_hi_hat_screen_2 go on to it): its voice gets flags bit 3 (48), plays the samples from 100 on and pans left (90).
comment release_note_screen_2 As release_note_screen_1 for screen 2's voices (flags bit 3) (play_midi_message_screen_2 goes on to it).

0F20  func  retune_voice_screen_2
comment retune_voice_screen_2 The same code as retune_voice_screen_1, for screen 2's pitch bend.

0FF8  func  set_voice_modulation_screen_2
comment set_voice_modulation_screen_2 As set_voice_modulation_screen_1 for screen 2 (FM: 80 | the depth, with the same mistake over the channel and the caller's count).

127B  func  read_midi_byte_screen_2
comment read_midi_byte_screen_2 Moves screen_2_midi_read on by one and hands back the byte of screen_2_midi_queue there.

12E0  func  start_fm_note
comment start_fm_note The FM note on's chip side: the F-number of the note's semitone from fm_fnum_tables at the channel's pitch bend (pitch_bends[midi_channel]) and the block from its octave (A4, A0); the patch (load_fm_patch, or load_fm_patch_part2 for a channel of part II); the 4 operators' total levels (fm_level_registers): a patch level with bit 7 as it is, the others plus note_level; B4 = voice_modulation (the output side and the modulation depth); all four operators keyed on (28 = F0 | fm_channel).

13D8  func  retune_fm_voice
comment retune_fm_voice Retunes an FM voice after a pitch bend: fm_channel from its chip_channel, the F-number of its note from fm_fnum_tables at pitch_bend and the block from its octave (A4, then A0, on its part).

1449  func  stop_fm_voice
comment stop_fm_voice Frees an FM voice (flags and midi_channel 0) and keys its channel off (28): the sustain pedal's release of an FM note it held.

145A  func  apply_fm_music_volume
comment apply_fm_music_volume CC 10 for a sounding FM voice (part in iy): note_level = 7F - its level x the part's effective_volume / 2, then the patch's operator levels without bit 7 plus note_level (write_fm_channel); those with bit 7 are left alone. It reads the patch number from the instrument's byte 1, where every FM instrument has 7F (the note on reads byte 2), so the levels come from past the 32 patches of fm_patches.

14A8  func  apply_fm_channel_volume
comment apply_fm_channel_volume As apply_fm_music_volume for CC 7 (part in ix), with the same patch number mistake.

14F6  func  load_fm_patch
comment load_fm_patch Writes the 21 registers of fm_patches[sample_or_patch] (fm_patch_registers plus the channel within the part) on part I; hands back the channel in channel_in_part, fm_level_registers in register_list and the patch's 4 operator levels in patch_data.

1515  func  load_fm_patch_part2
comment load_fm_patch_part2 As load_fm_patch on part II.

36AD  func  update_engine_screen_1
comment update_engine_screen_1 Screen 1's engine on MultiPCM voice 26 (selected as 1D), each main loop pass while screen_1_engine_requests is set: revs 0 key it off (when screen_1_engine_state bit 7 says it is on) and clear the requests; else it is keyed on first (pan 70, key_on_with_pan), then the requests are done and cleared: bit 6 nothing on screen 1, bit 7 the sample (set_engine_sample with screen_1_engine_sample), bit 5 the pitch and level for screen_1_engine_revs (set_engine_pitch with screen_1_engine_loudness).

36F6  func  update_engine_screen_2
comment update_engine_screen_2 As update_engine_screen_1 for screen 2 on voice 27 (1E), pan 90; its bit 6 sets the level to screen_2_engine_loudness x 2.

3748  func  key_on_with_pan
comment key_on_with_pan Sets the selected MultiPCM voice's pan (register 0) and keys it on.

376D  func  set_engine_pitch
comment set_engine_pitch The engine's sound for the revs (high byte of revs_and_loudness): the pitch engine_pitches[revs] (registers 3 and 2), with a random amount (the refresh register) added where its octave is negative (revs below A2); the level engine_levels[revs] - the loudness (low byte); a random LFO (register 6) and tremolo depth 1 (register 0A).

37B5  func  set_engine_sample
comment set_engine_sample Gives the selected MultiPCM voice its sample (register 1, which loads the sample's envelope and LFO), register 2 cleared first so that it is one of the first 256.

3AF3  func  engine_sweep_tick
comment engine_sweep_tick On every timer tick: while engine_sweep_on is set, every 65 ticks screen 1's engine plays the next revs of engine_sweep_revs (screen_1_engine_revs with a pitch request), up the table, then back down (engine_sweep_down turns at its ends). Nothing sets engine_sweep_on, so in the game it only turns engine_sweep_down and the position over every tick.

3DE6  func  update_tyre_noise_screen_1
comment update_tyre_noise_screen_1 Screen 1's tyre noise on MultiPCM voice 24 (selected as 1B), each main loop pass: a request (screen_1_tyre_noise, 1-8) is taken and cleared: screen_1_tyre_noise_time = the noise's duration and, unless its sample plays already (screen_1_tyre_noise_sample), start_tyre_noise with pan 70; without one, unless the noise is off (screen_1_tyre_noise_off), the time counts down by one a pass and at 0 the noise is keyed off.

3E36  func  update_tyre_noise_screen_2
comment update_tyre_noise_screen_2 As update_tyre_noise_screen_1 for screen 2 on voice 25 (1C), pan 90.

3E86  func  start_tyre_noise
comment start_tyre_noise Starts a tyre noise on the selected MultiPCM voice: the page's tyre_noise_off cleared, the noise's sample (register 1, also into tyre_noise_sample), level, pan, pitch (register 3) and key on.

3EED  func  sequence_tick
comment sequence_tick The sequence players' step, on every timer tick: screen_1_tick_countdown runs 4 to 1 and picks a group, each stepped once in four ticks (step_player): at its wrap screen 2's seven effect players (fade_player_volume on the first of them before), at 3 screen 2's music player (fade_music_volume before), at 2 screen 1's seven effect players, at 1 screen 1's music player; a group waits while its screen's MIDI queue holds 64 messages or more.

3FC2  func  playlist_command
comment playlist_command A playlist byte F0-FF, through playlist_command_table by its low nibble: F0 (and F3-FD) jumps to the playlist address that follows and hands back the byte there (the next song); F1 and F2 hand back song 90 + (playlist_choice_1 or playlist_choice_2 & 7); FE clears the player (it stops); FF clears all 8 of the screen's players (the screen by the queue's page) and hands back 0, which stops it.

403E  func  step_player
comment step_player Steps a playing sequence player (flags bit 7): its delta time (delta_time_high, delta_time_low) counts down, and at 0 the events from position on, in its bank (ROM_BANK), go into the screen's MIDI queue at queue_pointer, one more in the page's midi_count for each: a status byte is kept in running_status (a data byte reuses it); 80 note off with velocity 7F; B0 control change, controller 10's value kept in fade_volume or, while a fade runs, replaced by it; C0 and D0 two bytes; 90, A0 and E0 three. FF meta events: 2F ends the sequence, 51 its value into meta_51_value, the others are skipped; F0 and F7 system exclusive are skipped but counted as a message; F1-FE end the sequence. After an event a data byte with bit 7 (chain_next_event) or a delta of 0 reads the next one at once; else the delta (one byte, or two with bit 7: 7 bits each) waits. At the end a player with a playlist (flags bit 5) starts its next playlist entry at once (playlist_command for F0-FF; start_song, or start_sound with flags bit 4); 0, or no playlist, stops it.

4097  func  chain_next_event
comment chain_next_event A data byte with bit 7 set: hands it back without the bit and sets the player's flags bit 6, so that the next event is read at once, with no delta time.

41D2  func  clear_player_end_flag
comment clear_player_end_flag Clears the screen page's player_end_flag as a player with flags bit 4 stops; nothing reads it, nothing sets it.

41F2  func  poll_sound_commands
comment poll_sound_commands Each main loop pass: a sound command in screen_1_command starts from screen 1's music player, one in screen_2_command from screen 2's (take_sound_command).

420F  func  take_sound_command
comment take_sound_command Clears the screen's command byte and starts the command (start_sound).

4211  func  start_sound
comment start_sound Starts sound command 'command' (sound_commands) from the screen's music player at player_address, by its header's flags: an effect (bit 7) goes to the screen's effect player two pages on or, with bit 6, to the channel player its first event's channel picks (select_channel_player), unless that player plays one of higher priority (flags bits 0-3): it is cleared, takes the header's flags and plays the sequence right after them; bit 6 alone plays that on the music player as it is (no command has it); bit 5 a sequence (start_sequence: the header's bank and address); else a playlist: the player cleared, flags bit 5, the playlist after its first song, which start_song starts. The game's commands: 00-1D and E0-FB playlists, 1E stops the music, 1F silences the screen, 20-8F an effect note on channel E, 90-BF the channel players' effects, C0-CF sequences, D0-DB a sound set (CC 20), DC-DF and FC-FE channel A's and stop controls.

4238  func  start_song
comment start_song Starts song 'song' (songs) on the player: start_sequence with its record.

4256  func  start_sequence
comment start_sequence The player plays the sequence of a song record or of a sound header (its flags byte skipped): its bank (byte 1) and address (bytes 2-3), delta_time_low 1, flags bit 7; nothing else of the player changes.

42C8  func  select_channel_player
comment select_channel_player Moves player_address from the first channel player to the one of the effect's channel: as many pages on as the low nibble of the header's first event (its status byte, channel A-E) less 0A.

42D3  func  clear_player
comment clear_player Clears the player's bytes 00-30 (flags to playlist_high) and hands back its address.

42E2  func  fade_music_volume
comment fade_music_volume The music player's fade, while its fade_speed is set (the V70's fade_out_music_at writes it): every fade_speed + 1 calls (fade_wait) fade_volume goes down by one and out as CC 10 on channel E (the screen's music volume); at 0 the player stops (flags bit 7), fade_speed is cleared, and CC 50 7E (the music's voices stop) and CC 79 0 (which nothing handles) go out on channel E.

433A  func  fade_player_volume
comment fade_player_volume The same for the player after the music player, with fade_channel_volume going out as CC 7 on channel A; at 0 the player is cleared (flags 0) and CC 7B 0 (all notes off) goes out on channel A. Nothing sets that player's fade_speed, and no command starts that player.

4387  func  next_sequence_byte
comment next_sequence_byte Moves the sequence position on by one; past the bank window (C000) the player's bank goes one on (ROM_BANK) and the position back to A000.

comment sound_reset The sound CPU's start: interrupts off, the shared RAM E000-FDFF cleared (from shared_ram_start), the interrupt inputs mapped (IRQ_VECTOR0_INPUT-IRQ_VECTOR2_INPUT: 0 the YM3438's timers, 1 the V70's request, 2), the pending ones cleared, none masked, sound_init, then interrupts on.
comment sound_irq The timer interrupt (the YM3438's timer A): acknowledges the pending inputs, rearms the timer (register 27 = 15), then sequence_tick, drum_timeout_tick and engine_sweep_tick.
comment sound_main_loop One pass of the main loop: waits, interrupts off, while sound_cpu_hold is set; then stop_flagged_voices, one message of each screen's MIDI queue (handle_midi_message_screen_1 and _screen_2), both engines, both tyre noises and poll_sound_commands.

# ======== code labels (the handlers inside the functions; the listing and the C's labels) ========

017B  code  drum_timeout_step
03FC  code  note_on_screen_1
0461  func  cut_open_hi_hat_screen_1
0493  code  find_key_split_screen_1
04B7  func  take_voice_screen_1
04D9  code  steal_oldest_voice_screen_1
04FD  code  start_voice_screen_1
054A  code  start_instrument_voice_screen_1
05AD  code  write_note_registers_screen_1
05E1  code  note_off_screen_1
05FC  func  release_note_screen_1
065C  code  pitch_bend_screen_1
0730  code  program_change_screen_1
073C  code  control_change_screen_1
0772  code  modulation_screen_1
07DB  code  sustain_pedal_screen_1
0838  code  music_volume_screen_1
08BB  code  channel_volume_screen_1
092F  code  stop_voices_screen_1
0961  code  stop_music_voices_screen_1
098C  code  select_sound_set_screen_1
09D1  code  stop_note_screen_1
0A0C  code  all_notes_off_screen_1
0A7D  code  renumber_voice_orders
0C37  code  note_on_screen_2
0C9C  func  cut_open_hi_hat_screen_2
0CCE  code  find_key_split_screen_2
0CF2  func  take_voice_screen_2
0D14  code  steal_oldest_voice_screen_2
0D38  code  start_voice_screen_2
0D85  code  start_instrument_voice_screen_2
0DE8  code  write_note_registers_screen_2
0E1E  code  note_off_screen_2
0E39  func  release_note_screen_2
0E99  code  pitch_bend_screen_2
0F6C  code  program_change_screen_2
0F78  code  control_change_screen_2
0FAE  code  modulation_screen_2
1017  code  sustain_pedal_screen_2
1074  code  music_volume_screen_2
10F7  code  channel_volume_screen_2
116B  code  stop_voices_screen_2
119D  code  stop_music_voices_screen_2
11C8  code  select_sound_set_screen_2
1213  code  stop_note_screen_2
124E  code  all_notes_off_screen_2
1289  code  fm_note_on_screen_1
137D  code  fm_note_off_screen_1
1434  code  fm_modulation_screen_1
177D  code  fm_note_on_screen_2
17D7  code  fm_note_off_screen_2
1832  code  fm_modulation_screen_2
37C3  code  engine_off_screen_1
37DB  code  engine_off_screen_2
3B35  code  engine_sweep_turn
3EB3  code  key_off_tyre_noise_screen_1
3ED0  code  key_off_tyre_noise_screen_2
3F04  code  step_music_screen_1
3F21  code  step_effects_screen_1
3F62  code  step_music_screen_2
3F7F  code  step_effects_screen_2
3FCC  code  playlist_jump
3FD4  code  playlist_chosen_song_1
3FDD  code  playlist_chosen_song_2
3FE6  code  playlist_stop_player
3FF7  code  playlist_clear_all_players
4056  code  read_events
4066  code  next_event
409E  code  control_change_event
40D4  code  note_off_event
40EF  code  three_byte_event
40F6  code  two_byte_event
410D  code  system_event
411B  code  unknown_system_event
4134  code  running_status_event
413B  code  meta_event
4158  code  read_delta_time
418A  code  end_of_sequence
41C3  code  stop_at_end
41D7  code  meta_51_event
4243  code  start_playlist
426D  code  start_effect
427E  code  start_header_sequence
428D  code  start_channel_effect

# ======== jump table (renamed) ========

401E  jumps  playlist_command_table 16
3FCB  via    playlist_command_table

# ======== data ========

3B5D  data  engine_sweep_revs
479F  data  playlist_stop_music
47A3  data  playlist_silence_screen
595D  data  stop_music_sequence
596E  data  stop_screen_voices_sequence

# ======== the sound data's pieces (the assets: assets/sound/data, sound_formats.json) ========
# What is not the code: data and banked lines cut the chip into pieces, each in its format; 'banked' lines
# are offsets in the chip (A000 and up: bank * 2000h + the address in the A000-BFFF window - A000h). The
# unused_ pieces are what nothing reads (unreached code, padding, copies no command points at).

0004  data    unused_restart_entries              # 0004-0037, zeros (NOPs) where the Z80's RST 08h-30h land: nothing in the program executes RST, so nothing reaches them
005F  data    unused_nmi_entry                    # zeros (NOPs), then at 0066, the Z80's NMI entry, RETN: nothing in the program reaches it
0068  data    unused_music_demo_loop              # code nothing calls (0068-00AB): every 8 calls (E781) counts E782 down from 20h; at 0 it starts, in turn, the first command of unused_demo_commands (14) on screen 1 (screen_1_command) and the music's fade (the music player's fade_speed = 0E)
00AC  data    unused_demo_commands                # 14 13 12 11 10, seven times: unused_music_demo_loop reads its first byte
00CF  data    unused_zeros_00CF                   # zeros up to sound_main (0100)
072F  data    unused_return_072F                  # a RET no code reaches, between retune_voice_screen_1 and program_change_screen_1
0A9B  data    unused_midi_uart                    # code nothing calls (0A9B-0B76): MIDI through a USART at ports F0 (data) and F1 (status, commands; set up as an 8251: 00 00 00 40, mode 4E, command 37): the bytes it receives (but F0-FF) go into screen 2's MIDI queue (E200, screen 2's midi_write and midi_count), and screen 1's queue goes out through it
0BA2  data    unused_loop_0BA2                    # LD A,A; JP 0BA2: a loop no code reaches, after multiply_bytes
0F6B  data    unused_return_0F6B                  # a RET no code reaches, between retune_voice_screen_2's end and program_change_screen_2
1285  data    unused_loop_1285                    # LD A,A; JP 1285: a loop no code reaches, after read_midi_byte_screen_2
154D  data    unused_fm_fnum_pointers             # fm_level_registers + 4 (the code reads its 4 registers): 12 pointers in the shape of fm_fnum_tables' (157D eleven times, then 159D); nothing reads them
2096  data    unused_pcm_pitch_pointers           # velocity_levels + 80 (the velocity is 00-7F): 12 pointers in the shape of pcm_pitch_tables', at the runs an octave below (20C6-2226); nothing reads them
42B2  data    unused_lowest_flags_player          # code nothing calls (42B2-42C7): of the player at HL and the two after it, the address of the one whose first byte (its flags) is lowest, into E770
4382  data    unused_return_4382                  # NOP x4, RET: no code reaches it, before next_sequence_byte

46DB  data    playlist_stop_music_2               # command FD: as playlist_stop_music
46DF  data    playlist_magical_sound_shower       # commands 00, 01: Magical Sound Shower (radio song 0)
46FD  data    playlist_passing_breeze             # command 02: Passing Breeze (radio song 1)
4712  data    unused_playlist_songs_1a_1e         # a playlist no command points at: songs 1A-1E twice, then 1E over and over
4720  data    playlist_picture_the_rivers         # command 04: Picture the Rivers (radio song 3)
4736  data    playlist_blow_your_cool             # commands 05, 14: Blow Your Cool (radio song 4; also command 14)
474A  data    playlist_looking_for_the_rainbow    # commands 06, 15: Looking for the Rainbow (radio song 5; also command 15)
4757  data    playlist_speed_king                 # commands 07, 16: Speed King (radio song 6; also command 16)
476A  data    playlist_adventure                  # commands 08, 17: Adventure (radio song 7; also command 17)
4786  data    playlist_staff_credits              # commands 09, 18: the staff credits' music (staff_credits_code_watch, sound 9; also command 18)
478D  data    playlist_race_opening               # commands 0A, 19: the race opening's tune (race_opening_sound_cues, sound 0A; also command 19)
4790  data    playlist_meaning_of_the_light       # commands 0B, 1A, 1D: Meaning of the Light, the route map after a race short of the goal (game_mode_play step 12; also commands 1A, 1D)
4795  data    playlist_music_0c                   # commands 0C, 1B: command 0C (also 1B): no V70 code found that requests it, not in the sound test
4798  data    playlist_jingle_bell                # commands 0D, 1C: Jingle Bell (radio song 10; also command 1C)
47A7  data    playlist_sonic_control              # command 0E: Sonic Control (radio song 8)
47BE  data    playlist_mega_driver                # command 0F: Mega Driver, the car select's and the entry countdown's title music
47C4  data    playlist_dream_flying               # command 10: Dream Flying, at the goal (goal_update)
47CB  data    playlist_splash_wave                # commands 03, 11, 13: Splash Wave (radio song 2; also commands 11, 13)
47DB  data    playlist_last_wave                  # command 12: Last Wave (radio song 9)
47E4  data    unused_silence_playlists            # 11 copies of playlist_silence_screen no command points at
4810  data    playlist_station_fork_jingle        # command E0: the radio station's jingle as a fork nears (car_radio_update, sound E0)
4813  data    playlist_station_stage_09           # command E1: the radio station's music on route stage 9 (route_stage_radio_sounds)
481B  data    playlist_station_stages_15_18       # command E2: the radio station's music on route stages 15, 18 (route_stage_radio_sounds)
4823  data    playlist_station_stages_16_17       # command E3: the radio station's music on route stages 16, 17 (route_stage_radio_sounds)
4829  data    playlist_station_stage_11           # command E4: the radio station's music on route stage 11 (route_stage_radio_sounds)
482F  data    playlist_station_stages_13_20       # commands E5, F5: the radio station's music on route stages 13, 20 (route_stage_radio_sounds)
4834  data    playlist_station_stage_12           # commands E6, F6: the radio station's music on route stage 12 (route_stage_radio_sounds)
4839  data    playlist_station_stage_07           # commands E7, F7: the radio station's music on route stage 7 (route_stage_radio_sounds)
483E  data    playlist_station_stage_03           # commands E8, F8: the radio station's music on route stage 3 (route_stage_radio_sounds)
4843  data    playlist_station_stage_06           # commands E9, F9: the radio station's music on route stage 6 (route_stage_radio_sounds)
4849  data    playlist_station_stage_10           # commands EA, FA: the radio station's music on route stage 10 (route_stage_radio_sounds)
484E  data    playlist_unplayed_station_eb        # commands EB, FB: command EB: no route stage plays it (route_stage_radio_sounds), not in the sound test
4853  data    playlist_station_stage_01           # command EC: the radio station's music on route stage 1 (route_stage_radio_sounds)
4858  data    playlist_station_stage_05           # command ED: the radio station's music on route stage 5 (route_stage_radio_sounds)
485E  data    playlist_station_fork               # command EE: the radio station's music as a fork nears (car_radio_update, sound EE)
4863  data    playlist_station_stages_14_19       # command EF: the radio station's music on route stages 14, 19 (route_stage_radio_sounds)
4868  data    playlist_station_stage_08           # command F0: the radio station's music on route stage 8 (route_stage_radio_sounds)
486E  data    playlist_station_stage_02           # command F1: the radio station's music on route stage 2 (route_stage_radio_sounds)
4876  data    playlist_station_stage_04           # command F2: the radio station's music on route stage 4 (route_stage_radio_sounds)
487D  data    playlist_station_stage_00           # command F3: the radio station's music on route stage 0 (route_stage_radio_sounds)
4884  data    playlist_station_stages_21_30       # command F4: the radio station's music on route stages 21-30 (route_stage_radio_sounds)
488C  data    effect_20                           # command 20
4894  data    effect_21_game_start                # command 21: a game starts (game_mode_play step 0) and the race opening's cue at count 120
489C  data    effect_22                           # command 22
48A4  data    effect_23_stage_30_start            # command 23: as stage 30's road starts being built (one_shot_sound_update)
48AC  data    effect_24_checkpoint_leading        # command 24: a checkpoint passed in the lead, the stage end's first sound and race opening cues
48B4  data    effect_25                           # command 25
48BC  data    effect_26_after_crash               # command 26: 10 frames after a crash (crash tables' crash_sound)
48C4  data    effect_27_after_crash               # command 27: 10 frames after a crash (crash tables' crash_sound)
48CC  data    effect_28_checkpoint                # command 28: a checkpoint passed not in the lead (stage_end_sounds_update)
48D4  data    effect_29                           # command 29
48DC  data    effect_2a                           # command 2A
48E4  data    effect_2b_rival_alarm               # command 2B: the rival warning, twice (rival_alarm_update); a letter entered in the name entry in 1st place
48EC  data    effect_2c_name_entry_letter         # command 2C: a letter entered in the name entry in 2nd place (name_entry_place_sounds)
48F4  data    effect_2d_race_opening              # command 2D: the race opening's cues at counts 1 and 160; a letter entered in 3rd place
48FC  data    effect_2e_race_opening_2            # command 2E: the race opening's cue at count 150
4904  data    effect_2f                           # command 2F
490C  data    effect_30                           # command 30
4914  data    effect_31_crash                     # command 31: a crash's hit (crash tables' hit_sound), and the car landing after a crash's bounce (player_car_update)
491C  data    effect_32_crash_hit                 # command 32: a crash's hit (crash tables' hit_sound)
4924  data    effect_33_crash_hit                 # command 33: a crash's hit (crash tables' hit_sound)
492C  data    effect_34_crash_hit                 # command 34: a crash's hit (crash tables' hit_sound)
4934  data    effect_35                           # command 35
493C  data    effect_36_car_pass                  # command 36: a car going by: models 2 and 6 (car_pass_sounds)
4944  data    effect_37_car_pass                  # command 37: a car going by: models 1 and 7 (car_pass_sounds); a place changed with the car close
494C  data    effect_38_car_pass                  # command 38: a car going by: model 4 (car_pass_sounds)
4954  data    effect_39_car_pass                  # command 39: a car going by: models 3 and 5 (car_pass_sounds)
495C  data    effect_3a_car_pass                  # command 3A: a car going by: model 0 (car_pass_sounds); a place changed
4964  data    effect_3b                           # command 3B
496C  data    effect_3c                           # command 3C
4978  data    dj_message_31                       # command 3D: DJ message 31
4984  data    dj_message_32                       # command 3E: DJ message 32
4990  data    dj_message_33                       # command 3F: DJ message 33
499C  data    dj_goal_first                       # command 40: DJ message 34: at the goal in first place (goal_update)
49A8  data    dj_goal                             # command 41: DJ message 35: at the goal, not first (goal_update)
49B4  data    dj_time_up_36                       # command 42: DJ message 36: time up (player_car_update)
49C0  data    dj_time_up_37                       # command 43: DJ message 37: time up (player_car_update)
49CC  data    effect_44_dragon_dance              # command 44: the dragon dance at stage 22's goal (goal_parade_dragon_update)
49D4  data    effect_45                           # command 45
49DC  data    effect_46_matterhorn_crowd          # command 46: the scenery at the Matterhorn, stage 27 (sounding_scenery_update)
49E4  data    effect_47_pandas                    # command 47: the pandas at Beijing, stage 24 (sounding_scenery_update)
49EC  data    effect_48                           # command 48
49F4  data    effect_49_santa_sleigh              # command 49: Santa's sleigh over stage 26's goal (santa_sleigh_update)
49FC  data    effect_4a_cheering_crowd            # command 4A: the cheering group with banners in Japan, stage 23 (sounding_scenery_update)
4A04  data    effect_4b                           # command 4B
4A0C  data    effect_4c                           # command 4C
4A14  data    effect_4d                           # command 4D
4A1C  data    effect_4e                           # command 4E
4A24  data    effect_4f_ending                    # command 4F: the race's ending, when its objects are done (race_car_start_ending)
4A2C  data    effect_50                           # command 50
4A34  data    effect_51_jungle                    # command 51: the jungle of stage 3, repeated at random (ambient_sound_update)
4A3C  data    effect_52                           # command 52
4A44  data    effect_53_stage_end                 # command 53: 20 frames after the stage end's first sound (stage_end_sound_cues)
4A4C  data    effect_54                           # command 54
4A54  data    effect_55                           # command 55
4A5C  data    effect_56                           # command 56
4A64  data    effect_57                           # command 57
4A6C  data    dj_waiting                          # command 58: DJ message 3C: waiting for the race's other players (car_select_run)
4A74  data    effect_59                           # command 59
4A7C  data    effect_5a                           # command 5A
4A84  data    effect_5b                           # command 5B
4A8C  data    effect_5c                           # command 5C
4A94  data    effect_5d                           # command 5D
4A9C  data    dj_message_38                       # command 5E: DJ message 38
4AA4  data    dj_message_39                       # command 5F: DJ message 39
4AAC  data    effect_60_car_select_model_4        # command 60: car model 4 chosen in the car select (car_select_car_sounds)
4AB8  data    effect_61_car_select_model_2        # command 61: car model 2 chosen in the car select (car_select_car_sounds)
4AC4  data    effect_62_car_select_model_0        # command 62: car model 0 chosen in the car select (car_select_car_sounds)
4AD0  data    effect_63_car_select_model_6        # command 63: car model 6 chosen in the car select (car_select_car_sounds)
4ADC  data    effect_64_car_select_model_5        # command 64: car model 5 chosen in the car select (car_select_car_sounds)
4AE8  data    effect_65_car_select_model_3        # command 65: car model 3 chosen in the car select (car_select_car_sounds)
4AF4  data    effect_66_car_select_model_1        # command 66: car model 1 chosen in the car select (car_select_car_sounds)
4B00  data    effect_67_car_select_model_7        # command 67: car model 7 chosen in the car select (car_select_car_sounds)
4B0C  data    effect_68                           # command 68
4B14  data    effect_69                           # command 69
4B1C  data    effect_6a                           # command 6A
4B24  data    effect_6b                           # command 6B
4B2C  data    effect_6c                           # command 6C
4B34  data    effect_6d                           # command 6D
4B3C  data    effect_6e                           # command 6E
4B44  data    effect_6f                           # command 6F
4B4C  data    effect_70                           # command 70
4B54  data    effect_71                           # command 71
4B5C  data    dj_message_3a                       # command 72: DJ message 3A
4B68  data    effect_73                           # command 73
4B70  data    dj_car_model_4                      # command 74: DJ message 05: car model 4's name
4B78  data    dj_car_model_2                      # command 75: DJ message 03: car model 2's name
4B80  data    dj_car_model_0                      # command 76: DJ message 01: car model 0's name
4B88  data    dj_car_model_6                      # command 77: DJ message 07: car model 6's name
4B90  data    dj_car_model_5                      # command 78: DJ message 06: car model 5's name
4B98  data    dj_car_model_3                      # command 79: DJ message 04: car model 3's name
4BA0  data    dj_car_model_1                      # command 7A: DJ message 02: car model 1's name
4BA8  data    dj_car_model_7                      # command 7B: DJ message 08: car model 7's name
4BB0  data    effect_7c                           # command 7C
4BB8  data    effect_7d                           # command 7D
4BC0  data    effect_7e                           # command 7E
4BC8  data    effect_7f                           # command 7F
4BD0  data    effect_80                           # command 80
4BD8  data    effect_81                           # command 81
4BE0  data    dj_station                          # command 82: DJ message 29: as the radio goes to the station
4BE8  data    dj_cars_introduced                  # command 83: DJ message 2A: after the cars' introduction (car_radio_dj_remark_2a)
4BF0  data    effect_84                           # command 84
4BF8  data    effect_85                           # command 85
4C00  data    dj_remark_2b                        # command 86: DJ message 2B: a remark (car_radio_dj_remark_2b)
4C08  data    effect_87                           # command 87
4C10  data    dj_remark_2c                        # command 88: DJ message 2C: a remark (car_radio_dj_remark_2c)
4C18  data    effect_89                           # command 89
4C20  data    dj_remark_2d                        # command 8A: DJ message 2D: a remark (car_radio_dj_remark_2d)
4C28  data    dj_checkpoint_final                 # command 8B: DJ message 2E: at the last checkpoint (stage_level_radio_messages, level 4)
4C30  data    dj_remark_2f                        # command 8C: DJ message 2F: a remark (car_radio_dj_remark_2f)
4C38  data    dj_checkpoint                       # command 8D: DJ message 30: at a checkpoint (stage_level_radio_messages, levels 0-3)
4C40  data    effect_8e                           # command 8E
4C48  data    effect_8f                           # command 8F
4C50  data    select_sound_set_0                  # command D0: CC 20 0 on channel E: sound set 0 (part_templates)
4C58  data    select_sound_set_1                  # command D1: CC 20 1 on channel E: sound set 1 (part_templates)
4C60  data    select_sound_set_2                  # command D2: CC 20 2 on channel E: sound set 2 (part_templates)
4C68  data    select_sound_set_3                  # command D3: CC 20 3 on channel E: sound set 3 (part_templates)
4C70  data    select_sound_set_4                  # command D4: CC 20 4 on channel E: sound set 4 (part_templates)
4C78  data    select_sound_set_5                  # command D5: CC 20 5 on channel E: sound set 5 (part_templates)
4C80  data    select_sound_set_6                  # command D6: CC 20 6 on channel E: sound set 6 (part_templates)
4C88  data    select_sound_set_7                  # command D7: CC 20 7 on channel E: sound set 7 (part_templates)
4C90  data    select_sound_set_8                  # command D8: CC 20 8 on channel E: sound set 8 (part_templates)
4C98  data    select_sound_set_9                  # command D9: CC 20 9 on channel E: sound set 9 (part_templates)
4CA0  data    select_sound_set_a                  # command DA: CC 20 A on channel E: sound set A (part_templates)
4CA8  data    select_sound_set_b                  # command DB: CC 20 B on channel E: sound set B (part_templates)
4CB0  data    channel_a_notes_off                 # command DC: CC 7B on channel A (all notes off)
4CB8  data    channel_a_full_volume               # command DD: CC 7 7F on channel A
4CC0  data    stop_all_voices_7d                  # commands DE, FC: CC 50 7D on channel E: the screen's MultiPCM voices stop (also command FC)
4CC8  data    stop_all_voices_7f                  # commands DF, FE: CC 50 7F on channel E: the screen's MultiPCM voices stop (also command FE)
4CD0  data    effect_b2                           # commands B2, B4, B8, BC
4D9A  data    effect_b3                           # commands B3, B5, B9, BD
4EBC  data    effect_b6                           # commands B6, BA, BE
4FDE  data    effect_b7                           # commands B7, BB, BF
5100  data    unused_effect_program_7d            # an effect no command points at: effect_b3's tune with program 7D on channel B
5222  data    unused_effect_program_7e            # an effect no command points at: effect_b3's tune with program 7E on channel B
5344  data    unused_effect_program_7f            # an effect no command points at: effect_b3's tune with program 7F on channel B
5466  data    dj_message_21                       # command 90: DJ message 21
5479  data    dj_message_22                       # command 91: DJ message 22
548C  data    dj_message_23                       # command 92: DJ message 23
549F  data    dj_message_24                       # command 93: DJ message 24
54B2  data    dj_message_25                       # command 94: DJ message 25
54C5  data    dj_message_26                       # command 95: DJ message 26
54D8  data    dj_message_27                       # command 96: DJ message 27
54EB  data    dj_message_28                       # command 97: DJ message 28
54FE  data    dj_car_number_1                     # command 98: DJ message 09: car number 1
550C  data    dj_car_number_2                     # command 99: DJ message 0A: car number 2
551A  data    dj_car_number_3                     # command 9A: DJ message 0B: car number 3
5528  data    dj_car_number_4                     # command 9B: DJ message 0C: car number 4
5536  data    dj_car_number_5                     # command 9C: DJ message 0D: car number 5
5544  data    dj_car_number_6                     # command 9D: DJ message 0E: car number 6
5552  data    dj_car_number_7                     # command 9E: DJ message 0F: car number 7
5560  data    dj_car_number_8                     # command 9F: DJ message 10: car number 8
556E  data    dj_leader_car_1                     # command A0: DJ message 11: the leader, car number 1 (car_radio_dj_leader)
5581  data    dj_leader_car_2                     # command A1: DJ message 12: the leader, car number 2 (car_radio_dj_leader)
5594  data    dj_leader_car_3                     # command A2: DJ message 13: the leader, car number 3 (car_radio_dj_leader)
55A7  data    dj_leader_car_4                     # command A3: DJ message 14: the leader, car number 4 (car_radio_dj_leader)
55BA  data    dj_leader_car_5                     # command A4: DJ message 15: the leader, car number 5 (car_radio_dj_leader)
55CD  data    dj_leader_car_6                     # command A5: DJ message 16: the leader, car number 6 (car_radio_dj_leader)
55E0  data    dj_leader_car_7                     # command A6: DJ message 17: the leader, car number 7 (car_radio_dj_leader)
55F3  data    dj_leader_car_8                     # command A7: DJ message 18: the leader, car number 8 (car_radio_dj_leader)
5606  data    dj_own_car_1                        # command A8: DJ message 19: this screen's car, number 1 (car_radio_dj_own_car)
561E  data    dj_own_car_2                        # command A9: DJ message 1A: this screen's car, number 2 (car_radio_dj_own_car)
5636  data    dj_own_car_3                        # command AA: DJ message 1B: this screen's car, number 3 (car_radio_dj_own_car)
564E  data    dj_own_car_4                        # command AB: DJ message 1C: this screen's car, number 4 (car_radio_dj_own_car)
5666  data    dj_own_car_5                        # command AC: DJ message 1D: this screen's car, number 5 (car_radio_dj_own_car)
567E  data    dj_own_car_6                        # command AD: DJ message 1E: this screen's car, number 6 (car_radio_dj_own_car)
5696  data    dj_own_car_7                        # command AE: DJ message 1F: this screen's car, number 7 (car_radio_dj_own_car)
56AE  data    dj_own_car_8                        # command AF: DJ message 20: this screen's car, number 8 (car_radio_dj_own_car)
56C6  data    dj_station_hello                    # command B0: DJ message 00: the first message on the station (talk_step 0)
56D9  data    dj_entry                            # command B1: DJ message 3B: the car select and the entry countdown
56F1  data    song_records                        # the songs' records (songs, commands C0-CF)
5974  data    unused_fill_005974                  # FF up to the banked part's songs (0x10000), nothing reads it
10000  banked  magical_sound_shower_04             # song 04
10273  banked  magical_sound_shower_05             # song 05
104EC  banked  magical_sound_shower_06             # song 06
106D7  banked  magical_sound_shower_07             # song 07
10943  banked  magical_sound_shower_08             # song 08
10C9D  banked  magical_sound_shower_09             # song 09
10ECA  banked  magical_sound_shower_0a             # song 0A
11736  banked  magical_sound_shower_0b             # song 0B
12117  banked  magical_sound_shower_0c             # song 0C
12D9E  banked  magical_sound_shower_0d             # song 0D
1306C  banked  magical_sound_shower_0e             # song 0E
1343A  banked  magical_sound_shower_0f             # song 0F
13C43  banked  passing_breeze_10                   # song 10
13F1E  banked  passing_breeze_11                   # song 11
141CB  banked  passing_breeze_12                   # song 12
149D3  banked  passing_breeze_13                   # song 13
15083  banked  passing_breeze_14                   # song 14
1570E  banked  passing_breeze_15                   # song 15
15872  banked  passing_breeze_16                   # song 16
159E8  banked  passing_breeze_17                   # song 17
16AAB  banked  passing_breeze_18                   # song 18
16E5E  banked  passing_breeze_19                   # song 19
172A6  banked  unplayed_song_1a                    # song 1A: only in unused_playlist_songs_1a_1e
1766E  banked  unplayed_song_1b                    # song 1B: only in unused_playlist_songs_1a_1e
17986  banked  unplayed_song_1c                    # song 1C: only in unused_playlist_songs_1a_1e
192EF  banked  unplayed_song_1d                    # song 1D: only in unused_playlist_songs_1a_1e
1A552  banked  unplayed_song_1e                    # song 1E: only in unused_playlist_songs_1a_1e
1B5E3  banked  picture_the_rivers_1f               # song 1F
1B8F8  banked  picture_the_rivers_20               # song 20
1C130  banked  picture_the_rivers_21               # song 21
1D2D8  banked  picture_the_rivers_22               # song 22
1DEB4  banked  picture_the_rivers_23               # song 23
1E96F  banked  picture_the_rivers_24               # song 24
1F44B  banked  picture_the_rivers_25               # song 25
1F6AA  banked  picture_the_rivers_26               # song 26
1F994  banked  picture_the_rivers_27               # song 27
20074  banked  picture_the_rivers_28               # song 28
20F42  banked  looking_for_the_rainbow_29          # song 29
21229  banked  looking_for_the_rainbow_2a          # song 2A
21F09  banked  looking_for_the_rainbow_2b          # song 2B
235F3  banked  looking_for_the_rainbow_2c          # song 2C
23C62  banked  looking_for_the_rainbow_2d          # song 2D
242FD  banked  looking_for_the_rainbow_2e          # song 2E
24AB4  banked  looking_for_the_rainbow_2f          # song 2F
25F79  banked  speed_king_30                       # song 30
26679  banked  speed_king_31                       # song 31
26D99  banked  speed_king_32                       # song 32
27254  banked  speed_king_33                       # song 33
280A1  banked  speed_king_34                       # song 34
28F1C  banked  speed_king_35                       # song 35
29651  banked  speed_king_36                       # song 36
2A171  banked  speed_king_37                       # song 37
2B689  banked  speed_king_38                       # song 38
2C0B2  banked  speed_king_39                       # song 39
2D238  banked  unplayed_song_3a                    # song 3A: in no playlist
2D3C5  banked  adventure_3b                        # song 3B
2D75B  banked  adventure_3c                        # song 3C
2DD7F  banked  adventure_3d                        # song 3D
2F367  banked  adventure_3e                        # song 3E
3080F  banked  adventure_3f                        # song 3F
30D57  banked  adventure_40                        # song 40
31B38  banked  adventure_41                        # song 41
31C40  banked  staff_credits_42                    # song 42
32041  banked  staff_credits_43                    # song 43
324D5  banked  staff_credits_44                    # song 44
32FEC  banked  race_opening_45                     # song 45
33200  banked  meaning_of_the_light_46             # song 46
34670  banked  music_0c_47                         # song 47
355A5  banked  jingle_bell_48                      # song 48
35614  banked  jingle_bell_49                      # song 49
35EF4  banked  jingle_bell_4a                      # song 4A
3668C  banked  blow_your_cool_4b                   # song 4B
36AEB  banked  blow_your_cool_4c                   # song 4C
374E4  banked  blow_your_cool_4d                   # song 4D
379B2  banked  blow_your_cool_4e                   # song 4E
37CFE  banked  blow_your_cool_4f                   # song 4F
386A4  banked  blow_your_cool_50                   # song 50
38AC7  banked  blow_your_cool_51                   # song 51
38B1C  banked  blow_your_cool_52                   # song 52
390D8  banked  blow_your_cool_53                   # song 53
39705  banked  blow_your_cool_54                   # song 54
39E6C  banked  blow_your_cool_55                   # song 55
3AA74  banked  blow_your_cool_56                   # song 56
3B1F5  banked  blow_your_cool_57                   # song 57
3B4EB  banked  sonic_control_58                    # song 58
3B983  banked  sonic_control_59                    # song 59
3C96F  banked  sonic_control_5a                    # song 5A
3D6B2  banked  sonic_control_5b                    # song 5B
3E6EF  banked  sonic_control_5c                    # song 5C
3EABC  banked  sonic_control_5d                    # song 5D
3EF14  banked  sonic_control_5e                    # song 5E
3F30C  banked  sonic_control_5f                    # song 5F
3FA36  banked  sonic_control_60                    # song 60
3FF07  banked  sonic_control_61                    # song 61
42D67  banked  mega_driver_62                      # song 62
42E29  banked  mega_driver_63                      # song 63
43543  banked  station_stage_08_64                 # song 64
441F8  banked  station_stage_08_65                 # song 65
44370  banked  station_stage_03_66                 # song 66
44CC1  banked  station_stage_10_67                 # song 67
459E1  banked  station_stages_13_20_68             # song 68
46291  banked  station_stages_15_18_69             # song 69
4672A  banked  station_stages_15_18_6a             # song 6A
46ED6  banked  station_stages_15_18_6b             # song 6B
46F31  banked  station_stages_16_17_6c             # song 6C
482AA  banked  station_stages_16_17_6d             # song 6D
4847F  banked  station_stage_05_6e                 # song 6E
488B4  banked  station_stage_05_6f                 # song 6F
4898B  banked  station_stage_12_70                 # song 70
496E0  banked  unplayed_station_eb_71              # song 71
49DE4  banked  station_stage_11_72                 # song 72
4A94E  banked  station_stage_11_73                 # song 73
4AB09  banked  station_stage_06_74                 # song 74
4C044  banked  station_stage_06_75                 # song 75
4C3D3  banked  station_fork_jingle_76              # song 76
4C94A  banked  station_stage_07_77                 # song 77
4DFAB  banked  station_stage_02_78                 # song 78
4E108  banked  station_stage_02_79                 # song 79
4E4B4  banked  station_stage_02_7a                 # song 7A
4E96C  banked  station_stage_02_7b                 # song 7B
4EAC5  banked  station_stage_09_7c                 # song 7C
4EBF5  banked  station_stage_09_7d                 # song 7D
4EFBB  banked  station_stage_09_7e                 # song 7E
4F390  banked  station_stage_09_7f                 # song 7F
4F8CF  banked  station_stage_01_80                 # song 80
50A17  banked  station_fork_81                     # song 81
51176  banked  station_stages_14_19_82             # song 82
5395B  banked  station_stage_04_83                 # song 83
53CD9  banked  station_stage_04_84                 # song 84
54684  banked  station_stage_00_85                 # song 85
54CA3  banked  station_stage_00_86                 # song 86
556DA  banked  station_stage_00_87                 # song 87
55AFC  banked  station_stages_21_30_88             # song 88
55D3E  banked  station_stages_21_30_89             # song 89
56B19  banked  station_stages_21_30_8a             # song 8A
57338  banked  station_stages_21_30_8b             # song 8B
57DB0  banked  dream_flying_8c                     # song 8C
5804A  banked  dream_flying_8d                     # song 8D
582E4  banked  dream_flying_8e                     # song 8E
58572  banked  splash_wave_8f                      # song 8F
59AD7  banked  splash_wave_90                      # song 90
5AD32  banked  splash_wave_91                      # song 91
5BB96  banked  splash_wave_92                      # song 92
5CE25  banked  splash_wave_93                      # song 93
5CE82  banked  splash_wave_94                      # song 94
5D5D3  banked  splash_wave_95                      # song 95
5DBE3  banked  splash_wave_96                      # song 96
5E19F  banked  splash_wave_97                      # song 97
5E70C  banked  splash_wave_98                      # song 98
5F4CC  banked  last_wave_99                        # song 99
5F96F  banked  last_wave_9a                        # song 9A
602F6  banked  last_wave_9b                        # song 9B
60A9E  banked  last_wave_9c                        # song 9C
613A5  banked  unused_fill_0613A5                  # FF to the chip's end, nothing reads it

# ======== ports ========

0080  port  FM_ADDRESS
0081  port  FM_DATA
0082  port  FM_PART2_ADDRESS
0083  port  FM_PART2_DATA
00A0  port  ROM_BANK
00B0  port  PCM_BANKS
00C0  port  IRQ_CONTROL
00C1  port  IRQ_ACKNOWLEDGE
00D0  port  IRQ_VECTOR0_INPUT
00D1  port  IRQ_VECTOR1_INPUT
00D2  port  IRQ_VECTOR2_INPUT
00D3  port  IRQ_MASK
00D8  port  IRQ_CONTROL_D8

# ======== the MultiPCM's places (io) ========

C000  io  pcm_data              u8
C001  io  pcm_voice_select      u8
C002  io  pcm_register_select   u8
# C009 left unnamed: init_pcm_chip writes 3 there before and after its loop (0294, 02C6); the chip as MAME has it ignores offset 9, so what it is for is not known.

# ======== tables of the program ROM ========

0234  table  fm_global_init      register_value_pair
024A  table  fm_operator_init    register_value_pair
02E4  table  voice_chip_channels voice_chip_codes
1534  table  fm_patch_registers  fm_register_numbers
1549  table  fm_level_registers  fm_register_numbers
1565  table  fm_fnum_tables      fm_fnumber_runs
1847  table  part_templates      u16
1BC2  table  instruments         u16
1F62  table  note_codes          u8
2016  table  velocity_levels     note_levels
20AE  table  pcm_pitch_tables    pcm_pitch_runs
2546  table  bend_range_tables   u16
2A5E  table  fm_patches          u16
2DA5  table  drum_kits           u16
37F3  table  engine_levels       u8
38F3  table  engine_pitches      u16
3DC6  table  tyre_noises         u8
439B  table  songs               u16
44DB  table  sound_commands      u16

# ======== variables in the shared RAM ========

E000  var  shared_ram_start              u8
E002  var  screen_1_midi_read            u8
E008  var  screen_1_midi_status          u8
E00D  var  sample_or_patch               u8
E010  var  drum_timeout_wait             u8
E011  var  drum_timeout_spare            u8   # the byte after drum_timeout_wait, which sound_init's "ld ($E010),hl" (01D4, HL 008C) clears with it; nothing reads it
E012  var  note_code                     u8
E013  var  note_level                    u8
E014  var  pitch_bend                    s16
E017  var  drum_timeout_pass             u8
E018  var  drum_timeout_cursor           u16
E01A  var  drum_timeout_voices_left      u8
E01B  var  voice_modulation              u8
E01C  var  screen_1_music_volume         u8
E01D  var  drum_pitch                    u8
E01E  var  fm_channel                    u8
E01F  var  pcm_voices_used               u8
E028  var  next_voice                    u16 voice
E02A  var  pcm_banks                     u8
E02B  var  split_tune                    u8
E02C  var  split_octave                  u8
E02D  var  note_number                   u8
E040  var  screen_1_pitch_bends          u16
E060  var  screen_1_channel_controls     u8
E082  var  screen_2_midi_read            u8
E088  var  screen_2_midi_status          u8
E09C  var  screen_2_music_volume         u8
E0C0  var  screen_2_pitch_bends          u16
E0E0  var  screen_2_channel_controls     u8
E100  var  screen_1_midi_queue           u8
E200  var  screen_2_midi_queue           u8
E411  var  voice_0_chip_channel          u8
E412  var  voice_0_note                  u8
E413  var  voice_0_midi_channel          u8
E414  var  voice_0_drum_timeout          u8
E416  var  voice_0_allocation_order      u8
E700  var  screen_1_command              u8
E710  var  screen_1_engine_revs          u8
E711  var  screen_1_engine_state         u8
E712  var  screen_1_engine_requests      u8
E713  var  screen_1_engine_sample        u8
E714  var  screen_1_engine_loudness      u8
E718  var  screen_1_tyre_noise           u8
E719  var  screen_1_tyre_noise_sample    u8
E71C  var  screen_1_tyre_noise_time      u8
E71D  var  screen_1_tyre_noise_off       u8
E740  var  screen_1_tick_countdown  u8
E758  var  screen_1_midi_write           u8
E759  var  screen_1_midi_count           u8
E780  var  engine_sweep_on               u8
E781  var  engine_sweep_wait             u8
E784  var  engine_sweep_position_low     u8
E785  var  engine_sweep_position_high    u8
E786  var  engine_sweep_down             u8
E800  var  screen_2_command              u8
E810  var  screen_2_engine_revs          u8
E811  var  screen_2_engine_state         u8
E812  var  screen_2_engine_requests      u8
E813  var  screen_2_engine_sample        u8
E814  var  screen_2_engine_loudness      u8
E818  var  screen_2_tyre_noise           u8
E819  var  screen_2_tyre_noise_sample    u8
E81C  var  screen_2_tyre_noise_time      u8
E81D  var  screen_2_tyre_noise_off       u8
E858  var  screen_2_midi_write           u8
E859  var  screen_2_midi_count           u8
E900  var  screen_1_music_flags          u8
F100  var  screen_2_music_flags          u8
FFFF  var  sound_cpu_hold                u8

# ======== structures in the shared RAM ========

struct  midi_part        A
array   midi_part        E300  26
struct  voice            9
array   voice            E410  30
struct  sequence_player  100
array   sequence_player  E900  16
struct  screen_page      100
array   screen_page      E700  2
struct  tyre_noise       4  rom

field  midi_part  00  flags             u8
field  midi_part  01  midi_channel      u8
field  midi_part  02  volume            u8
field  midi_part  03  program           u8
field  midi_part  04  transpose         u8
field  midi_part  06  lfo_frequency     u8
field  midi_part  08  effective_volume  u8
field  midi_part  09  bend_range        u8
field  voice  00  flags                 u8
field  voice  01  chip_channel          u8
field  voice  02  note                  u8
field  voice  03  midi_channel          u8
field  voice  04  drum_timeout          u8
field  voice  05  level                 u8
field  voice  06  allocation_order      u8
field  voice  07  tune                  u8
field  voice  08  octave_shift          u8
field  sequence_player  00  flags              u8
# sequence_player 02: the position, as position_low and position_high (the code reads and writes it a byte and a halfword at a time)
field  sequence_player  02  position_low       u8
field  sequence_player  03  position_high      u8
field  sequence_player  06  delta_time_high    u8
field  sequence_player  07  delta_time_low     u8
field  sequence_player  0A  meta_51_value      u8
field  sequence_player  14  running_status     u8
field  sequence_player  15  fade_volume        u8
field  sequence_player  18  fade_speed         u8
field  sequence_player  19  fade_wait          u8
field  sequence_player  1A  fade_channel_volume  u8
field  sequence_player  1B  bank               u8
# sequence_player 20: the playlist, as playlist_low and playlist_high (a byte and a halfword at a time)
field  sequence_player  20  playlist_low       u8
field  sequence_player  21  playlist_high      u8
field  screen_page  00  command            u8
field  screen_page  09  playlist_choice_1  u8
field  screen_page  0A  playlist_choice_2  u8
field  screen_page  0B  player_end_flag    u8
field  screen_page  10  engine_revs        u8
field  screen_page  11  engine_state       u8
field  screen_page  12  engine_requests    u8
field  screen_page  13  engine_sample      u8
field  screen_page  14  engine_loudness    u8
field  screen_page  18  tyre_noise         u8
field  screen_page  19  tyre_noise_sample  u8
field  screen_page  1C  tyre_noise_time    u8
field  screen_page  1D  tyre_noise_off     u8
field  screen_page  40  tick_countdown     u8
field  screen_page  58  midi_write         u8
field  screen_page  59  midi_count         u8
field  tyre_noise  00  sample              u8
field  tyre_noise  01  pitch               u8
field  tyre_noise  02  level               u8
field  tyre_noise  03  duration            u8

# ======== parameters ========

param  write_fm_channel          bc  fm_register     # C: the register; handed back with the value in B (0219, on both ways out)
param  write_fm_channel          a   value
param  write_fm                  bc  fm_register
param  write_fm                  a   value
param  write_fm_part2            bc  fm_register
param  write_fm_part2            a   value
param  write_pcm_register        bc  pcm_register
param  write_pcm_register        a   value
param  read_table_word           hl  table
param  read_table_word           a   entry
param  skip_midi_data_screen_1   bc  first_byte
param  play_midi_message_screen_1  bc  message_byte
param  play_midi_message_screen_1  ix  part  midi_part
param  cut_open_hi_hat_screen_1  bc  velocity_then_timeout
param  cut_open_hi_hat_screen_1  ix  part  midi_part
param  take_voice_screen_1  bc  velocity_then_timeout   # the drum_timeout of a drum note
param  take_voice_screen_1  ix  part  midi_part
local  take_voice_screen_1    04B7  c  drum_timeout           # C: what play_midi_message_screen_1 hands on in it, a drum note's timeout
param  release_note_screen_1  ix  part  midi_part
param  retune_voice_screen_1     iy  voice  voice
param  set_voice_modulation_screen_1  ix  part  midi_part
param  set_voice_modulation_screen_1  bc  voices_left     # B: the caller's count of voices left; C then the register for write_fm_channel (pan_register) or write_pcm_register (6), and write_fm_channel hands its value back in B
param  set_voice_modulation_screen_1  hl  voice
param  read_midi_byte_screen_1   a   midi_byte
param  read_midi_byte_screen_1   bc  midi_byte_copy
param  multiply_bytes            hl  value
param  multiply_bytes            de  factor
param  reset_next_voice          hl  first_voice
param  skip_midi_data_screen_2   bc  first_byte
param  play_midi_message_screen_2  bc  message_byte
param  play_midi_message_screen_2  ix  part  midi_part
param  cut_open_hi_hat_screen_2  bc  velocity_then_timeout
param  cut_open_hi_hat_screen_2  ix  part  midi_part
param  take_voice_screen_2  bc  velocity_then_timeout   # the drum_timeout of a drum note
param  take_voice_screen_2  ix  part  midi_part
local  take_voice_screen_2    0CF2  c  drum_timeout
param  release_note_screen_2  ix  part  midi_part
param  retune_voice_screen_2     iy  voice  voice
param  set_voice_modulation_screen_2  ix  part  midi_part
param  set_voice_modulation_screen_2  bc  voices_left     # as screen 1's
param  set_voice_modulation_screen_2  hl  voice
param  read_midi_byte_screen_2   a   midi_byte
param  read_midi_byte_screen_2   bc  midi_byte_copy
param  start_fm_note             bc  note
param  start_fm_note             de  midi_channel
param  start_fm_note             hl  pitch_bends
param  retune_fm_voice           iy  voice  voice
param  retune_fm_voice           a   chip_channel
param  stop_fm_voice             iy  voice  voice
param  apply_fm_music_volume     bc  chip_channel
param  apply_fm_music_volume     hl  voice_field
param  apply_fm_music_volume     iy  part  midi_part
param  apply_fm_channel_volume   bc  chip_channel
param  apply_fm_channel_volume   hl  voice_field
param  apply_fm_channel_volume   ix  part  midi_part
param  load_fm_patch             a   channel_code
param  load_fm_patch             bc  channel_in_part
param  load_fm_patch             de  register_list
param  load_fm_patch             hl  patch_data
param  load_fm_patch_part2       a   channel_code
param  load_fm_patch_part2       bc  channel_in_part
param  load_fm_patch_part2       de  register_list
param  load_fm_patch_part2       hl  patch_data
param  key_on_with_pan           de  pan
param  set_engine_pitch          de  revs_and_loudness
param  set_engine_sample         a   sample
param  start_tyre_noise          de  pan
param  start_tyre_noise          ix  page  screen_page
param  start_tyre_noise          iy  noise  tyre_noise
param  playlist_command          a   playlist_byte
param  playlist_command          hl  playlist
param  playlist_command          de  queue_pointer
param  playlist_command          ix  player  sequence_player
param  playlist_command          iy  page  screen_page
param  step_player               hl  player_address
param  step_player               de  queue_pointer
param  step_player               iy  page  screen_page
param  chain_next_event          a   data_byte
param  chain_next_event          ix  player  sequence_player
param  clear_player_end_flag     iy  page  screen_page
param  take_sound_command        a   command
param  take_sound_command        de  player_address
param  take_sound_command        hl  page  screen_page
param  start_sound               a   command
param  start_sound               de  player_address
param  start_song                a   song
param  start_song                de  player  sequence_player
param  start_sequence            de  header
param  start_sequence            hl  player  sequence_player
param  select_channel_player     de  header
param  select_channel_player     hl  player_address
param  clear_player              hl  player  sequence_player
param  fade_music_volume         hl  player  sequence_player
param  fade_music_volume         de  queue_pointer
param  fade_music_volume         iy  page  screen_page
param  fade_player_volume        hl  player  sequence_player
param  fade_player_volume        de  queue_pointer
param  fade_player_volume        iy  page  screen_page
param  next_sequence_byte        hl  position
param  next_sequence_byte        ix  player  sequence_player

# ======== local variables ========

local  handle_midi_message_screen_1  0393,03B3  ix  part  midi_part
local  handle_midi_message_screen_2  0BCE,0BEE  ix  part  midi_part
local  init_parts                    033C,0361  iy  part  midi_part
local  release_note_screen_1    060D,063E  iy  voice  voice
local  play_midi_message_screen_1    06BB,06DE  iy  voice  voice
local  play_midi_message_screen_1    07F0,0825  iy  voice  voice
local  play_midi_message_screen_1    0841,08B6  iy  music_part  midi_part
local  play_midi_message_screen_1    09A7,09CC  iy  music_part  midi_part
local  release_note_screen_1    137D,13AE  iy  voice  voice
local  release_note_screen_2    0E4A,0E7B  iy  voice  voice
local  play_midi_message_screen_2    0EF8,0F1B  iy  voice  voice
local  play_midi_message_screen_2    102C,1061  iy  voice  voice
local  play_midi_message_screen_2    107D,10F2  iy  music_part  midi_part
local  play_midi_message_screen_2    11E9,120E  iy  music_part  midi_part
local  release_note_screen_2    17D7,1808  iy  voice  voice
local  update_tyre_noise_screen_1    3E06,3E10  iy  noise  tyre_noise
local  update_tyre_noise_screen_1    3DED,3E02  ix  page  screen_page
local  update_tyre_noise_screen_2    3E56,3E60  iy  noise  tyre_noise
local  update_tyre_noise_screen_2    3E3D,3E52  ix  page  screen_page
local  sequence_tick                 3F04,3F21,3F62,3F81  iy  page  screen_page
local  step_player                   4059  ix  player  sequence_player

# ======== records and runs the pointers walk, in the sound ROM (rom names, batch B6) ========
# The same driver as SegaSonic's (its sound_symbols.txt names these the same way)
struct register_value_pair 2 rom        # a register number and the value written to it: fm_global_init (0234, 11 pairs) and fm_operator_init (024A, 36 pairs), init_fm_chip "ld c,(hl); inc hl; ld a,(hl); inc hl" at 01F2-01F5 and 0200-0203
field register_value_pair 00 register_number u8   # the YM3438's register (fm_global_init 22-2B, fm_operator_init 40-9E)
field register_value_pair 01 value u8             # what is written to it
elements voice_chip_codes u8            # voice_chip_channels (02E4): each voice's chip_channel, 00-06, 08-0E, 10-16, 18-1A for the 24 MultiPCM voices, then 80-82, 84-86 for the YM3438's 6 channels (init_voice_channels 030B "ld a,(de)", 030D "inc de"; init_pcm_chip 02A0 "ld c,(hl)", 02A1 "inc hl")
elements note_levels u8                 # velocity_levels (2016): by note-on velocity 0-127, the note's level 00-FF on a curve (play_midi_message_screen_1 0425, screen_2 0C60: "ld a,(hl)" at velocity_levels + velocity)
elements pcm_pitch_steps u16            # a semitone's run of MultiPCM pitches, one per pitch bend step: read at the run + 2 x the bend (+ 2 x the voice's tune): play_midi_message_screen_1 05A0, screen_2 0DDB, retune_voice_screen_1 0717, screen_2 0F53
elements pcm_pitch_runs u16 pcm_pitch_steps     # pcm_pitch_tables (20AE): by semitone (note & 0F), the address of its run of pitches (0599, 0705, 0DD4, 0F42: "ld a,(hl); inc hl; ld h,(hl)")
elements fm_fnumbers u16                # a semitone's run of YM3438 F-numbers, one per pitch bend step: read at the run + 2 x the bend (start_fm_note 12F9, retune_fm_voice 13F5)
elements fm_fnumber_runs u16 fm_fnumbers        # fm_fnum_tables (1565): by semitone, the address of its run of F-numbers (12F2, 13EB)
elements fm_register_numbers u8         # YM3438 register numbers the channel within its part is added to: fm_patch_registers (1534, 21: load_fm_patch 1508, load_fm_patch_part2 1527, "ld a,(de); add a,c") and fm_level_registers (1549, the 4 total levels: apply_fm_music_volume 1490, apply_fm_channel_volume 14DE)
local  init_fm_chip                  01ED,01F3,01F5,01FB,0201,0203  hl  init_entry
local  init_pcm_chip                 029B,02A1  hl  code_entry
local  init_pcm_chip                 02A0  c  chip_code
local  init_voice_channels           0305,030D  de  code_entry
local  take_voice_screen_1    059F  hl  pitch_entry  pcm_pitch_steps
local  take_voice_screen_2    0DDA  hl  pitch_entry  pcm_pitch_steps
local  retune_voice_screen_1         0715  hl  pitch_entry  pcm_pitch_steps
local  retune_voice_screen_2         0F52  hl  pitch_entry  pcm_pitch_steps
local  start_fm_note                 12F8  hl  fnum_entry  fm_fnumbers
local  retune_fm_voice               13F4  hl  fnum_entry  fm_fnumbers

# ======== locals (batch L6) ========
local  drum_timeout_tick             0163  t1  wait_ticks           # drum_timeout_wait before it is counted down
local  drum_timeout_tick             017E  t1  voices_left          # drum_timeout_voices_left before it is counted down
local  drum_timeout_tick             018B  t1  drum_timeout         # the voice's drum_timeout before it is counted down
local  drum_timeout_tick             0188,019A  hl  cursor          # drum_timeout_cursor: the voice's drum_timeout, then its flags (4 bytes back)
local  drum_timeout_tick             019B  a   voice_flags
local  drum_timeout_tick             019C  c   saved_flags
local  write_fm_channel              0216  t1  channel_code         # fm_channel: bit 2 picks the chip's part
local  write_fm_channel              0212  b   saved_value
local  play_midi_message_screen_1    0686  t2  negated_bend         # a downward bend's steps, made positive
local  play_midi_message_screen_1    06A0  t2  negated_step         # the pitch step of bend_range_tables, negated for a downward bend
local  play_midi_message_screen_1    0773  t1  modulation_wheel     # CC 1's value: shifted right four times (rra) into the depth 0-7
local  play_midi_message_screen_1    0774  t1  wheel_halved
local  play_midi_message_screen_1    0775  t1  wheel_quartered
local  play_midi_message_screen_1    08BC  t3  part_volume          # CC 7: the value doubled (and 1 added when not 0), 0-FF
local  play_midi_message_screen_1    0839  t3  music_volume         # CC 10: the value doubled (and 1 added when not 0), 0-FF
local  play_midi_message_screen_2    0EC3  t2  negated_bend
local  play_midi_message_screen_2    0EDD  t2  negated_step
local  play_midi_message_screen_2    0FAF  t1  modulation_wheel
local  play_midi_message_screen_2    0FB0  t1  wheel_halved
local  play_midi_message_screen_2    0FB1  t1  wheel_quartered
local  play_midi_message_screen_2    10F8  t3  part_volume
local  play_midi_message_screen_2    1075  t3  music_volume
local  retune_fm_voice               13EF  t1  bend                 # pitch_bend
local  retune_fm_voice               13EF  d   bend_high
local  retune_fm_voice               1408,141F  d  part_channel     # the channel within its part of the chip
local  retune_fm_voice               1400  a   channel_code         # fm_channel: bit 2 picks the chip's part
local  retune_fm_voice               13EA  hl  run_entry            # fm_fnum_tables' entry for the note's semitone
local  retune_fm_voice               13F8,13FF  hl  fnumber         # the F-number, then with the block (the note's octave) in bits 11-13
local  engine_sweep_tick             3B1E  p1  lower_position
local  engine_sweep_tick             3B1A  p1  higher_position
local  engine_sweep_tick             3AFA  a   wait_ticks           # engine_sweep_wait
local  engine_sweep_tick             3B27  a   revs                 # the revs at the position (engine_sweep_revs; 0 at its ends)
local  engine_sweep_tick             3B12,3B1A,3B1E  h  sweep_high  # the position in engine_sweep_revs, high byte and low byte
local  engine_sweep_tick             3B0E,3B1A,3B1E  l  sweep_low
local  sequence_tick                 3EF0  t1  countdown            # screen_1_tick_countdown before it is counted down
local  step_player                   4046  p1  delta_time_left      # the player's delta time less one tick
local  step_player                   40AA  t1  controller           # the control change's controller number (10: the music volume)
local  start_sound                   4217  t1  swapped_player       # the player, before "ex de,hl" puts it in hl
local  start_sound                   4211,4214  hl  command_header  # the command's header (sound_commands)
local  start_sound                   4217,4246,424A,427E,4290,42A1  de  header
local  start_sound                   4218  a   header_flags
local  start_sound                   4274,4298  a   priority        # the header's low four bits, against the player's
local  start_song                    423E  t1  swapped_player
local  start_song                    4238,423B  hl  song_record     # the song's record (songs)

# ======== locals (batch Z80) ========
# The values the C still named after the Z80's registers; the names of SegaSonic's sound program where the
# code is the same (its play_midi_message, step_player, the FM patch loops).
local  init_fm_chip                  01F0,01F9,01FE,020F  b  pairs_left                   # B: the register/value pairs of fm_global_init (11) and fm_operator_init (36) left (DJNZ at 01F9, 020F)
local  init_pcm_chip                 029E,02C2  b  voices_left                            # B: the 28 entries of voice_chip_channels set up (DJNZ at 02C2)
local  init_voice_channels           0308,0313  b  voices_left                            # B: the 30 voices whose chip_channel is set (DJNZ at 0313)
local  init_parts                    0318,031B  hl  part_template                         # part_templates[0]: sound set 0's parts, copied to both screens'
local  init_parts                    032D,0336,033A,0342,0352  hl  template_then_product  # the template again (POP HL), past its parts; then H the part's volume and its product with volume_scale
local  init_parts                    0340,0363  bc  parts_left                            # B: the 26 parts (DJNZ at 0363)
local  init_parts                    0345,034E  a  volume_scale                           # FF for a part with flags bit 0, else screen_1_music_volume
local  init_parts                    0355,035A  a  rounded_volume                         # H of volume x scale, + 1 when not 0: the part's effective_volume
local  read_table_word               0368  bc  offset                                     # the entry (A), added twice
local  handle_midi_message_screen_1  0379,0387  a  status                                 # the byte read, or screen_1_midi_status for a data byte
local  handle_midi_message_screen_1  0379,03AB  bc  message_byte                          # C: the byte read_midi_byte_screen_1 read, for play_midi_message_screen_1 and skip_midi_data_screen_1
local  handle_midi_message_screen_1  0390,03AA  hl  channel_and_index                     # H the message's channel, L screen_1_midi_read
local  handle_midi_message_screen_1  0391,03AB,03B5  b  parts_left                        # B: the 13 parts of screen 1 left to look at (DJNZ at 03B5)
local  skip_midi_data_screen_1       03B7  hl  read_index_address                         # &screen_1_midi_read
local  skip_midi_data_screen_1       03C2,03C8  a  event                                  # the status & F0
local  play_midi_message_screen_1    03D6  a  event                                       # the MIDI status & F0: which handler
local  play_midi_message_screen_1    0401,05E6,0661,0735,0741,03D3  c  first_data_byte    # C: the message's first data byte (note, controller, program, bend LSB): from the caller, or read here when that byte was the status
local  play_midi_message_screen_1    0404  b  midi_note                                   # B: the note on's note number (before transpose): the drum kit entry index
local  play_midi_message_screen_1    0408  a  transposed_note                             # the note number + the part's transpose: note_number, and note_codes' index
local  play_midi_message_screen_1    0417,0443  c  velocity_then_timeout                  # C: the velocity read_midi_byte leaves; for a drum note then the kit's byte 1, the voice's drum_timeout
local  play_midi_message_screen_1    0417  bc  velocity_copy        # BC: the velocity read_midi_byte_screen_1 leaves (in C), which take_voice_screen_1 takes
local  play_midi_message_screen_1    0422  de  velocity_index                             # DE = velocity: velocity_levels' index
local  play_midi_message_screen_1    0429,0431  a  part_program                           # the part's program, then program + 10 (F0 on: drum_kits' index)
local  play_midi_message_screen_1    0433,0436,043C,0441  hl  kit_note                    # drum_kits[program - F0] + note * 3: the note's 3 bytes
local  play_midi_message_screen_1    0439  de  note_index                                 # DE = the note number: 3 bytes each in the drum kit
local  play_midi_message_screen_1    0445  a  sample                                      # drum kit byte 2 (FF: the note has no sample)
local  play_midi_message_screen_1    0456  a  drum_note                                   # the note number on channel 15: 2A and 2C (closed and pedal hi-hat) cut the open hi-hat
local  cut_open_hi_hat_screen_1    0464  de  voice_size  # 9, a voice's size
local  take_voice_screen_1    04BA  de  voice_size
local  release_note_screen_1    0611,1381  de  voice_size
local  play_midi_message_screen_1    07F4,0938,0964,0A14,1292  de  voice_size
local  cut_open_hi_hat_screen_1    0467,0488  b  voices_left  # B: the voices left in a walk over the voices (DJNZ)
local  take_voice_screen_1    04BD,04CB,04DC,04E3,04EE,04F2  b  voices_left
local  release_note_screen_1    0614,0640,1384,13B0  b  voices_left
local  play_midi_message_screen_1    06BF,06E0,0797,07AE,07B9,07F7,0827,0867,08B0,08E1,092C,093B,094A,0967,0987,09DD,0A09,0A17,0A36,1295,129D  b  voices_left
local  play_midi_message_screen_1    048F,0493,0496,049E,04A8,04AD  hl  instrument  # instruments[program]: its flags, then its key splits (note, sample, tune, octave)
local  release_note_screen_1    0602,0605  hl  instrument
local  take_voice_screen_1    04C5  a  oldest_order                                # 0: compared with each voice's flags first (a free voice), then the allocation_order of the oldest voice, the one taken over
local  take_voice_screen_1    04D5,04FC,0510,0515,051A,0521,0524,0529,0551,0556,055C,0565,056A,0573  hl  new_voice_field  # the voice the note takes (free or taken over), its fields one after another
local  take_voice_screen_1    053A,056B  a  order                                  # pcm_voices_used: the new voice's allocation_order
local  take_voice_screen_1    0545,05A3,05A8  hl  pitch                            # the MultiPCM pitch of the run, then with the octave in its high byte (0 for a drum note)
local  take_voice_screen_1    0557  a  stored_note                            # note_code, stored in the new voice's note
local  play_midi_message_screen_1    12AB  a  stored_note
local  take_voice_screen_1    055B  c  voice_note                             # C: the note code just stored: its low nibble picks the pitch table, its high one the octave
local  play_midi_message_screen_1    12AF  c  voice_note
local  take_voice_screen_1    0560  a  channel  # the MIDI status & 0F
local  release_note_screen_1    0619,063D,1389,13AD  a  channel
local  play_midi_message_screen_1    06C4,06DA,079C,07B4,07FC,0824,0A0F,12B4  a  channel
local  take_voice_screen_1    0563  b  voice_channel                          # B: the new voice's MIDI channel: the pitch bends' index (channel_controls' for an FM voice)
local  play_midi_message_screen_1    12B7  b  voice_channel
local  take_voice_screen_1    0583  de  channel_offset                        # DE = the MIDI channel (x 2 for the pitch bends): the index of the pitch bends, or for an FM note of channel_controls (and start_fm_note's midi_channel)
local  play_midi_message_screen_1    12D2  de  channel_offset
local  take_voice_screen_1    0585  hl  bend_entry                  # &screen_N_pitch_bends[channel] (CC 50: walks them)
local  play_midi_message_screen_1    06B7,0956,095D  hl  bend_entry
local  take_voice_screen_1    058D  de  tune                                       # split_tune
local  take_voice_screen_1    0598  hl  pitch_table_entry                          # &pcm_pitch_tables[semitone]
local  take_voice_screen_1    05C3,05C7  hl  level_product               # H: note_level, then times the part's effective_volume
local  play_midi_message_screen_1    12BE,12C2  hl  level_product
local  release_note_screen_1    0621,1391  hl  channel_index                    # L: the channel, kept while the note is compared
local  play_midi_message_screen_1    0804  hl  channel_index
local  play_midi_message_screen_1    0664  b  bend_low                                    # B: the bend's first data byte, its low 7 bits
local  play_midi_message_screen_1    066A,0671,0674,0677,067A,067D,0699,069E  c  bend_sign  # C: the bend's bits above the low byte as the 14 bits shift down 5; bit 0 left is the direction (set: above the middle); then 00 up or FF down, the high byte of pitch_bend
local  play_midi_message_screen_1    066B,066F,0673,0676,0679,067C,067F,0686,068A  a  bend  # the 14-bit bend >> 5, then its distance from the middle (0-FF)
local  play_midi_message_screen_1    068C  de  bend_index                                 # DE = bend: the step table's index
local  play_midi_message_screen_1    0691,0694  hl  step_table                            # bend_range_tables[the part's bend_range]
local  play_midi_message_screen_1    0698,06A0,06A4  a  bend_steps                        # the step table's entry, negated for a bend down
local  play_midi_message_screen_1    06A5  b  pitch_bend_high                             # B: the signed bend's high byte (from C)
local  play_midi_message_screen_1    06A6  c  pitch_bend_low                              # C: the signed bend's low byte
local  play_midi_message_screen_1    0744  b  controller_number                           # B: the controller number (the first data byte)
local  play_midi_message_screen_1    0745  c  control_value                               # C: the controller's value
local  play_midi_message_screen_1    0748  a  controller                                  # the controller number
local  play_midi_message_screen_1    0773,0774,0775,0777  a  depth                        # CC 1's value rotated right (RRA) four times and & 7: the modulation depth 0-7
local  play_midi_message_screen_1    0779  c  modulation_depth                            # C: CC 1's value >> 4 & 7, compared with the channel's controls bits 0-6 and stored there
local  play_midi_message_screen_1    0788,07EC,0834,094C,0953  hl  controls_entry         # &screen_N_channel_controls[channel] (CC 50: walks them)
local  play_midi_message_screen_1    0789  a  controls                                    # channel_controls[channel]
local  play_midi_message_screen_1    078A  b  old_controls                                # B: channel_controls[channel] before CC 1 (its bit 7, the pedal, is kept)
local  play_midi_message_screen_1    07A2  de  kept_channel                               # D: the channel while set_voice_modulation runs
local  play_midi_message_screen_1    07AE  bc  voices_left_pair                           # BC for the per-voice call: B the voices left
local  play_midi_message_screen_1    0839,083D,08BC,08C0  a  volume                       # the value x 2, + 1 if not 0: the screen's music volume (CC 10), or the part's volume (CC 7)
local  play_midi_message_screen_1    0845,08B8,09AB,09CE  b  parts_left                   # B: the 8 music parts CC 10 and CC 20 rescale
local  play_midi_message_screen_1    0848,0858,08C4,08D2  hl  scaled_part_volume          # H: the part's volume, then times volume_scale
local  play_midi_message_screen_1    084B,0854,08C5,08CE,09B0,09B9  a  volume_scale       # FF for a part with flags bit 0, else the screen's music volume
local  play_midi_message_screen_1    085B,0860,08D5,08DA,09C0,09C5  a  rounded_volume     # H of volume x scale, + 1 when not 0: a part's effective_volume
local  play_midi_message_screen_1    0864,0874,087F,089B,089F,08AF,08DE,08F0,08FB,0917,091B,092B  hl  voice_field  # (also HL as the caller leaves it, whose low byte the first product takes along)
local  play_midi_message_screen_1    0880,08FC  c  voice_chip_channel                     # C: the sounding voice's chip_channel: bit 7 an FM voice, else the MultiPCM voice to select
local  play_midi_message_screen_1    094F,0954,0959,095E  b  channels_left                # B: CC 50's 16 bytes of channel_controls, then 16 bytes of the pitch bends (half of them), cleared
local  play_midi_message_screen_1    098D,0990,0999,09AD,09BD  hl  template_then_product  # part_templates[set], copied to the music parts, then its bank byte; then H each part's volume and its product with volume_scale
local  play_midi_message_screen_1    09A1  a  new_banks                                   # pcm_banks with the set's bank byte: PCM_BANKS
local  play_midi_message_screen_1    09D9  c  note_to_mark                                # C: note_codes[CC 51's value], compared with each sounding voice's note
local  play_midi_message_screen_1    12BA  a  level                                       # note_level: the FM voice's level
local  retune_voice_screen_1         06EB  c  chip_code                                   # C: the voice's chip_channel, selected in pcm_voice_select
local  retune_voice_screen_1         0704  hl  pitch_table_entry                          # &pcm_pitch_tables[semitone]
local  retune_voice_screen_1         0709  de  bend                                       # pitch_bend
local  retune_voice_screen_1         071A,071F  hl  pitch                                 # the MultiPCM pitch of the run, then with the octave in its high byte
local  set_voice_modulation_screen_1 07CE  c  lfo_register                                # C: 6, the MultiPCM's LFO register
local  set_voice_modulation_screen_1 1434  a  count_as_channel                            # B, the caller's count of voices left, taken as the FM channel (into fm_channel)
local  set_voice_modulation_screen_1 143C  c  pan_register                                # C: B4 + the channel within the part, the YM3438 L/R and modulation register
local  stop_flagged_voices           0A43,0A5D,0A69,0A6E,0A92,0A97  hl  voice_field       # a field of the voice being looked at (9 bytes a voice)
local  stop_flagged_voices           0A46,0A94,0A85  de  voice_size
local  stop_flagged_voices           0A49,0A93,0A98,0A88,0A90  b  voices_left             # B: the 24 MultiPCM voices (DJNZ at 0A98)
local  stop_flagged_voices           0A62  a  key_off_value                               # 0: register 4 (key on) off; also clears the voice's midi_channel
local  stop_flagged_voices           0A6A  b  midi_channel                                # B: the stopped voice's midi_channel
local  stop_flagged_voices           0A70  c  voice_flags                                 # C: the voice's flags before they were cleared (POP AF)
local  stop_flagged_voices           0A7D  a  own_order                                   # the stopped voice's allocation_order
# handle_midi_message_screen_2: the names of handle_midi_message_screen_1's copy of the code
local  handle_midi_message_screen_2  0BB4,0BC2  a  status
local  handle_midi_message_screen_2  0BB4,0BE6  bc  message_byte
local  handle_midi_message_screen_2  0BCB,0BE5  hl  channel_and_index
local  handle_midi_message_screen_2  0BCC,0BE6,0BF0  b  parts_left
# skip_midi_data_screen_2: the names of skip_midi_data_screen_1's copy of the code
local  skip_midi_data_screen_2       0BF2  hl  read_index_address
local  skip_midi_data_screen_2       0BFD,0C03  a  event
# play_midi_message_screen_2: the names of play_midi_message_screen_1's copy of the code
local  play_midi_message_screen_2    0C0E,0C3C,0E23,0E9E,0F71,0F7D  c  first_data_byte
local  play_midi_message_screen_2    0C11  a  event
local  play_midi_message_screen_2    0C3F  b  midi_note
local  play_midi_message_screen_2    0C43  a  transposed_note
local  play_midi_message_screen_2    0C52,0C7E  c  velocity_then_timeout
local  play_midi_message_screen_2    0C52  bc  velocity_copy
local  play_midi_message_screen_2    0C5D  de  velocity_index
local  play_midi_message_screen_2    0C64,0C6C  a  part_program
local  play_midi_message_screen_2    0C6E,0C71,0C77,0C7C  hl  kit_note
local  play_midi_message_screen_2    0C74  de  note_index
local  play_midi_message_screen_2    0C80  a  sample
local  play_midi_message_screen_2    0C91  a  drum_note
local  cut_open_hi_hat_screen_2    0C9F  de  voice_size
local  take_voice_screen_2    0CF5  de  voice_size
local  release_note_screen_2    0E4E,17DB  de  voice_size
local  play_midi_message_screen_2    1030,1174,11A0,1256,1786  de  voice_size
local  cut_open_hi_hat_screen_2    0CA2,0CC3  b  voices_left
local  take_voice_screen_2    0CF8,0D06,0D17,0D1E,0D29,0D2D  b  voices_left
local  release_note_screen_2    0E51,0E7D,17DE,180A  b  voices_left
local  play_midi_message_screen_2    0EFC,0F1D,0FD3,0FEA,0FF5,1033,1063,10A3,10EC,111D,1168,1177,1186,11A3,11C3,121F,124B,1259,1278,1789,1791  b  voices_left
local  play_midi_message_screen_2    0CCA,0CCE,0CD1,0CD9,0CE3,0CE8  hl  instrument
local  release_note_screen_2    0E3F,0E42  hl  instrument
local  take_voice_screen_2    0D00  a  oldest_order
local  take_voice_screen_2    0D10,0D37,0D4B,0D50,0D55,0D5C,0D5F,0D64,0D8C,0D91,0D97,0DA0,0DA5,0DAE  hl  new_voice_field
local  take_voice_screen_2    0D75,0DA6  a  order
local  take_voice_screen_2    0D80,0DDE,0DE3  hl  pitch
local  take_voice_screen_2    0D92  a  stored_note
local  play_midi_message_screen_2    179F  a  stored_note
local  take_voice_screen_2    0D96  c  voice_note
local  play_midi_message_screen_2    17A3  c  voice_note
local  take_voice_screen_2    0D9B  a  channel
local  release_note_screen_2    0E56,0E7A,17E3,1807  a  channel
local  play_midi_message_screen_2    0F01,0F17,0FD8,0FF0,1038,1060,1251,17A8  a  channel
local  take_voice_screen_2    0D9E  b  voice_channel
local  play_midi_message_screen_2    17AB  b  voice_channel
local  take_voice_screen_2    0DBE  de  channel_offset
local  play_midi_message_screen_2    17C6  de  channel_offset
local  take_voice_screen_2    0DC0  hl  bend_entry
local  play_midi_message_screen_2    0EF4,1192,1199  hl  bend_entry
local  take_voice_screen_2    0DC8  de  tune
local  take_voice_screen_2    0DD3  hl  pitch_table_entry
local  take_voice_screen_2    0E00,0E04  hl  level_product
local  play_midi_message_screen_2    17B2,17B6  hl  level_product
local  release_note_screen_2    0E5E,17EB  hl  channel_index
local  play_midi_message_screen_2    1040  hl  channel_index
local  play_midi_message_screen_2    0EA1  b  bend_low
local  play_midi_message_screen_2    0EA7,0EAE,0EB1,0EB4,0EB7,0EBA,0ED6,0EDB  c  bend_sign
local  play_midi_message_screen_2    0EA8,0EAC,0EB0,0EB3,0EB6,0EB9,0EBC,0EC3,0EC7  a  bend
local  play_midi_message_screen_2    0EC9  de  bend_index
local  play_midi_message_screen_2    0ECE,0ED1  hl  step_table
local  play_midi_message_screen_2    0ED5,0EDD,0EE1  a  bend_steps
local  play_midi_message_screen_2    0EE2  b  pitch_bend_high
local  play_midi_message_screen_2    0EE3  c  pitch_bend_low
local  play_midi_message_screen_2    0F80  b  controller_number
local  play_midi_message_screen_2    0F81  c  control_value
local  play_midi_message_screen_2    0F84  a  controller
local  play_midi_message_screen_2    0FAF,0FB0,0FB1,0FB3  a  depth
local  play_midi_message_screen_2    0FB5  c  modulation_depth
local  play_midi_message_screen_2    0FC4,1028,1070,1188,118F  hl  controls_entry
local  play_midi_message_screen_2    0FC5  a  controls
local  play_midi_message_screen_2    0FC6  b  old_controls
local  play_midi_message_screen_2    0FDE  de  kept_channel
local  play_midi_message_screen_2    0FEA  bc  voices_left_pair
local  play_midi_message_screen_2    1075,1079,10F8,10FC  a  volume
local  play_midi_message_screen_2    1081,10F4,11ED,1210  b  parts_left
local  play_midi_message_screen_2    1084,1094,1100,110E  hl  scaled_part_volume
local  play_midi_message_screen_2    1087,1090,1101,110A,11F2,11FB  a  volume_scale
local  play_midi_message_screen_2    1097,109C,1111,1116,1202,1207  a  rounded_volume
local  play_midi_message_screen_2    10A0,10B0,10BB,10D7,10DB,10EB,111A,112C,1137,1153,1157,1167  hl  voice_field
local  play_midi_message_screen_2    10BC,1138  c  voice_chip_channel
local  play_midi_message_screen_2    118B,1190,1195,119A  b  channels_left
local  play_midi_message_screen_2    11C9,11CC,11D5,11EF,11FF  hl  template_then_product
local  play_midi_message_screen_2    11E3  a  new_banks
local  play_midi_message_screen_2    121B  c  note_to_mark
local  play_midi_message_screen_2    17AE  a  level
# retune_voice_screen_2: the names of retune_voice_screen_1's copy of the code
local  retune_voice_screen_2         0F28  c  chip_code
local  retune_voice_screen_2         0F41  hl  pitch_table_entry
local  retune_voice_screen_2         0F46  de  bend
local  retune_voice_screen_2         0F56,0F5B  hl  pitch
# set_voice_modulation_screen_2: the names of set_voice_modulation_screen_1's copy of the code
local  set_voice_modulation_screen_2 100A  c  lfo_register
local  set_voice_modulation_screen_2 1832  a  count_as_channel
local  set_voice_modulation_screen_2 183A  c  pan_register
local  start_fm_note                 12E0  c  voice_note                                  # C: the note code: low nibble the semitone, high nibble the octave
local  start_fm_note                 12F1  hl  run_entry                                  # fm_fnum_tables' entry for the note's semitone
local  start_fm_note                 12FC,1303  hl  fnumber                               # the F-number, then with the block (the note's octave) in bits 11-13
local  start_fm_note                 1304,133B  a  channel_code                           # fm_channel: bit 2 picks the chip's part
local  start_fm_note                 130C,1326  de  register_channel                      # D: the channel within its part, or'ed into A4 and A0
local  start_fm_note                 1343,1349,1362  c  part_channel                      # C: the channel within its part load_fm_patch hands back, added to each level register number; POP BC puts it back (1362)
local  start_fm_note                 1343,1349,1351  de  register_list                    # fm_level_registers, as load_fm_patch hands it back
local  start_fm_note                 1343,1349,1354  hl  patch_levels                     # the patch's 4 operator levels, as load_fm_patch hands them back
local  start_fm_note                 134C,1363  b  operators_left                         # B: the 4 operators whose total level is written (DJNZ at 1363)
local  start_fm_note                 1350  a  register_number                             # fm_level_registers' entry + the channel within the part
local  start_fm_note                 1352  c  level_register                              # C: the operator's total level register
local  start_fm_note                 1353,135E  a  total_level                            # the patch's operator level, + note_level when its bit 7 is clear
local  apply_fm_music_volume         145B  a  channel_code                                # chip_channel, into fm_channel
local  apply_fm_music_volume         1461,14A3  c  part_channel                           # C: the channel within its part (chip_channel & 3); POP BC puts it back (14A3)
local  apply_fm_music_volume         1466,146A  hl  level_product                         # H: the voice's level, then times the part's effective_volume
local  apply_fm_music_volume         1478,147B  hl  instrument                            # instruments, then instruments[the part's program]
local  apply_fm_music_volume         1480,1483,1489,1495  hl  patch_levels                # fm_patches, then the patch, + 15: its 4 operator levels
local  apply_fm_music_volume         148A,14A4  b  operators_left                         # B: the 4 operators (DJNZ at 14A4)
local  apply_fm_music_volume         148C,1492  de  register_list                         # fm_level_registers
local  apply_fm_music_volume         1491  a  register_number
local  apply_fm_music_volume         1493  c  level_register
local  apply_fm_music_volume         1494,149F  a  total_level                            # the operator level, + note_level when its bit 7 is clear (else not written)
local  apply_fm_channel_volume       14A9  a  channel_code
local  apply_fm_channel_volume       14AF,14F1  c  part_channel
local  apply_fm_channel_volume       14B4,14B8  hl  level_product
local  apply_fm_channel_volume       14C6,14C9  hl  instrument
local  apply_fm_channel_volume       14CE,14D1,14D7,14E3  hl  patch_levels
local  apply_fm_channel_volume       14D8,14F2  b  operators_left
local  apply_fm_channel_volume       14DA,14E0  de  register_list
local  apply_fm_channel_volume       14DF  a  register_number
local  apply_fm_channel_volume       14E1  c  level_register
local  apply_fm_channel_volume       14E2,14ED  a  total_level
local  load_fm_patch                 14F8,1511  c  part_channel                           # C: channel_code & 3, the channel within its part, added to each register number; POP BC puts it back (1511)
local  load_fm_patch                 14FC,14FF,150D  hl  patch_data                       # fm_patches, then the patch: its first 21 bytes, one a pass; handed back past them
local  load_fm_patch                 1505,1512  b  registers_left                         # B: the 21 patch registers (DJNZ at 1512)
local  load_fm_patch                 1509  a  register_number                             # fm_patch_registers' entry + the channel within the part
local  load_fm_patch                 150B  c  patch_register                              # C: the register the patch byte goes to
local  load_fm_patch_part2           1517,1530  c  part_channel
local  load_fm_patch_part2           151B,151E,152C  hl  patch_data
local  load_fm_patch_part2           1524,1531  b  registers_left
local  load_fm_patch_part2           1528  a  register_number
local  load_fm_patch_part2           152A  c  patch_register
local  update_engine_screen_1        36B2  hl  pcm_data_at                                # &pcm_data, read for the busy bit
local  update_engine_screen_1        36BF  a  engine_revs                                 # screen_1_engine_revs
local  update_engine_screen_1        36C2  d  revs                                        # D: the revs, for set_engine_pitch
local  update_engine_screen_1        36C7,37C3  a  engine_state                           # screen_1_engine_state
# update_engine_screen_2: the names of update_engine_screen_1's copy of the code
local  update_engine_screen_2        3707  a  engine_revs                                 # screen_2_engine_revs
local  update_engine_screen_2        370A  d  revs
local  update_engine_screen_2        370F,37DB  a  engine_state                           # screen_2_engine_state
local  set_engine_pitch              376E,3771,3787  hl  pitch                            # engine_pitches[revs], plus a random amount where its octave is negative
local  set_engine_pitch              3779  a  refresh_value                               # the refresh register: a random number
local  set_engine_pitch              377B  c  random_amount                               # C: the refresh register's value, added to the pitch
local  set_engine_pitch              3780,3785  b  random_sign                            # B: 00 or FF, the random amount's sign
local  set_engine_pitch              37A4,37A6  a  random_lfo                             # the refresh register & 3F: register 6
local  set_engine_sample             37B5  b  saved_sample                                # B: the sample, kept while register 2 is cleared
local  update_tyre_noise_screen_1    3DE6  a  noise_request                               # screen_1_tyre_noise: 1-8, or 0
local  update_tyre_noise_screen_1    3DF6  a  tyre_noise_time                             # screen_1_tyre_noise_time
# update_tyre_noise_screen_2: the names of update_tyre_noise_screen_1's copy of the code
local  update_tyre_noise_screen_2    3E36  a  noise_request                               # screen_2_tyre_noise
local  update_tyre_noise_screen_2    3E46  a  tyre_noise_time                             # screen_2_tyre_noise_time
local  sequence_tick                 3F15,3F1B,3F32,3F38,3F73,3F79,3F92,3F98  hl  first_player  # the group's first player, the one fade_*_volume fades: the music player (E900, F100) or the first effect player (EA00, F200)
local  sequence_tick                 3F18,3F35,3F3A,3F40,3F46,3F4C,3F52,3F58,3F76,3F95,3F9A,3FA0,3FA6,3FAC,3FB2,3FB8  de  chained_queue_pointer  # where the next byte goes in the screen's MIDI queue (D its page, E1 or E2), from one call to the next as fade_*_volume and step_player hand it back (not queue_pointer, the last call's: one name would join the two variables)
local  sequence_tick                 3F18,3F35,3F3A,3F40,3F46,3F4C,3F52,3F58,3F76,3F95,3F9A,3FA0,3FA6,3FAC,3FB2,3FB8  e  write_index  # E: its low byte, the queue's write index
local  playlist_command              3FC5,3FC8  hl  handler                               # playlist_command_table, then the handler (read_table_word)
local  playlist_command              3FE9  hl  cleared_player                             # FE: the player (IX through the stack), its flags and the 30 bytes after them cleared
local  step_player                   403E,40A0,40A6,40CA,40D6,40E1,40E8,40F1,40F8,4103,41B8,41BF  e  write_index  # E: the page's midi_write, one on per byte copied to the queue; stored back to midi_write
local  step_player                   4046  b  delta_time_left_high                        # B: delta_time_left's high byte
local  step_player                   4046  c  delta_time_left_low                         # C: delta_time_left's low byte
local  step_player                   4047  a  zero_delta                                  # 0, compared with the delta time left: the events' time
local  step_player                   4050  hl  delta_time_at                              # &delta_time_low, then &delta_time_high: the delta time left written back
local  step_player                   4063,40A1,40A7,40CB,40D7,40E2,40F2,40F9,4104,410E,4120,4129,4137,413B,4149,414D,4152,4160,4177,41D7,41DA,41EC  hl  position  # the read position in the sequence
local  step_player                   406A,4079,4134  a  status                            # the event's status byte (running_status for a data byte), then its type (& F0)
local  step_player                   4078,40F5  c  queued_byte                            # C: the status byte copied to the queue first; for messages with two data bytes the first of them (40F5)
local  step_player                   40A4  a  controller_number                           # the control change's first data byte
local  step_player                   40AC,40B8,40BE,40C6  a  control_value                # the controller's value (fade_volume for controller 10 while a fade runs)
local  step_player                   40B0  c  volume_value                                # C: controller 10's value: fade_volume takes it (bit 7 cleared) unless a fade runs
local  step_player                   40DA,40DD,40FC,40FF  a  data_byte                    # the event's last data byte, without bit 7 (chain_next_event)
local  step_player                   410D  a  system_status                               # F0 or F7 (F1-FE end the sequence)
local  step_player                   411E,4123  b  sysex_bytes_left                       # B: the length byte of an F7 event, the bytes skipped (DJNZ at 4123)
local  step_player                   4128  a  sysex_byte                                  # an F0 event's bytes, skipped up to F7
local  step_player                   413E  a  meta_type                                   # the meta event's type: 2F the end, 51 meta_51_value
local  step_player                   414C,4150  b  meta_bytes_left                        # B: the length byte of a meta event, the bytes skipped (DJNZ at 4150)
local  step_player                   415F,416C,4171,4175  a  delta_byte                   # the delta time's byte, or its second byte with bit 7 from the first one's bit 0: the new delta_time_low
local  step_player                   4170  c  new_delta_high                              # C: the high byte of a two-byte delta time ((first & 7F) >> 1)
local  step_player                   4194,4198,419D  hl  playlist                         # the player's playlist, one byte on (and past a command's operands)
local  step_player                   4197,419D  a  playlist_byte                          # the playlist's next byte: a song, or a sound command with flags bit 4; F0-FF a playlist_command, 0 the end
local  step_player                   41AD  de  playlist_player                            # the player (IX through the stack), for start_song or start_sound
local  step_player                   41AD  e  playlist_player_low                         # E: the player's low byte (00)
local  step_player                   41DD,41E7  a  meta_51_value                          # the meta 51 event's value byte, negated with bit 7 set when its bit 7 is set
local  poll_sound_commands           41F5,4203  a  command                                # screen_1_command
local  start_sequence                4259  a  bank                                        # the sequence's bank (byte 1)
local  select_channel_player         42D0  h  player_page                                 # H: the player's page, EC + (the effect's channel - 0A) from the first channel player
local  fade_music_volume             42E2,42FB,42FF,4302,431B,431F,4323,432A,432E,4332  e  write_index  # E: where the next byte goes in the MIDI queue, one on per byte queued
local  fade_player_volume            433A,4353,4357,435A,4372,4376,437A  e  write_index

# ======== stack slots ========
local take_voice_screen_1 0004D0,0004EA s2 pushed_voice      # PUSH HL: the voice, popped into the new voice field
local take_voice_screen_1 00058F s2 bent_pitch               # the bend table's entry plus the tune
local play_midi_message_screen_1 0008E3 s2 pushed_voice_field       # PUSH HL: the voice field, popped back 9 on
local take_voice_screen_2 000D0B,000D25 s2 pushed_voice
local take_voice_screen_2 000DCA s2 bent_pitch
local play_midi_message_screen_2 00111F s2 pushed_voice_field
local stop_flagged_voices 000A53 s5 saved_flags                     # the voice's flags, popped into voice_flags
local start_fm_note 0012E6 s2 channel_pitch_bend                    # the channel's pitch bend (pitch_bends)
local step_player 004058 s2 player_page_start                       # the player's page, its low byte cleared
local step_player 0041AA s10001 queue_page                          # the queue pointer's high byte, kept while the event is written

# ======== source files: the files of src/sound/ and the stretches of the program each takes ========
0000  file  main                      # the sound program's frame: the reset, the timer interrupt, sound_init and the chips set up and written
0372  file  midi                      # the MIDI messages of each screen's queue for its parts: note on and off, pitch bend, controllers, programs; the voices they take
12E0  file  voices                    # the YM3438's FM voices: starting a note, retuning, stopping, their volume and patches
36AD  file  engine                    # the engine and tyre noise of each screen's car
3EED  file  sequences                 # the sequence players and the playlist: their tick, their events into the MIDI queues, the sound commands, the music's fade
