Mods to QL Assembly Language Programming book

A place to discuss general QL issues.
Post Reply
User avatar
ajb
ROM Dongle
Posts: 49
Joined: Sat Oct 19, 2019 6:14 am
Location: W.Yorks

Mods to QL Assembly Language Programming book

Post by ajb »

I recently got a new bound copy of Norm's "QL Today ... Book One" masterpiece. Being very familiar with 68000 code but not fluent
in QL niceties I intended skipping the first section "Introduction to Assembly Language" but found myself having a peek. I
PM'd Norm with suggestions for a couple of corrections. He in turn suggested, among other things (all polite), an
approach of opening this thread to which he could reply as he incorporated or ignored them.

I then felt, if I were to do that, I'd better read the section properly. The list has therefore grown. I've intentionally
not been a punctuation/grammar pedant and kept any such things to an absolute minimum. [ There are good books by
Truss (Eats, Shoots & Leaves) and Brandreth (Have You Eaten Grandma?) on that subject - even though linguists probably argue about both]

Anyway, here are some suggestions (working from his latest PDF release which fixes Bigendian problem). I can now settle down to a more relaxing read of the rest of the book.

Alan



1. General

Throughout the book 'compliment' is used when meaning 'complement'.
It's stated in section 5.1.5 that all the 68008 instructions have been covered; most have but some haven't. The following don't appear
in the index. Many of them don't have a dedicated entry (arguably RTS & BRA have) or are only mentioned in passing and some only appear
in code fragments.

BRA, CLR, EXG, EXT, JMP, JSR, NOP, ROL, ROR, ROXL, ROXR, RTS, SWAP, TRAP

The most noticeable omissions are the rotates, given that the book states that there are 4 of them and leaves it at that.


2. Specific

Section 1.3:
"will be a hexadecimal" -> "it will be a hexadecimal"


Section 1.3.1:
"are registers either" -> "are registers; either"


Section 1.3.2:
I haven't used GWASL (does it automatically treat $1000 as short absolute?), but the usual way (for me anyway) to be clear when defining short absolute is by:
MOVE.L $1000.W,D1
MOVE.L $9000.W,D1
If the compiler seeks to use the 'shortest' instruction by default then you ought to be
able to force long absolute using (e.g.)
MOVE.L $9000.L,D1
i.e. it might make things clearer by being explicit.


Section 1.3.7:
"id incremented" -> "is incremented"


Section 2.2:
"This instruction copied" -> "This instruction copies"
"This instruction will be most often used in its Post decrement and pre-increment forms:"
I think you mean pre-decrement and post-increment.


Section 2.4:
"with converts to" -> "which converts to"

"In an unsigned nibble the most significant bit (2|3) is used to hold the sign, so all numbers below unsigned 7 are positive while those
'above' 7 are actually negative and so are below 0."

The above would be more accurate if you say "In a signed nibble..." and "all numbers from 0 to 7 are positive..."
(The '2|3' is my lazy way of representing superscript using only the ASCII character set!).


Section 3.2:
"It is very simply" -> "It is very simple"
"Put simply. The code" -> "Put simply the code"


Section 3.3:
Divs example shows 100/9 as 9r1 rather than 11r1


Section 4.1:
"and in the instruction set," -> "and, in the instruction set,"
"family of instruction" -> "family of instructions"
"opposite to zeros" -> "opposite of zeros"
You say you've previously described doing negation by flipping and incrementing; not so.


Section 4.3
"similar job" -> "similar job,"
"To exit from supervisor mode ANDI #$07FF,SR would need to be done."
To be consistent with the rest of the text that should be #$D7FF (used elsewhere).


Listing 4.3:
"Now it is 0100 0010 and" -> "Now it is 0100 0000 and"


Section 4.4:
I'm unsure whether 'corrupying' is an intentional joke.

"And can be" -> "ANDI can be"
"But the actual" -> "but the actual"
The formatting here (at least with Acrobat and the PDF) makes it tricky to work out which code sections the "These are:" refers to.
It may be best to leave out "These are:" for clarity, in which case the above "And can be" can be replaced by
"and can be" instead.


Listing 4.4: 'Multlication'


Section 4.5:
"D1.W contains $6543 the instruction" -> "D1.W contains $6543. The instruction:"
"Will result in" -> "will result in"
"extremely bad for of" -> "extremely bad form of"
Trace & supervisor are changed if the bits are a '1', not '0' as written.


Section 5.1.1
"cleared is Dn.W is" -> "cleared if Dn.W is"
"... instruction and is the processor is in user mode, and a privilege..." ->
"... instruction and, if the processor is in user mode, a privilege..."

