Andy Pennell's books.

A place to discuss general QL issues.
Derek_Stewart
Font of All Knowledge
Posts: 3900
Joined: Mon Dec 20, 2010 11:40 am
Location: Sunny Runcorn, Cheshire, UK

Re: Andy Pennell's books.

Post by Derek_Stewart »

Hi,

I have copied all the possible amendments and have tried to validate the changes against QL Technical Guide and Advanced QL Guide.

I have a few questions on the ammenments, which I ask by PM.


Regards,

Derek
Derek_Stewart
Font of All Knowledge
Posts: 3900
Joined: Mon Dec 20, 2010 11:40 am
Location: Sunny Runcorn, Cheshire, UK

Re: Andy Pennell's books.

Post by Derek_Stewart »

I have added the amendments, checking with the Advanced QL User Guide (QLAUG) and QL Technical Manual (QLTM)

here is a PDF file of the current update, just in case someone does not use Github.
QDOS_Companion_18-05-2022.pdf
QDOS Companion update 18/05/22
(1.59 MiB) Downloaded 113 times
if there are any changes or errors required, please quote the PDF filename and page number:

QDOS-Companion_18-05-22: Page 35
Enter amendments required....


Regards,

Derek
Derek_Stewart
Font of All Knowledge
Posts: 3900
Joined: Mon Dec 20, 2010 11:40 am
Location: Sunny Runcorn, Cheshire, UK

Re: Andy Pennell's books.

Post by Derek_Stewart »

Martin_Head wrote: Page 35
Channels I have a reference to page 155

Page 185
Format A1 Pointer to medium name
D1 Number of medium to format e.g 3 = FLP3_
A4 Pointer to Physical Definition Block
A6 Pointer to System variables[/code]
[/quote]

Just some clarifications, my question preceded with ***

------------------------------------
Page 35
Channels I have a reference to page 155

*** Same as original book
------------------------------------
Page 43
IO.OPEN D2,D3 and A1 not preserved

*** QL AUG : Same as QDOS_Companion
*** QLTM: D2,D3 Preserved, A1 ??? or Not Preserved
------------------------------------

Page 185
Format

*** QDOS Companion agrees with QL AUG, QLTM
A1 Pointer to medium name
D1 Number of medium to format e.g 1 = MDV1_

*** Is this on entry?
A4 Pointer to Physical Definition Block
A6 Pointer to System variables


Regards,

Derek
Martin_Head
Aurora
Posts: 846
Joined: Tue Dec 17, 2013 1:17 pm

Re: Andy Pennell's books.

Post by Martin_Head »

Page 35
Channels I have a reference to page 155

*** Same as original book
In original book, Page 33 to Page 126.

About 2/3 of the way down the page, It starts talking about the channel table. The reference was to help me find the SuperBASIC channel information.
Probably not really needed.
Page 43
IO.OPEN D2,D3 and A1 not preserved

*** QL AUG : Same as QDOS_Companion
*** QLTM: D2,D3 Preserved, A1 ??? or Not Preserved
A1 is preserved in SMSQ/E. Not sure about Minerva. But I hit this in the MDI driver. There's a thread here viewtopic.php?f=3&t=3370&hilit=convert2&start=40#p37202 about it.

In my copy of the book I have a couple of Question marks on D2 and D3 on exit. I can't remember why.
Page 185
Format

*** QDOS Companion agrees with QL AUG, QLTM
A1 Pointer to medium name
D1 Number of medium to format e.g 1 = MDV1_

*** Is this on entry?
A4 Pointer to Physical Definition Block
A6 Pointer to System variables
Yes A4 and A6 on entry. Not sure about exit. The book says A0-A5 may be used as required.
I don't know where I got the information on A4 and A6 from. But it could have been from observations when writing the MDI and FDI Format routines


Derek_Stewart
Font of All Knowledge
Posts: 3900
Joined: Mon Dec 20, 2010 11:40 am
Location: Sunny Runcorn, Cheshire, UK

Re: Andy Pennell's books.

Post by Derek_Stewart »

Hi Martin,

Thanks for the clarification and update, I will apply the changes and update Github.

My version of the book, the pages numbers do not correspond to the original, mainly because of he reformatting of the book and I have tried to make some of the text more readable. But I will look at the Links to see if I have made errors.


Regards,

Derek
User avatar
pjw
QL Wafer Drive
Posts: 1280
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Andy Pennell's books.

Post by pjw »

Well Derek, since you ask:
Using the 18-5-2022 book's page numbers, not the PDF's

P7 Supervisor stack: should be $28480 to $28180, not $28480 to $28140

p151 Getting Parameters: OCR error at penultimate line "..and register AS
points to.." AS should be A5.

p152 Penultimate paragraph:
Line 6: "AJ in this addressing mode.." presumably AJ should be A1.

"On entry to the procedure or function, A1 is a suitable value for the top
of the stack." This is false. A better description might be:

"A1 is undefined on entry to a function or procedure. TOS can be found in
BV.RIP(a6) on entry to a procedure if need be, otherwise A1 will only point
to TOS after, for example, a call to fetch parameters."

p154:
Starting at first para:
First example: This is at best confusing and incomplete:
..
MOVE.L BV.RIP(A6),A1 new stack position possibly

There is nothing magical about A1. A1 will be exactly the same before and
after the call! The only thing that may change during BV.CHRIX is A6.

If you wanted to reserve, say, six bytes on the RI stack you could do worse
than:

