DSP: Comment the DSPSpy ucode a bit.

git-svn-id: https://dolphin-emu.googlecode.com/svn/trunk@2997 8ced0084-cf51-0410-be5f-012b33b47a6e

Source/DSPSpy/dsp_code.ds

@@ -1,4 +1,6 @@
+; This is the trojan program we send to the DSP from DSPSpy to figure it out.
 
+; A lot of constant definitions.
 DSCR:	equ 0xffc9	; DSP DMA Control Reg
 DSBL:	equ 0xffcb	; DSP DMA Block Length
 DSPA:	equ 0xffcd	; DSP DMA DMEM Address
@@ -65,6 +67,7 @@ REGS_BASE:	equ		0x0f80
 MEM_HI:			equ		0x0f7E
 MEM_LO:			equ		0x0f7F
 
+; CODE STARTS HERE.
 
 ; Interrupt vectors 8 vectors, 2 opcodes each
 
@@ -78,21 +81,22 @@ MEM_LO:			equ		0x0f7F
 	jmp		irq7
 	
 ; Main code at 0x10
-	CW		0x1302
+	sbset       #0x02
-	CW		0x1303
+	sbset       #0x03
-	CW		0x1204
+	sbclr       #0x04
-	CW		0x1305
+	sbset       #0x05
-	CW		0x1306
+	sbset       #0x06
 
 	s40
-	lri		$r12, #0x00ff
+	lri		$CR, #0x00ff
 
+; Why do we have a main label here?	
 main:
 
-	cw		0x8900
+	clr         $ACC1
-	cw		0x8100	
+	clr         $ACC0
 
-; get address of memory dump and copy it
+; get address of memory dump and copy it to DRAM
 
 	call	wait_for_dsp_mbox
 	si		@DMBH, #0x8888
@@ -114,7 +118,7 @@ main:
 	call	do_dma
 
 
-; get address of registers and DMA them to memory
+; get address of registers and DMA them to ram
 
 	call	wait_for_dsp_mbox
 	si		@DMBH, #0x8888
@@ -135,7 +139,7 @@ main:
 	lr		$r1e, @MEM_LO
 	call	do_dma
 
-
+; Read in all the registers from RAM
 
 	lri		$r00, #REGS_BASE+1
 	lrri	$r01, @$r00
@@ -171,28 +175,30 @@ main:
 	lrri	$r1f, @$r00
 	lr		$r00, @REGS_BASE
 
-	nop
+;  Right here we are at a specific predetermined state.
-	nop
+;  Ideal environment to try instructions.
-	nop
-	nop
-
 
+;  We can call send_back at any time to send data back to the PowerPC.
 
+	nop
+	nop
+	nop
+	nop
 
 	cw 0x8600
 
 	call	send_back
 	
-		JMP ende
+; We're done - currently we only test one opcode, in this case 0x8600.
+; It's possible to test many more in one go - just call send_back after each one.
 
+	jmp ende
+
+; Below here is tons of random leftover test code from whoever last experimented with this.
 
 ;	call dump_memory
 ;	call send_back
 
-	
-; 0x041e
-;	
-
     cw 0x00de 
     cw 0x03f1 
     call	send_back
@@ -405,7 +411,7 @@ g_0c65:
     call	send_back
     
 	
-
+; This is where we jump when we're done testing, see above. 
 ende:
 
 	nop
@@ -416,36 +422,42 @@ ende:
 	nop
 	nop
 	
-	
+; We just fall into a loop, playing dead until someone resets the DSP.	
-	
 dead_loop:
 	jmp		dead_loop
 
+; Utility function to do DMA.
+; r1c:r1e - external address.
+; r18     - address in DSP
 do_dma:
 	sr		@DSMAH, $r1c
 	sr		@DSMAL, $r1e
 	sr		@DSPA, $r18
 	sr		@DSCR, $r19
-	sr		@DSBL, $r1a
+	sr		@DSBL, $r1a  ; This kicks off the DMA.
+
+; Waits for said DMA to complete by watching a bit in DSCR.
 wait_dma:
 	LRS		$ACL1, @DSCR
 	andcf	$acl1, #0x0004
 	JLZ		wait_dma
 	RET
 
