Advanced User Guide (AUG) [Remastered PDF]

[dv8]

Here is a completely remastered PDF of The Advanced User Guide For The BBC Micro.

A huge amount of effort has been put in to fix the errors in the original book.
This PDF should be the most accurate version of the AUG available.

• The look and layout of the original guide has been preserved.
• A large number of error corrections have been applied to the text.
• All diagrams have been redrawn in vectors.
• There is extensive hyperlinking - click on any reference to a page, chapter or section number or on any OSBYTE/OSWORD reference to jump directly to the relevant page.

There is also a disc image containing all the listings from the guide. Boot the disc or enter the command *TYPE !INDEX to see a list of programs and which section of the guide they correspond to.

Advanced_User_Guide.pdf

Seventh revision (April 2023)

(1.34 MiB) Downloaded 670 times

Advanced_User_Guide.ssd

updated on 16 March 2020

(20.25 KiB) Downloaded 653 times

Other remastered user guides in this series:

New Advanced User Guide
BBC Micro User Guide (Model B and B+ editions)
Master Reference Manual Parts 1 and 2
Advanced Master Reference Manual

[lurkio]

Wow!

[leenew]

Amazing

Lee.

[MartinB]

What I said in the Remastered NAUG thread...

[tricky]

Beautiful

[0xC0DE]

Fantastic, thank you so much!

[Elminster]

Yikes. Downloaded...... Last one. What tome of law is next?

[dv8]

What tome of law is next?

Well, the Master Welcome Guide and Reference Manuals are on the 'to-do' list but I need a break before starting another big project like that

[tom_seddon]

Nice work! Great to see the key numbers fixed, and for OSFILE to finally have the right address - I suspect this PDF will have a permanent home in my Acrobat recent files list...

I have found one new issue - on page 257, 10.2 section c should real "Locations &FD and &FE".

--Tom

P.S. A remastered version of the Master Reference Manual (volume 1 in particular) would be amazing!

[Rich Talbot-Watkins]

Nice work! Great to see the key numbers fixed

Yeah, I have enduring memories of 9 and I being the wrong way round in the AUG. (Were there other problems?)

Thanks a lot for doing this, it'll be my new indispensable Beeb reference!

[dv8]

I have found one new issue - on page 257, 10.2 section c should real "Locations &FD and &FE".

Thanks for this. I've corrected the PDF but I'll leave it a week or so before re-uploading to see if any other errors are discovered.

Yeah, I have enduring memories of 9 and I being the wrong way round in the AUG. (Were there other problems?)

I don't think there were any other mistakes in that table on p142.

There were quite a few problems with the larger keycode table in the NAUG (section 14.1), mostly internal key numbers and INKEY numbers not corresponding or decimal/hex numbers not matching. Can't remember if these errors were also present in the equivalent AUG table (appendix C).

[rmbrowngr]

Great stuff. Any thoughts on the Electron User Guide? The only copies I have are of a poor scan in pdf and a tatty copy bought from eBay.

Acorn_ElectronUG.zip

(4.73 MiB) Downloaded 117 times

[vanekp]

Electron User guide https://www.retro-kit.co.uk/user/custom ... tronUG.pdf
you can download Electron advanced uses guide here http://stardot.org.uk/mirrors/www.bbcdo ... Issue2.pdf

[dv8]

Updated the PDF to fix a few issues. Download links in the opening post

Changes since revision 1 (June 2019)

• p54 (56) BRK instruction, B flag : added text (set in P pushed on stack)
• p152 (154) OSBYTE &81 Read machine type : (INKEY &FF00) changed to (INKEY -256)
• p153 (155) OSBYTE &81 Read key : added link to 'Read machine type' entry on p152
• p257 (259) 10.2 BRK vector (c) : 'Locations &ED and &FE' should be &FD and &FE
• p272 (274) 11.3 Page two : &297-&27B should be &297-&29B
• p349 (351) 16.11 ROM Filing System, 3rd para from bottom : (&43 '#') should be (&23 '#')
• p366 (368) 18.8.1 The cursor start register (R10) : '1/16th and 1/32nd of field rate' should be '16 and 32 times field rate', added text 'When bit 6=0 and bit 5=1, the cursor is disabled.'

[dv8]

Another update with more corrections. The new PDF is in the opening post

Changes since revision 2 (June 2019):

