Sound Engine

[EleventhNov]

A substantial amount of the process occurs in the ARM7, which itself works over two domains: The ARM7 binary and the shared WRAM. Since there's not a lot of info on those two aspects, I'll include some relevant stuff of theirs aswell. All of this information is for North America ROM

I'll try to summarize the process as far as I've been researching it. Due to the large complexity of the system, I'll try to not add a lot all at once. If some detail in particular is needed before it's added, please ask for it!

This is my idea of how a request to play music goes from start to finish, in function calls. I'm not fully certain what some steps are meant to achieve in the big picture yet so I apologize for leaving them blank

• 0x20198b8 void BGM_Play(int bgmId, int unk0, int unk1)
• 0x206d9bc
• 0x206db7c
• 0x2073504
• 0x2073edc In this function, the two arguments passed in are somehow used to buffer writes to an array of structs in 0x22b7a6c (size of each: 0x15c, and there's one for every sound channel in the DS)
  Since the writes are buffered, this is the end of this avenue. To further follow the process, we need to start elsewhere
• 0x2071014
• 0x2074a58 For each of the structs in the previously mentioned array, some of their fields are used to create the sound_ops that are passed via IPC
• 0x207ca6c void PushSoundOp_Type0xE(uint channel, uint format, uint source, int repeat_mode, uint loop_start, uint word_amt, uint volume, uint volume_div, int timerVal, int panning)
  This is the most complete sound op I could find and it overwrites a huge amount of the sound registers in 4000400. Basically all of the names are from GBATEK
• 0x207cbcc void PushSoundOp(uint type, uint arg0, uint arg1, uint arg2, uint arg3)
• 0x207cedc void PushSoundOpToLinkedList(sound_op* op)
  The linked list in question has pointers to the start and end at 0x22b9a28 and 0x22b9a2c respectively. Anyway, having buffered these operations, they're finally all sent through IPC over the dedicated sound channel (n. 7), see IPC System #20

STRUCTS:
Sound Op: Stores the operation type, four ints (16 bytes) used to store any kind of arguments in any bit layout, and a pointer to the next sound op (making it a linked list node, which is a VERY common data structure observed in the sound engine overall)
0x0: ptr to next sound op
0x4: type (u32)
0x8: arguments (u32[4])
Total size: 24 bytes

FUNCTIONS ARM7:
0x3801f1c: Processes operations sent from the ARM9 over IPC fifo, most of them are values to be written to the sound registers (0x40004XX)

0x2380118: Copies the WRAM binary stored in ARM7 (0x23801e8) to 0x37f8000. It also copies stuff to 0x27e0000 but I'm not sure what for

[adakite1]

Awesome research! I've done some more digging specifically on the channel structs and what exactly are filled into them and I'll post my findings here.

Methods

02073edc (us)

• param_1: Unknown struct containing a variety of relevant data
• param_2: Note data
  • 0x2: Note played (standard MIDI note values)
  • 0x3: Note velocity

0206d5c8 GetNextUsedSplit (us)
Given a program_info_chunk and prev (the previous SplitEntry), get the address to the next used SplitEntry. Returns zero if all splits have been exhausted, or if this preset doesn't have any splits in the first place. (used splits are ones where the note being played is within the keyrange of the split, and the note's velocity is between the velocity range of the split)

• program_info_chunk: Addr to the start of the current track's SWD Program Info chunk
• prev: Addr to the previous (processed) SplitEntry. If this is called the first time, pass 0.
• notePlayed: Note played (standard MIDI note values)
• noteVelocity: Note velocity

02074618 AssignChannelStruct (us)
Given param_1, the keygroup entry pointed to by the SplitEntry, an unknown value calculated from the keygroup id and a value from param_1, and the keygroupPriority, assign a channel-struct for use in this SplitEntry's playback. Returns the address to the channel struct. This is only ever called from 02073edc (us).

