Sections or includes in GST/Quanta Assembler

Anything QL Software or Programming Related.
martyn_hill
Gold Card
Posts: 381
Joined: Sat Oct 25, 2014 9:53 am

Sections or includes in GST/Quanta Assembler

Postby martyn_hill » Thu Jan 25, 2018 10:52 pm

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!


User avatar
tofro
QL Wafer Drive
Posts: 1368
Joined: Sun Feb 13, 2011 10:53 pm
Location: SW Germany

Re: Sections or includes in GST/Quanta Assembler

Postby tofro » Thu Jan 25, 2018 11:13 pm

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
Gold Card
Posts: 381
Joined: Sat Oct 25, 2014 9:53 am

Re: Sections or includes in GST/Quanta Assembler

Postby martyn_hill » Fri Jan 26, 2018 12:23 am

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.


User avatar
pjw
Gold Card
Posts: 375
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway

Re: Sections or includes in GST/Quanta Assembler

Postby pjw » Fri Jan 26, 2018 1:43 am

tofro wrote: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


Per
For every complex problem there is an answer that is clear, simple, and wrong.
- H. L. Mencken
User avatar
tofro
QL Wafer Drive
Posts: 1368
Joined: Sun Feb 13, 2011 10:53 pm
Location: SW Germany

Re: Sections or includes in GST/Quanta Assembler

Postby tofro » Fri Jan 26, 2018 7:25 am

martyn_hill wrote: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
Gold Card
Posts: 381
Joined: Sat Oct 25, 2014 9:53 am

Re: Sections or includes in GST/Quanta Assembler

Postby martyn_hill » Fri Jan 26, 2018 8:13 am

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.


User avatar
janbredenbeek
Trump Card
Posts: 249
Joined: Wed Jan 21, 2015 4:54 pm
Location: Hilversum, The Netherlands

Re: Sections or includes in GST/Quanta Assembler

Postby janbredenbeek » Fri Jan 26, 2018 3:09 pm

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.


User avatar
tofro
QL Wafer Drive
Posts: 1368
Joined: Sun Feb 13, 2011 10:53 pm
Location: SW Germany

Re: Sections or includes in GST/Quanta Assembler

Postby tofro » Fri Jan 26, 2018 4:05 pm

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
Gold Card
Posts: 381
Joined: Sat Oct 25, 2014 9:53 am

Re: Sections or includes in GST/Quanta Assembler

Postby martyn_hill » Fri Jan 26, 2018 4:38 pm

Hi Jan!

janbredenbeek wrote: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
Gold Card
Posts: 381
Joined: Sat Oct 25, 2014 9:53 am

Re: Sections or includes in GST/Quanta Assembler

Postby martyn_hill » Fri Jan 26, 2018 4:52 pm

tofro wrote: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 :-)



Return to “Software & Programming”

Who is online

Users browsing this forum: No registered users and 3 guests