-
+; This waits for a mail to arrive in the DSP in-mailbox.
 wait_for_dsp_mbox:
 	lrs		$ACL1, @DMBH
 	andcf	$acl1, #0x8000
 	jlz		wait_for_dsp_mbox
 	ret
 
+; This waits for the CPU to grab a mail that we just sent from the DSP.
 wait_for_cpu_mbox:
 	lrs		$ACL1, @cmbh
 	andcf	$acl1, #0x8000
 	jlnz	wait_for_cpu_mbox
 	ret
 
+; IRQ handlers. Not entirely sure what good they do currently.
 irq0:
 	lri		$acl0, #0x0000
 	jmp		irq
@@ -455,7 +467,6 @@ irq1:
 irq2:
 	lri		$acl0, #0x0002
 	jmp		irq
-	
 irq3:
 	lri		$acl0, #0x0003
 	jmp		irq
@@ -463,14 +474,14 @@ irq4:
 	lri		$acl0, #0x0004
 	jmp		irq
 irq5:
-;	jmp finale
+; No idea what this code is doing.
 	s40
 	mrr		$r0d, $r1c
 	mrr		$r0d, $r1e
 	clr		$acc0
 	mrr		$r1e, $r0d
 	mrr		$r1c, $r0d
-	nop
+	nop     ; Or why there's a nop sled here.
 	nop
 	nop
 	nop
@@ -497,11 +508,9 @@ irq:
 	si		@DIRQ, #0x0001
 	halt
 	
-	
+; DMA:s the current state of the registers back to the PowerPC. To do this,
-	
+; it must write the contents of all regs to DRAM.
-	
 send_back:
-
 	; store registers to reg table
 	sr		@REGS_BASE,  $r00
 	lri		$r00, #(REGS_BASE + 1)
@@ -537,7 +546,7 @@ send_back:
 	srri	@$r00, $r1e
 	srri	@$r00, $r1f
 
-
+; Regs are stored. Prepare DMA.
 	lri		$r18, #0x0000
 	lri		$r19, #1		;(DSP_CR_IMEM | DSP_CR_TO_CPU)
 	lri		$r1a, #0x200
@@ -546,6 +555,7 @@ send_back:
 
 	lri		$r01, #8+8
 
+; Now, why are we looping here?
 	bloop	$r01, dma_copy
 	call	do_dma
 	addi	$r1e, #0x200
@@ -553,21 +563,22 @@ send_back:
 	addi	$r1f, #0x100
 	mrr		$r18, $r1f
 	nop
+
 dma_copy:
 	nop
 
+; Wait for the CPU to send us a mail.	
 	call	wait_for_dsp_mbox
 	si		@DMBH, #0x8888
 	si		@DMBL, #0xfeeb
 	si		@DIRQ, #0x0001
 	
-; wait for answer before we execute the next op	
+; wait for the CPU to recieve our response before we execute the next op	
 	call	wait_for_cpu_mbox
 	lrs		$ACL0, @CMBL
 	andi	$acl1, #0x7fff
 
-	
+; Restore all regs again so we're ready to execute another op.
-	
 	lri		$r00, #REGS_BASE+1
 	lrri	$r01, @$r00
 	lrri	$r02, @$r00
@@ -602,19 +613,18 @@ dma_copy:
 	lrri	$r1f, @$r00
 	lr		$r00, @REGS_BASE
 	
-	ret	
+	ret   ; from send_back
 	
+; I wish I knew what this 16 means.
 send_back_16:
-			
+	set40
-	cw		0x8e00
 	call	send_back	
-	cw		0x8f00
+	set16
-	
 	ret
 
-	
+; This one's odd. Doesn't look like it should work since it uses acl0 but 
+; increments acm0... (acc0)	
 dump_memory:
-
 	lri		$r02, #0x0000
 	lri		$acl0, #0x1000
 	
@@ -622,7 +632,7 @@ dump_memory:
 	bloop	$r01, _fill_loop2			
 	
 	mrr $r03, $acl0
-	cw 0x80f0
+	nx'ld   : $AX0.H, $AX1.H, @$AR0
 	
 	mrr $r1f, $r00
 	mrr $r00, $r02
@@ -634,6 +644,4 @@ dump_memory:
 
 _fill_loop2:
 	nop
-	
+	ret   ; from dump_memory
-
-ret