MK68 SANDBOX Readme

SANDBOX is a utility, written in ASM, to test and debug your code, experimenting and even learning how M68K processor works. It's an enviroment with tools to see Registers and RAM space. You can write your ASM-code and then run in it SANDBOX, but here, besides normal ASM-comands, you'll have extra commands, like OUT, which can show the values of registers, bytes from RAM, ROM, almost everything. You'll also be able to pause your program at any point, write text strings and even more.

Usage

Place your programs in Proj folders, any ASM-files there will be included into SANDBOX after the compilation.

When the ROM is compiled, run it in any SMD Emulator. I'd recommend you Regen, because it's closest to the hardware, with it, you could learn to write a proper code, that will be the most compatible with the real hardware. After opening SANDBOX in emulator, select any program and run it. Controls are show in the bottom status bar.

Notes

Here some notes for you to avoid confuses in the future:

• Don't forget to put RTS in the end of your programs!
  Absence of RTS in the end may cause the next program to run.
• Never call PAUSE/DELAY from subprograms.
  This may cause fatal error and freeze the system, see bottom for more.
• Simple copy-pasting code from Sonic games won't work.
  It's not Sonic engine, you must understand it before set to work. It doesn't know, what's in a0 until you put something in it. The whole memory for programs is empty, so reading something from it without writing before is useless. I'd recommend you to look at "Sonic_Display Test.asm" example to see, how to test code from Sonic games here.
• Use $FF0000-$FF8000 RAM-space for your needs.
  I think $8000 is more than enough. Using any memory after $FF8000 is not recommended, this may spoil system data and cause glitches and errors. See Vars.asm to learn, how memory space is used in SANDBOX.
• Be careful with labels.
  Due to compilator nature, label names are global, so using short names like "Loop", "Quit" etc in sevral programs at the same time will cause "Label is multiply defined" error. So try to use local labels, like "@loop", "@quit" and so on. But they can be valid only between two normal labels (though, I'm quite not sure). Also, they often became invalid, if you put "out" comand between them.
• Label at the beginning of the program is optional.

Commands

OUT [string]

Outputs constant string into console.

[string] - Any expression in quotes. Length is unlimited.

Examples:

	out	"I'm writing text in the console!"
	out	'Now the calculations will be done'

OUTx [data],[flags]

Outputs numeric value in the console.

[x] - data size, can be "w" (word), "b" (byte) and "l" (long). So, there are 3 comands: outb, outw and outl.
[data] - can be literally everything: d0, a0, (a0), 4(a5), ($FF0000).w or just constant #$1010.
[flags] - can have the following params:

• signed - display number in signed type
• trim - destroy zero digits on the left, i.e. $0001 after trimming will be $1.
• dec - display in decimal numeral system.
• bin - displan as binary numeral system.

You also can combine flags with "+" or "|" operators (I personally prefer +), so if you want the outputing number to be binary and trimmed, you may write: bin+trim.

Examples:

	move.b	#$FF,d0		; move $FF to d0
	outb	d0,signed	; display it as signed number
	
	outw	#$1010		; display in default mode: unsigned hex
	
	outl	#$-1000000,dec+signed	; this will display the number as signed decimal

BREAK

Moves cursor to the next row.

CLS

Clears the console.

PAUSE

Interrupts the program, and waits until you press C-button. During this period, you can switch to alternative modes in SANDBOX, like "RAM View" or "Registers".

Warning: Don't call this command from subprogram (when bsr/jsr was launched).

Examples:

	pause			; you can pause here
	bsr.s	Subprogram
	pause			; you can pause here
	rts
	
Subprogram:
	pause			; this will cause fatal error
	rts
; -----------------------
	moveq	#5,d0
Loop:	delay	10		; Cycle, not subprogram. You can delay it here!
	dbf	d0,Loop
; -----------------------
	move.w	d0,-(sp)	; move d0 into the stack
	pause			; ERROR!!!
	move.w	(sp)+,d0	; get d0 from the stack
	pause			; correct!

DELAY [frames]

Delays program for the amount of frames.

[frames] - is amount of frames. Note that 0 value here is not valid and will cause delaying for $FF frames.

Warning: Don't call this command from subprogram.