Section 5.1.2
"is adjusted to be 0 to 8" -> "is adjusted to be 0 to 7"

"Z flag which takes the state" -> "Z flag which reflects the state"

"Sets the Z flag to the value of the bit specified." -> "Sets the Z flag according to the value of
the bit specified"

"character was read" -> "character is read"


User avatar
NormanDunbar
Forum Moderator
Posts: 2251
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Mods to QL Assembly Language Programming book

Post by NormanDunbar »

Morning Alan,

Thanks for the list. These will get fixed as soon as I have a minute or two.


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
NormanDunbar
Forum Moderator
Posts: 2251
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Mods to QL Assembly Language Programming book

Post by NormanDunbar »

The vast majority of AJB's points have been corrected. The following, however, are still in progress.
1. General

It's stated in section 5.1.5 that all the 68008 instructions have been covered; most have but some haven't. The following don't appear
in the index. Many of them don't have a dedicated entry (arguably RTS & BRA have) or are only mentioned in passing and some only appear
in code fragments.

BRA, CLR, EXG, EXT, JMP, JSR, NOP, ROL, ROR, ROXL, ROXR, RTS, SWAP, TRAP

The most noticeable omissions are the rotates, given that the book states that there are 4 of them and leaves it at that.
These need a bit more than just a spelling correction and/or a grammar fix, so will take a bit longer to get done. Apologies for these omissions.


With regard to:
Section 1.3.2:
I haven't used GWASL (does it automatically treat $1000 as short absolute?) ...
I did a test. As per the syntax you were not happy with, GWASL does indeed take the absolute short for of the instruction. So, this:

Code: Select all

	move.l $1000,d1
	move.l $1000.W,d1
Are both absolute short and assemble to a pair of words. The same is true, apart from being a pair of words, of the absolute long instructions when an address bigger than a word is supplied. Regardless, I have updated the text to ask that the programmer be specific and to use the size suffix on the address to be absolutely sure (see what I did there?) that the correct form of the instruction is assembled.


The latest PDF is available from https://github.com/NormanDunbar/QLAssem ... ses/latest and is dated August 2020.


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
ajb
ROM Dongle
Posts: 49
Joined: Sat Oct 19, 2019 6:14 am
Location: W.Yorks

Re: Mods to QL Assembly Language Programming book

Post by ajb »

Thanks Norm -

and don't apologise - it's a lovely piece of work and much appreciated. It's much easier pointing the occasional thing out than
writing the stuff (speaking from experience). Self-proofing invariably ends up with seeing what you think is there rather than what actually is.

btw: it wasn't that I didn't like the short absolute thing, just that I thought that readers might be left wondering
how they access e.g. address $9000 without the CPU wandering off into high memory.

I'm having a pleasurable read of the rest of the book - half way through chapter 8 at the mo. I've been thinking about doing some graphics so the screen docs are very useful. The SuperBasic extension stuff gave some fascinating insights into QDOS.

Brace yourself, I've been making a few notes but just a handful of minor corrections so far. I'll post those at some stage if you like.

Alan


User avatar
NormanDunbar
Forum Moderator
Posts: 2251
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Mods to QL Assembly Language Programming book

Post by NormanDunbar »

Hi Alan,

I'm happy to receive all sorts of constructive criticism, advice and bad jokes! As you say, proof reading your own stuff never seems to find anything like all the mistakes.

Keep them coming, thanks.


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
ajb
ROM Dongle
Posts: 49
Joined: Sat Oct 19, 2019 6:14 am
Location: W.Yorks

Re: Mods to QL Assembly Language Programming book

Post by ajb »

OK. Here is the list of things I noted reading through the rest of the book. Most are just minor typos but there were a few oddities along with suggested fixes for them (some where I had to guess what you meant, so beware). A very pleasant read (the book, not these errata).

Do you have any recommendations for other documentation on the PE/Windows coding area (preferably with examples in assembler) - perhaps the sources you used as reference for your articles (I may have overlooked a bibliography)?

Alan


1. General
Lots of MOVEs which should be MOVEAs. Some compilers might barf. Probably not worth fixing at this stage though.
A bit pedantic maybe, but as you know they are very useful visible indicators that flags won't be changed and sign extensions will happen.



2. Specific

Section 6.4:
"holds the address of the SR" -> "holds the value of the SSR"

Section 6.7:
"this means that" - delete as already used at the start of the sentence.

Section 7.3:
"we will get using integer parameters" -> "we will fetch all parameters as integers"

Section 7.5:
"When you fetch parameters onto the maths stack" ->
"When you fetch parameters from the maths stack"