Code: Select all

MOVE.L A1,BV_RIP(A6) keep some value stored on stack

or

MOVE.L BV_RIP(A6),A1 nothing on TOS or don't know/care

then

MOVEQ #6,D1	       this many bytes wanted
MOVE.W BV.CHRIX,A0   reserve room vector
JSR (A0) 	         make the call
SUBQ.L #6,BV_RIP(A6) adjust RIP to reflect
MOVE.L BV_RIP(A6),A1 new TOS
Also, here it might have been good to mention why there is no error return
from BV.CHRIX: If this call fails (due to insufficient memory) the routine
returns to the top level caller(? Not documented.)

Same page further down:

"Get parameters on to maths stack":

Code: Select all

..
"Entry: A1.L top of maths stack"      This is false

Exit:
..
A0 update pointer to top of stack:    This is false. Should be A1
A1 corrupted:			                False. See above
A2 preserved:			                Incorrect. Smashed
Also, all along the way Pennell confuses dots with underscore in the
mnemonics. There is method to why dots are used in, eg traps and vectors,
and underscores used in offsets and variables! Just another brick out of
the Jenga Tower of Babel..

I only scanned those parts of the book that I remembered had been problematic.
Common to many of the Sunshine books was that they were made in haste,
probably to cash in on the hoped for success of the QL. Both this book and the
Adder book are barely more than a rehash of The QL Technical Guide by Tony
Tebby and David Karlin, which had it been published and/or advertised in a
timely manner would have saved us all a great deal of trouble!


Per
dont be happy. worry
- ?
Derek_Stewart
Font of All Knowledge
Posts: 3900
Joined: Mon Dec 20, 2010 11:40 am
Location: Sunny Runcorn, Cheshire, UK

Re: Andy Pennell's books.

Post by Derek_Stewart »

Hi Per,

I am in the process of updating the changes, shoukd done by tomorrow.

Just a couple of points.
pjw wrote:"Get parameters on to maths stack":

Code: Select all

..
"Entry: A1.L top of maths stack"      This is false

Exit:
..
A0 update pointer to top of stack:    This is false. Should be A1
A1 corrupted:			                False. See above
A2 preserved:			                Incorrect. Smashed
Looks like the Advanced QL User Guide (QLAUG) by Adrian Dickens, is also incorrectly indicating on entry A1 pointing to the Stack.

I have OCRed the QLAUG, ut it might be a personally copy, as it might still be copyright.
pjw wrote:"
Also, all along the way Pennell confuses dots with underscore in the
mnemonics. There is method to why dots are used in, eg traps and vectors,
and underscores used in offsets and variables!
Is it better to use the Mnemonics rather than the Hex values in the QDOS Companion?
pjw wrote:"
Just another brick out of
the Jenga Tower of Babel..
Never been there...


Regards,

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

Re: Andy Pennell's books.

Post by NormanDunbar »

Just about every bit of documentation I ever read says that " on entry to a procedure or function, A1 will point to the top of the maths stack".

Many years ago, when writing DJToolkit, I spent ages debugging code that took no parameters and returned a result. That was when I discovered, and hopefully I'm remembering properly, that on entry to a procedure/function, A1 holds a value relating to the space used on the stack.

Negative, zero or positive all have different meanings. I'm away from everything at the moment, but I wrote it up for IQLR and QL Today, and it should be also in my eBook containing all the stuff I did for QL Today

Sorry about the vagueness!

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
pjw
QL Wafer Drive
Posts: 1280
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Andy Pennell's books.

Post by pjw »

Derek_Stewart wrote:Hi Per,

I am in the process of updating the changes, shoukd done by tomorrow.

Just a couple of points.
pjw wrote:"Get parameters on to maths stack":

Code: Select all

..
"Entry: A1.L top of maths stack"      This is false
<>
Looks like the Advanced QL User Guide (QLAUG) by Adrian Dickens, is also incorrectly indicating on entry A1 pointing to the Stack.
None of the official documentation supports this. Nor does experience.. ;) We've had this discussion before somewhere.
Derek_Stewart wrote:I have OCRed the QLAUG, ut it might be a personally copy, as it might still be copyright.
pjw wrote:"
Also, all along the way Pennell confuses dots with underscore in the
mnemonics. There is method to why dots are used in, eg traps and vectors,
and underscores used in offsets and variables!
Is it better to use the Mnemonics rather than the Hex values in the QDOS Companion?
To my mind, at least for the "reconstituted" version, the same mnemonics, where they are used, should be used. However, they should, ideally, be corrected as per the proper documentation. Otherwise whats the point?
Derek_Stewart wrote:
pjw wrote:"
Just another brick out of
the Jenga Tower of Babel..
Never been there...
Perhaps not but, apparently, we've all come from there..


Per
dont be happy. worry
- ?
User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: Andy Pennell's books.

Post by NormanDunbar »

My eBook is at https://github.com/NormanDunbar/QLAssem ... tober-2020.

Chapter 7.8 is where you need to be:

A1 is negative indicates something like "... 1234 * myFunc(...)" Has been executed

A1 is positive means that there are A1.L bytes available on the maths stack and calling BV_CHRIX to allocate stack space will not move the maths stack around in memory.

When A1 is zero your function is being called by itself -- " print myFunc(...)" Or at the start of an expression -- " print myFunc(...) * 1234" and so far, no bytes have been used on the maths stack.

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.
Post Reply