Differences

This shows you the differences between two versions of the page.

amiga:development_environments:basic:amos_professional:extension_development [2023/02/04 09:43] – Topaz		amiga:development_environments:basic:amos_professional:extension_development [2024/03/18 21:15] (current) – Topaz
Both sides previous revision Previous revision Next revision		Previous revision
Line 1:		Line 1:
-	# Original notes	+	# AMOS Professional Extension Development

-	These are detailed in [+Music.s](https://github.com/AOZ-Studio/AMOS-Professional-Official/blob/master/extensions/%2BMusic.s). I add them here as I use them.	+	[[amiga:development_environments:basic:amos_professional\|AMOS Professional]] extensions are written in [[m68k:development:m68k_assembly_language\|Motorola 68000 Assembly Language]].
		+
		+	## Original Notes
		+
		+	[+Music.s](https://github.com/AOZ-Studio/AMOS-Professional-Official/blob/master/extensions/%2BMusic.s) contains instructions for how to make an extension. I've added my own notes below and clarified some of the existing information.

	## Defining Tokens		## Defining Tokens
Line 22:		Line 26:
	##### String parameters		##### String parameters

-	Strings are stored in AMOS with a word for string length (so strings can be up to 65535 characters in length), and then the null-terminated string itself.	+	Strings are stored in AMOS with a word for string length (so strings can be up to 65535 characters in length), and then the string itself. I'm not sure if they're null terminated.

	* https://www.ultimateamiga.co.uk/HostedProjects/AMOSFactory/AMOSProManual/14/1407.html		* https://www.ultimateamiga.co.uk/HostedProjects/AMOSFactory/AMOSProManual/14/1407.html
Line 28:		Line 32:
	## Your own routines		## Your own routines

-	You can `Rbsr` and other branch related jumps to your own stuff, but you can't `Rjsr` to your routines! Only to built-in AMOS routines. Use `Rbsr` and its equivalent!	+	You can `Rbsr` and other branch related jumps to your own stuff, but you can't `Rjsr` to your routines! Only to built-in AMOS routines. Use `Rbsr` and its equivalent! The Compiler will let you know of this mistake very quickly.

	## Built-in Routines		## Built-in Routines
Line 62:		Line 66:
	When you want to demand string space, you apply for it with `L_Demande`.		When you want to demand string space, you apply for it with `L_Demande`.

-	The requested length goes into D3. It does not have to be even. You get the base address in both A0 and A1.	+	The requested length goes into D3. It has to be even. You get the base address in both A0 and A1.

	This is an AMOS string, so the first two bytes are the size of the string as a word. Then the string comes after.		This is an AMOS string, so the first two bytes are the size of the string as a word. Then the string comes after.

-	Then, you have to eventually hand `HiChaine(A5)` (be sure to preserve A5) the ending address of the string, rounded up to the nearest 2. I guess this is so it can be tracked in the garbage collector.	+	Then, you have to eventually hand `HiChaine(A5)` (be sure to preserve A5) the ending address of the string.

	Make sure you don't try to allocate a zero width string with this! It will fail hard.		Make sure you don't try to allocate a zero width string with this! It will fail hard.
Line 93:		Line 97:
	and.w #$0001,d1 ; keep the lowest bit		and.w #$0001,d1 ; keep the lowest bit
	add.w d1,a1 ; add the current address to a1		add.w d1,a1 ; add the current address to a1
-	move.l a1,HiChaine(a5) ; mark our completed string	+	move.l a1,HiChaine(a5) ; update the high end of string memory
	moveq #2,d2		moveq #2,d2
	rts		rts
Line 99:		Line 103:
	moveq #2,d2		moveq #2,d2
	rts		rts
		+	```
		+
		+	Here's a better version:
		+
		+	```asm
		+	; D4 contains your string length
		+	MOVE.L D4,D3
		+	AND.W #$FFFE,D3
		+	ADDQ #2,D3 ; round up to the nearest 2
		+
		+	Rjsr L_Demande ; string is in A0/A1
		+	LEA 2(A0,D3.W),A1
		+	MOVE.L A1,HiChaine(A5)
		+	MOVE.L A0,A1 ; put A1 back
		+	MOVE.W D4,(A0)+ ; put length of string at start of memory
		+	.stringstuff
		+	MOVE.B (A2)+,(A0)+
		+	BNE .stringstuff ; copy until null terminator
		+	```
		+
		+	You know your string code is working if you can do this:
		+
		+	```basic
		+	A$=My String Function$ ' returns "wow"
		+	Print "cat" + A$ + "dog" ' "catwowdog"
	```		```

Line 104:		Line 133:

	Send `ChVide(A5)` to `D3`. "vide" in French is "empty" so that makes sense.		Send `ChVide(A5)` to `D3`. "vide" in French is "empty" so that makes sense.
		+
		+	## Compiler
		+
		+	AMOS Professional will let you be a little sloppy with the differences between `Lib_Def`, `Lib_Par`, `Rbcc`, and `Rjsr`. The compiler will not.
		+
		+	Ensure you have your compiler set up properly:
		+
		+	* Show default screen
		+	* Don't put AMOS to back
		+	* Include the AMOS library
		+
		+	Save those settings and you can use `apcmp file.amos inclib` in your build script to build something for testing.
		+
		+	If your code is crashing, check for the following:
		+
		+	* You are only using `Rbcc` for routines in your library.
		+	* You are ideally only `Rbcc` to `Lib_Def` routines, not `Lib_Par` routines.
		+
		+	If you do this, the compiler will be happy. I suggest having a test AMOS file you can compile and run that will exercise all the code that `Rbcc`s within your own code and running it often, to keep you safe.

	## Tips and Tricks		## Tips and Tricks
Line 132:		Line 180:
	* You don't seem to be able to `INCLUDE` a file that contains `Lib_Def` code.		* You don't seem to be able to `INCLUDE` a file that contains `Lib_Def` code.
	* If you discovered you had been unwinding stacks incorrectly or anything else that could screw AMOS up, just reboot.		* If you discovered you had been unwinding stacks incorrectly or anything else that could screw AMOS up, just reboot.
		+	* Don't use A5 for stuff! Unless you put it back right away. That's where extension memory is located.
		+
		+	---
		+
		+	## How-Tos
		+
		+	### Add a new command to be used in the Editor
		+
		+	These use a bunch of macros I built for the BSD Socket extension:
		+
		+	* Add a new function definition to the token table:
		+
		+	```asm
		+	C_Tk dc.w 1,0
		+	;...
		+	; if something that accepts parameters and returns a value
		+	AddTokenFunction MyNewFunction
		+	dc.b "my new functio","n"+$80,"00,0",-1
		+
		+	; if something that returns nothing and just has side effects
		+	AddTokenInstruction MyNewInstruction
		+	dc.b "my new instructio"."n"+$80,"I",-1
		+	```
		+
		+	* Add a new `Lib_Par` section to the bottom of the file
		+
		+	```asm
		+	Lib_Par MyNewFunction
		+
		+	PreserveStackFunction
		+	RestoreStackFunction
		+	Ret_Int
		+	```
		+
		+	* For functions with more than one parameter, peel off the parameters from `A3` in reverse order:
		+
		+	```asm
		+	; takes four parameters
		+	Lib_Par MyNewFunction
		+
		+	PreserveStackFunction
		+
		+	MOVE.L D3,D4 ; last parameter
		+	MOVE.L (A3)+,D3 ; second-to-last
		+	MOVE.L (A3)+,D2 ; second-to-first
		+	MOVE.L (A3)+,D1 ; first
		+
		+	RestoreStackFunction
		+	Ret_Int
		+	```
		+
		+	* If returning an integer, put it in `D3`:
		+
		+	```asm
		+	Lib_Par MyNewFunction
		+
		+	PreserveStackFunction
		+	MOVE.L (A0),D3 ; return value
		+	RestoreStackFunction
		+	Ret_Int
		+	```

Differences

Page tools