Section 7.5.1:
"Add 2 ro" -> "Add 2 to"

Section 7.6:
"For the first parameter" -> "For parameters"

Table 7.7:
"Bytes 2&3" - this text looks redundant.
"For all entries" -> "All entries"


Section 7.9:
"maths stack the pointer" -> "maths stack, the pointer"


Section 8.2:
"the the" -> "that the"
"and A2.L holds" -> "and A1.L holds"
It may be more clear to say "The a2 routine gets" instead of "The actual routine itself get"
"and divided by 4" -> "and divided by 2"


Table 8.3:
Dunno whether it's worth using "Bit pair" instead of just "Bit"
Bit 1 should say Green.


Section 8.5:

You don't mention the case of (e.g.) INT(5/4) where the address calculation ends up as "base address + 1".
It might be worth adding something like the following after "base address + 2"

"But what about the case of bit 5? The calculation would give an answer of:
base address + (0 * scan width) + INT(5/4)
or
base address + 1

It is therefore still correct to say that the calculation produces an answer that points within the correct word.
However, it might not always give the same byte of that word. To consistently point to the first byte of the required
word we need to clear bit 0 of its address. In the case of the bit 5 example the result 'base address + 1' will
then become just 'base address'. Bear that in mind throughout the rest of this chapter."


"so we know" -> "So we know" - assuming you add the 'bit 5' paragraph.


Section 9.2:

"stop the program" -> "stops the program"

Section 9.4:
"will be you" -> "will be the"


Section 10.2:
"see this reason" -> "see the reason"

Section 10.2.2:
"for the same" -> "for the sake"

Section 10.2.3:
"the some form" -> "then some form"

Listing 10.10:
"variable are" -> "variables are"

Section 10.3.1:
"The nodes are address" -> "The nodes are added" ?

Section 10.3.2:
"then we still have an empty list" -> "then we are at the end of the list" ?

Section 10.3.5:
"but deleting" -> "deleting"

Section 11.2:
"shoing" -> "showing"
"node you want" -> "nodes you want"
"as wll" -> "as well"
"rot node" -> "root node"
"after we have deleting" -> "after we have deleted"
"displyed" -> "displayed"
"diplsy" -> "display"


Section 12.2:
"if there was" -> "if there were"


Section 13.2.1:

"register and" -> "register so"


Section 14.2.3:
"form" -> "for"


Section 14.2.4:
"time that" -> "time than"


Section 15.2:
"text read for" -> "text ready for"


Section 16.2:
"names ROOT" -> "named ROOT"


Section 18.5:

In the paragraph starting "And that's all" d7 should be zero for 'convert' and not 'convertq'.


Section 19.1:

"that causes me" -> "that cause me"


Section 19.5:
"UNLESS" -> "UNTIL" - to be consistent with section 3.2


Section 19.6:
"has only" -> "only"


Section 20.2:
"should have loaded" -> "should have it loaded"
"pile if hit" -> "pile is hit"
"inside out window" -> "inside our window"
"user click" -> "user clicks"

Section 21.2:
"if we should quite" -> "if we should quit"
"We scrolls up" -> "We scroll up"
"Ok, the documentation..." - You could refer the reader to Table 21.2 at the end of this para.

Listing 21.7:
"bsr.s" -> "bsr"

Listing 21.8:
"bsr.s" -> "bsr"

Listing 21.13:
"moveq 9,d5" -> "moveq #9,d5"


Section 22.3.1:
"an option is" -> "an option in"

Section 22.3.3:
"for the same of" ->"for the sake of"

Section 22.3.5:
"Objects" -> "Object"

Section 2.3.6:
"program name" -> "program names"

Section 22.3.8:
"prints its output" -> "prints its output to"

Section 22.3.10:
"PATTERS" -> "PATTERNS"
"patters" -> "patterns"

Section 22.5:
"even though" -> "even so"

Section 22.6:
"a windows" -> "a window"
Para starting "Again," - you need to swap the last two sentences.
"odd pointer obviously" -> "odd pointer" (as the sentence already starts with 'Obviously').
"that I ever" -> "than I ever"


Listing 23.7:
"Hit area width" -> "Width" for consistency as Table 23.2 doesn't mention hits.
"Height size" -> "Height" to match the above.


Section 25.2:
"that straight" -> "than straight"


Section 25.3.4:
"be positions" -> "be positioned"


Section 26.4.2:
"widow"->"window"


Section 26.5:
"George's example." -> "George's examples."


Section 27.5:
"lose item" -> "loose item"


Section 28.2:
"Note" about George- you already used the same note in Section 27.2