• p127 (129) OSBYTE &0B / *FX 11 : default setting n=32 should be n=50
• p215 (217) OSBYTE &D4 / *FX 212 : default value 144 (&90) addded text 'amplitude -13'
• p216 (218) OSBYTE &D5 / *FX 213 : default value 101 (&65) should be 100 (&64)
• p217 (219) OSBYTE &D6 / *FX 214 : default value 7 should be 6
• p226 (228) OSBYTE &E4 / *FX 228 : default value for fn+SHIFT+CTRL, &A0 should be 0 - key has no effect
• p246 (248) OSBYTE &FF / *FX 255 : added link to Appendix J, added description for bit 7, added timing table for 1770/1772 FDC
• p366 (368) 18.6.3 Cursor blanking delay : 'Cursor enable signal' should be 'Cursor blanking signal'
• p483 (485) Appx.I - link options : added * to default setting for each option
• p484 (486) Appx.I - link options, S14 : descriptions wrong way round, should be OPEN=disable JIM, CLOSED=enable JIM; in the note 'link 16 must be CLOSED' should be 'link 15 must be CLOSED and R72 fitted'
• p485 (487) Appx.I - link options, S15 note : 'link 15 must be CLOSED when link 17 is OPEN' should be 'link 15 must be CLOSED and R72 fitted when link 14 is OPEN'
• p485 (487) Appx.I - link options, S16 note : 'link 16 must be CLOSED if link 14 is OPEN' should be 'link 16 must be CLOSED and R73 fitted when link 17 is OPEN'
• p485 (487) Appx.I - link options, S17 note : 'link 15 must be CLOSED' should be 'link 16 must be CLOSED and R73 fitted'
• p489 (491) Appx.J - keyboard links : added switch orientation diagram for type 2 keyboards

[dv8]

Any thoughts on the Electron User Guide?

Coming soon...

[soviet]

Awesome work, it's gonna be very useful to my have a lot lo learn.

[AndyF]

I concur, excellent work.

Thank you!

[dv8]

The PDF has been updated with some more corrections. Download link is in the opening post

Changes since revision 3 (July 2019):

• p77 (79) LSR absolute,X : always takes 7 cycles on 6502A
• p113 (115) OSBYTE 190 &BE : should be Read/write ADC conversion type
• p121 (123) OSBYTE &05 (5) *FX5,2 : added hyperlink to 'OSBYTE A=3'
• p123 (125) OSBYTE &07 (7) : added X=0 9600 baud
• p124 (126) OSBYTE &08 (8) : added X=0 9600 baud
• p125 (127) OSBYTE &09 (9) : duration is in vsync units not centiseconds
• p126 (128) OSBYTE &0A (10) : duration is in vsync units not centiseconds
• p136 (138) OSBYTE &14 (20) 3rd para from bottom : 128 (&7F) should be 127 (&7F)
• p149 (151) OSBYTE &7E (126) : added text 'the VDU paging counter will be reset, the VDU queue will be reset, any soft key expansion will be cancelled and any sound will be terminated'
• p153 (155) OSBYTE &81 (129) : moved Y=&FF,X=0 paragraph to bottom
• p163 (165) OSBYTE &8B (139) entry parameters : improved formatting
• p179 (181) OSBYTE &A0 (160) entry parameters: X contains the number of the VDU variable ; on exit: X/Y = low/high byte of variable value ; after call: removed X and Y, only C is undefined
• p198 (200) OSBYTE &BE (190) : should be Read/write ADC conversion type
• p228 (230) OSBYTE &E6 (230) action list : removed 'Escape cleared' ; added 'Reset VDU queue, Any current soft key expansion is cleared, Any sound being produced is terminated'
• p249 (251) 9.5 OSWORD &3 : changed 'chapter 12' hyperlink to sec 12.10 on p291 (293)
• p252 (254) 9.14 OSWORD &C : added hyperlink to OSWORD &B
• p278 (280) 11.4 &364 and &365 : 'input cursor' should be 'output cursor'
• p490 (492) Fig J.2 Keyboard Circuit Diagram : corrected keyboard rows, corrected 'I' and '9' positions

[chrisn]

I just found a couple of errors:

Page 400, paragraph 3: "reading" should have a capital R
Page 308, line 270: LDX &16 should be LDX #16 (to read the lightpen register)

Brilliant work, btw .. this and all the other remastered books you've done!

[RetroBob]

Wow, this is incredible work, bravo.

[dv8]

I just found a couple of errors:
Page 400, paragraph 3: "reading" should have a capital R
Page 308, line 270: LDX &16 should be LDX #16 (to read the lightpen register)

Thanks for the corrections.

I've gone through all the listings again and fixed this along with several other problems. An updated SSD image has been added to the top post.

On page 400 the lower case 'reading' is correct but the full-stop after 'high' should be a comma.

I'll get all these errors fixed in the next release of the PDF.

Thanks again.

[tom_seddon]

It's not exactly a huge problem, but the table in section 19.1.7 has a column marked "Bjt5" rather than "Bit5".

--Tom

[dv8]

It's not exactly a huge problem, but the table in section 19.1.7 has a column marked "Bjt5" rather than "Bit5".

Thanks, this will be fixed in the next release.

All corrections are welcome, no matter how small, including OCR errors like this.

[tricky]

I love these remastered book, but my Kindle says no
It says that they use features that are too new.
If you have the masters in non-PDF format, would there be a chance you could export them for kindle/ebook?
If not, I haven't tried the Amazon conversion yet, not trying to upgrade my ancient Kindle.

[dv8]

If you have the masters in non-PDF format, would there be a chance you could export them for kindle/ebook?
If not, I haven't tried the Amazon conversion yet, not trying to upgrade my ancient Kindle.

Unfortunately, it's not possible to export these guides in ebook formats.

