Sections or includes in GST/Quanta Assembler

[martyn_hill]

Hi everyone

Quick question regarding the correct use of sections and linking versus includes when using the GST or Quanta QMAC Assembler...

If I want to keep assembler code segments of a project in different files, but am not interested in fixed addresses and/or linking per-se, is the 'section' directive still relevant or usable, or does one just 'include' the various segments in a master file?

I've written a lot of single-file assembler code over the years, but never needed to spread assembler over multiple files before.

In my naivety, I added a 'section' directive at the top of one of my assembler files recently and both the GST and QMAC assemblers refused to assemble the file, with an error I didn't quite understand and the instruction manual didn't make the use of 'section', etc any clearer as it appears to assume a level of understanding I don't already have

Anyone care to enlighten me on this area? I'd be much appreciated!

[tofro]

In fact, when you are assembling to a relocatable object file for linking, you need to use a section directive.

If you simply want to link a number of relocatable (code) files together with no specific positioning, you can simply put your code in multiple _asm files and use the same section name for all code.

Multiple section names come into play once you start to do magical things like fiddling code into chunks reachable by +-32kBytes of branch range, using the data space of an executable, or linking multi-language object files.

Simply put your code into separate files, use the same section name all over and make sure you use the proper xdef and xref directives between files to make your code known to the linker. And make sure you put the code you want to start from in the beginning of the linker control file.

File 1

Code: Select all

	SECTION CODE
	
	xref 	subroutine
mainThing:
	bra	job_start
	dc.w	0
	dc.w $4afb
	STRING$	{'Job name'}
job_start:
	; do stuff
	bsr	subroutine
	;do more stuff and end
	
	END	

File 2:

Code: Select all

	SECTION CODE
	xdef	subroutine
subroutine:
	; do subroutine stuff
	rts
	END
	

Once you start working with multiple files, you might also want to look into MAKE that comes with C68 - This allows you to compile only files which are newer than their associated _rel files (i.e. have been changed). This can speed up the assembly process significantly.

Tobias

[martyn_hill]

Thanks Tobias - that begins to make some sense to me.

You mention the linker control file (is that a '.ctx' file I've seen someplace?), so each assembler source file is listed there. Got it.

And is it the .ctx file (or whatever) that you then tell the assembler to go assemble?

M.

[pjw]

Once you start working with multiple files, you might also want to look into MAKE that comes with C68 - This allows you to compile only files which are newer than their associated _rel files (i.e. have been changed). This can speed up the assembly process significantly.

..or the very nice designed-for-SMSQ/E QMake, with a manual one can understand Now free and available from Marcel's site

[tofro]

Thanks Tobias - that begins to make some sense to me.

You mention the linker control file (is that a '.ctx' file I've seen someplace?), so each assembler source file is listed there. Got it.

And is it the .ctx file (or whatever) that you then tell the assembler to go assemble?

M.

Not quite. The linker control file normally has the _link extention (or is simply called "LINK" and tells the linker (amongst other things) the order of relocatable fils that should be linked together. It typically lists _rel files.

The _ctx or _cct (for "concatenated", I think) are library build lists. You can build a relocatable library by concatenating _rel files, and the linker will pick only the pieces of code from there it actually needs to resolve all the references. A linker control file contains all the _rel files you want to link into a program, plus some (optional) libraries and (optionally) the name of the finished program and the needed data space. For the above example, it will look like

Code: Select all

**** Linker control file for file1_bin
*512 bytes data space
data 512
section code
input file1_rel
input file2_rel

The qmake utility mentioned by Per also uses linker control files as lists of files to build (which I why I don't like it that much)

Tobias

[martyn_hill]

Thank you gentlemen!

That gives me what I need - and a timely reminder about the QMake approach!

I'll start to use this info over the weekend to re-org the files I've already started to get ready for the QL LAN Bridge Adapter project...

M.

[janbredenbeek]

Just one note: if you only have one _asm file, you can use the -NOLINK option on the GST/QMAC assembler and it will generate the _BIN file directly without intermediate _REL file, thus removing the need to use the linker. You still need to use a SECTION directive though as this indicates that you're generating relocatable code.

Another useful feature is the OFFSET directive that allows you to declare data storage areas:

Code: Select all

	OFFSET 0
var1	dc.w	1	; a word variable
var2	dc.l	1	; a long word
str1	dc.b	36+2 ; A buffer for a QDOS filename

Jan.

[tofro]

Now follows something more advanced:

There is a (relatively well-) hidden feature in the GST Macro Assembler/Linker suite that I discovered some years agoand that really helps building a set of re-usable libraries.

COMMON DUMMY sections that overlay the data space are known to nearly everyone writing assembler code on the QL. They give you the opportunity to work with offsets from a base register (typically a6) into the data space.

The tedious thing with this, is that once you start to use libraries that you have to organize that space yourself - _rel file 1 uses bytes 0-20, rel file 2 21-2f, and so on. You can define this using OFFSET and RORG directives, but you still need to know what library file uses which variables in the data space and shift the others around once you link to that library.

Actually, there is support for this programming technique in ASM and LINK:

Have a COMMON section in each of the library modules, like:

File 1:

Code: Select all

COMMON malloc
basePtr:	ds.l 1
memInc: 	ds.l 1
 

Access to these variables should be coded like:

Code: Select all

	SECTION code
	move.l 	a0,malloc+baseptr(a6)
	cmp.l	a1,malloc+meminc(a6)

File 2:

Code: Select all

	COMMON graphics
screenAddr: ds.l 1
lineLen: 	    ds.w 1
sprites:	ds.l 20

And some more access routines:

Code: Select all

	SECTION code
	move.l #20000,graphics+screenAddr(a6)
	move.w	#128,graphics+lineLen(a6)

If you do this using different COMMON names for all your parts of the data space, the linker will magically arrange them after each other in the data space without you doing anything. That means you can use libraries that use variables in the data space of a job fully transparently.

Tobias

[martyn_hill]

Hi Jan!

Just one note: if you only have one _asm file, you can use the -NOLINK option on the GST/QMAC assembler and it will generate the _BIN file directly without intermediate _REL file, thus removing the need to use the linker. You still need to use a SECTION directive though as this indicates that you're generating relocatable code.

Another useful feature is the OFFSET directive that allows you to declare data storage areas:

Code: Select all

	OFFSET 0
var1	dc.w	1	; a word variable
var2	dc.l	1	; a long word
str1	dc.b	36+2 ; A buffer for a QDOS filename

Jan.

Aha! You know, I think that was the issue when I first tinkered with using 'section' that got me confused - I had declared such dc's (as one often does) but I did not include an OFFSET 0 directive.

So, I summise therefore that, if section is to used (with or without multiple _asm source files) AND and dc's are used, that there also needs to be a OFFSET directive too.

Thank you!

[martyn_hill]

Now follows something more advanced:

Thank you Tobias!

I don't think I'm ready for that functionality yet, but its great that its documented here