Section 28.3:
"preservers" -> "preserves"
The advanced hit program does not display the key under qdos (it gives a grey
rectangle), but does under smsq/e.


Section 29.2:
"number of IW Objects=0.10" -> "number of IW Objects=0"


Section 29.5:
"witch" -> "which"
"when columns" -> "where columns"


Section 29.7:
"withing" -> "within"


Section 29.8:
"patters" -> "patterns"


Listing 30.1:
"regsiters" -> "registers"


Section 30.2:

"file names" -> "file named"


Appendix B:
"see the table in my explanation" - what table?


User avatar
NormanDunbar
Forum Moderator
Posts: 2251
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Mods to QL Assembly Language Programming book

Post by NormanDunbar »

Thanks. I think! :D

Progress report coming soon...


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
NormanDunbar
Forum Moderator
Posts: 2251
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Mods to QL Assembly Language Programming book

Post by NormanDunbar »

Just an FYI, I am working on the list of corrections, but other things (family related) are getting in the way.

Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
NormanDunbar
Forum Moderator
Posts: 2251
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Mods to QL Assembly Language Programming book

Post by NormanDunbar »

Finally! I'm finished. The latest version of this long running tome can be found at https://github.com/NormanDunbar/QLAssem ... ses/latest -- if you do not want the entire source code of the book (that's a whole lot of LaTeX files, not assembly language source code) -- just grab the pdf file. The various source code options also include the pdf, so you don't need to download that separately.

ajb wrote: 1. General
Lots of MOVEs which should be MOVEAs. Some compilers might barf. Probably not worth fixing at this stage though.
A bit pedantic maybe, but as you know they are very useful visible indicators that flags won't be changed and sign extensions will happen.
True, however, all (?) QL Assemblers that I've used automagically convert MOVE to MOVEA anyway. I didn't look in my Programmers Guide but I think I remember having a funny feeling that if you have the destination as an address register, the bit pattern for MOVE ??, An is the bit pattern for MOVEA ??,An anyway. Don't go looking that up by the way, I haven't confirmed it yet! ;)

I have not gone through all the MOVEs and converted them to MOVEAs.
ajb wrote: 2. Specific

Section 6.4:
"holds the address of the SR" -> "holds the value of the SSR"

...
Fixed as indicated.

ajb wrote: Section 8.5:

You don't mention the case of (e.g.) INT(5/4) where the address calculation ends up as "base address + 1".
It might be worth adding something like the following after "base address + 2"

"But what about the case of bit 5? The calculation would give an answer of:
base address + (0 * scan width) + INT(5/4)
or
base address + 1

It is therefore still correct to say that the calculation produces an answer that points within the correct word.
However, it might not always give the same byte of that word. To consistently point to the first byte of the required
word we need to clear bit 0 of its address. In the case of the bit 5 example the result 'base address + 1' will
then become just 'base address'. Bear that in mind throughout the rest of this chapter."


"so we know" -> "So we know" - assuming you add the 'bit 5' paragraph.
Thanks for that. I've added a paragraph that's basically what you have written above.
ajb wrote: Section 9.2:

...

Fixed as indicated.

ajb wrote: Listing 23.7:
"Hit area width" -> "Width" for consistency as Table 23.2 doesn't mention hits.
"Height size" -> "Height" to match the above.
I've changed the source code comments to be just Height and Width. In the table I've extended the description to show that the "hit area" sizes are the width or height including any borders defined in the window attributes.

I think that's what you were after?


ajb wrote:
Section 25.2:
"that straight" -> "than straight"

...
Fixed.

ajb wrote: Section 28.2:
"Note" about George- you already used the same note in Section 27.2
I removed the note from 28.2.
ajb wrote: Section 28.3:
The advanced hit program does not display the key under qdos (it gives a grey
rectangle), but does under smsq/e.
Hmm, interesting. I wonder why? I've not got any usable QLs at the moment so I have nothing running QDOS, so I'm not able to check, unfortunately. To this end, I've added a note to the section advising the reador of the problem.

ajb wrote: Section 29.2:
"number of IW Objects=0.10" -> "number of IW Objects=0"

...

Appendix B:
"see the table in my explanation" - what table?
[/quote]

Fixed. There was no table in Appendix B, so I've removed that sentence. It didn't make any sense.


Thanks again for the proof reading. Hopefully, with the above corrections, plus a few more that I found myself, it is a better document.


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
ajb
ROM Dongle
Posts: 49
Joined: Sat Oct 19, 2019 6:14 am
Location: W.Yorks

Re: Mods to QL Assembly Language Programming book

Post by ajb »

Thanks Norm. Good stuff.

Alan


Post Reply