It could be worth trying the Amazon converter, although in my experience the results are often disappointing.

While I don't fancy re-doing the whole AUG/NAUG in ebook format, I might be up for putting together a concise edition with content from selected chapters.

So, an open question to anyone reading: If I were to create a Kindle edition, what content would you find most useful?

* assembly language instruction reference
* operating system calls
* OSBYTE and OSWORD call reference
* memory map
* ROM service calls
* video CRTC / ULA registers
* VDU / PLOT code table
* keyboard ASCII / INKEY / internal code table
* anything else ?

[tricky]

I don't need it on Kindle, I just wanted to read it in the bath and my original is in the bottom of a box somewhere!

I tried Calibre, Amazon and a few others, others were poor, Calibre was a little better with Amazon the best, but still not usable where tables or diagrams were concerned.

As it is A5, the PDF would have been fine if the kindle would accept it.
Is there an option to export for earlier versions of PDF?
Is it authored in PDF, or is there another format that I could try through Amazon?

I did write a pdf2html converter, which worked quite well for RPG books (A4 mostly 2 columns), that did a pretty good job on tables, images and working out where an text wrapped around an image, but I don't fancy creating ebook files - it might be fun though and I might be able to use Amazon's author's page tool. Your manual looks easier, as there are groups of words. In the one I was converting, every character was separate so I had to workout where spaces were supposed to be and whether something was text spanning multiple columns or just columns that got close together. Unfortunately, this was while I was working away and I lost all the Java.

[dv8]

Another round of corrections. The updated PDF is in the opening post.

Changes since revision 4 (November 2019):

• p21 (23) Ch.3 example listing : line 10 should be OSWRCH=&FFEE
• p152 (154) OSBYTE &81 read machine type : US OS version should be A1.0
• p308 (310) 13.11 light pen listing : line 270 LDX &16 should be LDX #16
• p314 (316) 14.2.5 RS423 listing : line 130 SEA should be STA, line 130 RTS should be 150 RTS
• p374 (376) 18.14 hardware scroll example : line 190 REM MODIFY... should be line 210
• p379 (381) 19.1.7 table : 'Bjt5' should be 'Bit5', mode 7 entry should be &4B
• p400 (402) 22.2.1 last paragraph : the . after "output '0' high" should be a ,
• p423 (425) 23.5 sound example : line 380 should be 180
• p455 (457) Appendix B OS calls : NVRDCH should be &FFC8, NVWRCH should be &FFCB

[SamSkivington]

There is an error in both the AUG (p322) and New AUG (p298):

Reason code &07 Unrecognised OSBYTE call

When an OSBYTE call has been made and is not recognised by the
operating system, it is offered to the paged ROMs by this service call.
The contents of the A, X and Y registers at the time of the OSBYTE call
are stored in locations &EF, &F0 and &F1 respectively.

In reality, X is stored in &E5 and Y in &E4.

Hopefully this will save someone else some head scratching.

[sweh]

There is an error in both the AUG (p322) and New AUG (p298):

Reason code &07 Unrecognised OSBYTE call

When an OSBYTE call has been made and is not recognised by the
operating system, it is offered to the paged ROMs by this service call.
The contents of the A, X and Y registers at the time of the OSBYTE call
are stored in locations &EF, &F0 and &F1 respectively.

In reality, X is stored in &E5 and Y in &E4.

Hopefully this will save someone else some head scratching.

On what machine? On a model B it's definitely as the AUG describes.

It's easy to show as well

Code: Select all

OSWRCH = &FFEE
NVWRCH = &FFCB
OSNEWL = &FFE7

	ORG &8000

.start
\ ----------
\ ROM HEADER
\ ----------
	BRK
	BRK
	BRK
	JMP Service
	EQUB &82
	EQUB LO(Copyright)
	EQUB 1
	EQUS "OSB"
	EQUB 0
        EQUS "1.0 (NOW)"
.Copyright
	BRK
        EQUS "(C)"
	BRK

.Service
	CMP #7
	BEQ srv7
	RTS

.srv7
	PHA
	LDA &EF
	JSR debug1
	LDA &F0
	JSR debug1
	LDA &F1
	JSR debug1
	JSR OSNEWL
	PLA
	RTS

.debug1
	PHP
	PHA
	LDA #'<':JSR OSWRCH
	PLA
	JSR PrHex
	LDA #'>':JSR OSWRCH
	PLP
	RTS

.PrHex
        PHP
        PHA
        JSR PrHex2
        PLA
        PLP
        RTS
.PrHex2
        PHA
        LSR A
        LSR A
        LSR A
        LSR A
        JSR PrNyb
        PLA
.PrNyb
        AND #15
        CMP #10
        BCC PrDig
        ADC #6
.PrDig
        ADC #48
        JMP NVWRCH

.end

SAVE	"foo.rom",start,end

With that ROM loaded if I do a test osbyte call I get the output:

Code: Select all

>*FX114 20 30
<72><14><1E>
>

So it's clear that &EF, &F0, &F1 hold the three correct values.