• param_1: Unknown struct containing a variety of relevant data
• keygroupEntry: A reference to the start of the keygroup entry this split points to
• param_3: Unknown value calculated from the keygroup and a value from param_1
• keygroupPriority: Appears to be the keygroup's priority value

02074338 SetupChannelStructs (us)
Initializes the 16 channel structs with their indices (both in the form of just an integer and a half-word long bitflag with a bit for each channel), sets a default pan of 0x40 for all channels, and finally initializes a lot of other struct parameters to zero.

DSE channelStructArray preamble (0x022B7A30)

0x2e => # of channels

DSE channelStruct (array starts at 0x022B7A6C, with each entry spanning 0x15c bytes)

Note: All provided example hex values are values encountered when 02073edc (us) runs for the first time, right when it starts playing the Intro Theme (bgm0001).

0x0 => unk1unk2 (2 byte half word)
0x2 => ??? (seems like it's always 01 00 or 0x0001)
0x4 => zero or two (swaps between the two a lot, and to the beat of the song which is fun)
0x6 => initialized to zero at 02074368 us, and 020740ec us takes the value in here and does |(bitwise or) 0xff0 to it (F1 0F in memory or 0xff1 when bgm0001 plays, so this might be a flag?) (testing it again, it's 00 00 now, not sure how this happened but oh well)
0x8 => channel number (2 bytes)
0xa => channel number but it's represented as a bitflag (2 bytes, 16-bits for 16 channels)

0xc => ???

0xd => midi note played
0xe => SmplID the sample's slot number in the wavi pointer table (1 byte, which is strange since even bgm0001 uses sample 702 which is over the range of a byte)
0xf => Checks for param_1+0x59 first, and if that is zero, it reads unk11 (testing it again, and weirdly it's now 2, but oh well)

0x10 => seems to have something to do with unk11 in SplitEntry. On bgm0001, the unk11 (which is 0x2) is never read though, since the code checks for param_1+0x59 first and only reads unk11 if that returns zero. In this case with bgm0001, it was 0xC. However after a bunch of calculations, 0x10 ends up being just set to zero, so honestly not too sure what it does.

* 0x12 is initialized to zero at 02074388 us
0x12 => (half word) connected to 0x14, this one then adds noteplayed * 0x100 to it. k now I'm confused, it's good to note here that the "ftune" part is never really touched again after being set, even after this step. What has happened to the ctune part up until now is ctune-part = ctune (signed) + ktps (signed). Now we're adding noteplayed * 0x100 to it, and suddenly it's a positive value... Ahhhh I see, ctune-part is what needs to be done to the original sample to get to midi note 60.
0x12 (second attempt) => so ctune-part = ctune (signed) + ktps (signed) + noteplayed, so if note played is 90 and the root note is also 90, then 90 - 30 = 60. If note played is 80 and the root note is 90, then ktps = 60 - 90 = -30, and 80 - 30 = 50. We know that 0x5 is the tuning required to make the note sound at midi 60, so I guess that once that tuning is applied, this value refers to the "effective" midi note??? Like in the root note 90 but played note 80 example, since the note is now root at 60, then technically midi note 50 should be played???? also the ftune is left in as is just sitting in the least significant bits.

0x14 => (half word) appears to be base sample tuning to get it to match midi note 60. ctune is most significant bits, ftune (0-255, pitch up only) is least significant bits, ktps (in semitones) is converted based on ktps * 0x100 and added. I see now, ctune is semitones, and ftune is like a "decimal" tune, since the entire thing is read as a signed 16-bit integer. Since ktps's unit matches that of the most significant part, it's added like that. The whole tuning parameter's unit is probably just semitones, while the ftune part is like the decimal part in a fixed point decimal number. local_30 is also added but it was zero for me.

* 0x16 is initialized to zero at 0207438c us
0x16 => some kind of volume representation with the range of a single byte
* 0x17 is initialized to 0x40, 64, or interpreted as pan, center, at 02074394 us
0x17 => smplpan

0x18 => (half word) something related to the keygroup id

0x1A => ??? (appears to be zero all the time)
0x1B => ??? (appears to be zero all the time)

FUN_020750b4 (us) is passed with param_1 which is this channel struct offset to here 0x17, but it doesn't change anything in the channel struct so I'll ignore it.

0x1C (7) => 0x02000415 unk59 (dse version number 0x415, but appears to be 4 bytes anyways, meaning the 2 bytes of smplfmt which follows gets mixed in to the most important bytes)
--- 0x1C => dse version number 15 04
--- 0x1E => smplfmt 00 02
0x20 (8) => 0x08010109 unk9 (often 0x09, meaning the 1 byte of smplloop which follows gets mixed in to the next most important byte, and the 2 bytes of unk10, often 01 08 and 0x0801 in little endian decoding, gets mixed in to the most important bytes)
--- 0x20 => unk9 09
--- 0x21 => smplloop 01
--- 0x22 => unk10 01 08
0x24 (9) => 0x01010400 unk11 (often 0x0400, but appears to be 4 bytes anyways, meaning the 2 bytes of unk12 which follows and often has a value of 0x0101 gets mixed in to the most important bytes)
--- 0x24 => unk11 00 04
--- 0x26 => unk12 01 01
0x28 (10/0xa) => 0x00000000 unk13
0x2C (0xb) => smplrate
0x30 (0xc) => smplpos + *(int *)(internalWaviStructMaybe + 0x1c), possibly to turn it into an actual pointer to the sample
0x34 (0xd) => loopbeg
0x38 (0xe) => looplen

* A reference to the channel struct offset by 0x3C is given to FUN_02074c70 us for initialization
* 0x3C (envon, single byte) is initialized to zero by 02074c74 us
0x3C (0xf) => unk38/unk20, unk37/unk19, envmult, envon in order of most to least significant.
--- 0x3C => envon 01 (Gets set to 1 at 0207410c us)
--- 0x3D => envmult 01
--- 0x3E => unk37/unk19 01
--- 0x3F => unk38/unk20 03
0x40 (0x10) => 0xFFFFFF03 unk39 (unk39 is 2 bytes, but this appears to be 4 bytes anyways, meaning the 2 bytes of unk40 which follows gets mixed in to the most important bytes)
--- 0x40 => unk39 03 FF
--- 0x42 => unk40 FF FF
0x44 (0x11) => 0x285A0000 sustain, decay, attack, atkvol in order of most to least significant.
--- 0x44 => atkvol 00
--- 0x45 => attack 00
--- 0x46 => decay 5A
--- 0x47 => sustain 28
0x48 (0x12) => 0xFF507F00 unk53, release, decay2, hold in order of most to least significant.
--- 0x48 => hold 00
--- 0x49 => decay2 7F
--- 0x4A => release 50
--- 0x4B => unk53 FF

* 0x4C is initialized to zero by 02074c7c us as an offset from 0x3C
* as 0x3C is envon, and the previous bytes were all related to the ADSR, this could be a state-holder for the envelope
* while the game is playing music, this is noticeably flickering in the memory view, and it also syncs up to the music (i.e. when new notes play it seems to sort of reset), which combined with the fact that it's initialized in the same place as envon, suggests to me that this is something to keep track of the envelope's progression.
0x4C => ??? (full word)

* 0x58 is initialized to zero by 02074c78 us as an offset from 0x3C (envon)
* as 0x3C is envon, this could be related to the envelope
0x58 => ??? (single byte)

* 0x5C is initialized to zero by 020750a0 us as an offset from itself. A few words immediately following 0x5C are also initialized here
0x5C => ???
0x60 => ???
0x64 => ???
0x68 => ???

0x14c (0x53) => set to zero 0x00000000 at 02074368 us
0x154 (0x55) => set to zero 0x00000000 at 020743a4 us
0x158 (0x56) => set to zero 0x00000000 at 020743a8 us