New Advanced User Guide (NAUG) [Remastered PDF]

[TobyLobster]

The smallest of all possible errors: p129 section 8.6 refers to "IRQV2", but everywhere else this is called "IRQ2V"

[dv8]

The smallest of all possible errors: p129 section 8.6 refers to "IRQV2", but everywhere else this is called "IRQ2V"

Thanks. This will be corrected in the next release.

[6502]

Spotted another little boo boo.

Page 102

NVWRCH is labelled as non-vectored read character.
NVRDCH is labelled as non-vectored write character.

Fantastic work by the way. I'm really impressed. Shame I can't have it in a compact ring binder book.

[dv8]

Spotted another little boo boo.

Thanks.
It looks like these calls are also wrong in the AUG.
I'll get it fixed in the next release of both books.

[6502]

What's this on page 113 about?

Code: Select all

6.5.3 OSWRSC
Call address &FFB3
Not indirected
Entry parameters:
Least significant byte of the address to be written in location &D6
Most significant byte of the address to be written in location &D7
A=value to be written
On Exit:
A, X and Y are preserved.
This call is not available from second processors.

&FFB3 in OS 1.20 is &00 BRK

It's also mention on the table on page 102.

[TobyLobster]

Here's another in my small collection of "but does this really matter? I'm just being overly pedantic now" issues: there's a typo at the top of P363, 'funtions' instead of 'functions'.

[dv8]

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

Changes since revision 4 (April 2020):

• p102 (110) 6.1 OS calls : NVWRCH &FFCB should be 'Non-vectored write', NVRDCH &FFC8 should be 'Non-vectored read'
• p129 (137) 8.6 user VIA interrupts : IRQV2 should be IRQ2V
• p159 (167) 12.2 memory use OSBYTEs : added OSBYTE &EF (239) - read/write flag used by OSBYTE &72
• p173 (181) 13.1.6 OSBYTE &B6 : added hyperlink to Master OSBYTE &B6 - read/write use printer ignore char
• p206 (214) 13.3.13 VIDCON general summary table : mode 7 entry should be &4B
• p363 (371) 19.6 top paragraph : 'funtions' should be 'functions'
• p421 (429) 24.1.5 OSBYTE &FF : call address should be &FFF4
• p422 (430) 24.2.2 OSBYTE &F5 : section moved from page 423
• p423 (431) 24.2.4 OSBYTE &F6 : section renumbered from 24.2.3
• p423 (431) 24.2.5 OSBYTE &B6 : added new section for read/write use printer ignore char
• p424 (432) 24.2.6 UPTV : section renumbered from 24.2.4
• p425 (433) 24.2.7 OSBYTE &7B : section renumbered from 24.2.5
• p428 (436) 24.4.1 OSBYTE &81 read machine type : US OS version should be A1.0
• p436 (444) Appendix A : added hyperlink for Master OSBYTE &B6 - read/write use printer ignore char
• p437 (445) Appendix A : added hyperlink for OSBYTE &EF - read/write shadow state
• p438 (446) Appendix A : OSBYTE &F5 entry updated to page 422

[lurkio]

Another round of corrections.

Tremendous! Thank you!

[Coeus]

What's this on page 113 about?

Code: Select all

6.5.3 OSWRSC
Call address &FFB3
Not indirected
Entry parameters:
Least significant byte of the address to be written in location &D6
Most significant byte of the address to be written in location &D7
A=value to be written
On Exit:
A, X and Y are preserved.
This call is not available from second processors.

&FFB3 in OS 1.20 is &00 BRK

It's also mention on the table on page 102.

It's for writing to screen memory when shadow RAM is present. Let's trace it.

Code: Select all

F402: 20 AB F3    JSR F3AB    >s
F3AB: 48          PHA
F3AC: 48          PHA
F3AD: 48          PHA
F3AE: 08          PHP
F3AF: 48          PHA
F3B0: DA          PHX
F3B1: BA          TSX
F3B2: BD 08 01    LDA 0108,X
F3B5: 9D 05 01    STA 0105,X
F3B8: BD 07 01    LDA 0107,X
F3BB: 9D 04 01    STA 0104,X
F3BE: A9 F3       LDA #F3     ; This sets the address our caller will return to (1)
F3C0: 9D 07 01    STA 0107,X 
F3C3: A9 D6       LDA #D6
F3C5: 9D 06 01    STA 0106,X
F3C8: AD 34 FE    LDA FE34    ; Fetch the current value of ACCCON which controls some memory mapping.
F3CB: 9D 08 01    STA 0108,X
F3CE: A9 08       LDA #08     ; map out the 8K filing system RAM - see Master Ref Manual Pt1, Page F2-3, bit Y
F3D0: 1C 34 FE    TRB FE34    >s
F3D3: FA          PLX
F3D4: 68          PLA
F3D5: 28          PLP
F3D6: 60          RTS

F405: 4C 5F DB    JMP DB5F

Note that this address DB5F is within the area of the OS that gets overlaid by this filing system RAM which is why we had to make sure that RAM was paged out. But this area also has another special property in that hardware detects when the instruction is fetched from this area and, when it is, makes sure an access to the shadow screen area goes to the bank being displayed.

Code: Select all

DB5F: 91 D6       STA (D6),Y  ; So this is doing the actual write.  Note that Y is included and the documentation said nothing about that.
DB61: 60          RTS         >s

F3D7: 08          PHP         ; Note we're now at the address put on the stack at (1) +1
F3D8: 48          PHA
F3D9: DA          PHX
F3DA: BA          TSX
F3DB: BD 04 01    LDA 0104,X ; get the saved value of ACCON back.
F3DE: 20 B0 ED    JSR EDB0
EDB0: 29 08       AND #08     ; isolate bit Y (8K filing system RAM).
EDB2: D0 08       BNE EDBC    ; if it was set previously...
EDBC: 0C 34 FE    TSB FE34    ; set it.
EDBF: 60          RTS
F3E1: BD 03 01    LDA 0103,X
F3E4: 9D 04 01    STA 0104,X
F3E7: FA          PLX
F3E8: 68          PLA
F3E9: 28          PLP
F3EA: 28          PLP
F3EB: 60          RTS

So just a documentation bug here in failing to mention that Y is added as an offset to the address in &D6/&D7.

And another documentation bug on page 102 - while OSRDSC will read from the ROM of your choice (it was OSRDRM on the BBC B), OSWRSC does nothing with paged ROMs or sideways RAM - the code clearly shows it does nothing with &F4 and &FE30.

Then looking down the set of addresses, I wonder what is at &FFBC and &FFB6.

[SteveF]

Code: Select all

DB5F: 91 D6       STA (D6),Y  ; So this is doing the actual write.  Note that Y is included and the documentation said nothing about that.

So just a documentation bug here in failing to mention that Y is added as an offset to the address in &D6/&D7.

I just stumbled across this myself and came here to report it only to find this post a few days ago, quite a coincidence. BeebWiki had this wrong too, I've just fixed the page there: http://beebwiki.mdfs.net/OSWRSC

[SteveF]

Very small typo: on page 298 (according to the page numbers at the bottom)/306 (according to my PDF viewer):

An OWORD call with A=7 (equivalent to the SOUND command in BASIC) which has been given an unrecognised channel will also generate this service call.

(My emphasis)

[dp11]

Small error on page 30

The number of instruction cycles taken for the
execution of the instruction in each addressing mode is also given (1
instruction cycle=0.5µs in a BBC model B, 0.33µs in Master or 6502 2nd
processor, 0.25µs in a Master Turbo 2nd processor)

should be :

The number of instruction cycles taken for the
execution of the instruction in each addressing mode is also given (1
instruction cycle=0.5µs in a BBC model B or Master, 0.33µs in a 6502 2nd
processor, 0.25µs in a Master Turbo 2nd processor)

[roland]

On page 423 is Phi2 assigned to pin A8 of the Electron cartridge. However in the original user guide that pin is Phi0. What is the correct one?
(I could open a Plus 1 and follow the trace but that's to much work for now )

[paulb]

On page 423 is Phi2 assigned to pin A8 of the Electron cartridge. However in the original user guide that pin is Phi0. What is the correct one?
(I could open a Plus 1 and follow the trace but that's to much work for now )

This was covered in a previous discussion about flash memory interfacing.

[KenLowe]

The table on page 154 is missing a reference to the Econet Station ID register (&FE18) for the Model B. See here for further details:

viewtopic.php?p=360408#p360408

[dv8]

The PDF in the opening post has been updated to revision 6.

Changes since revision 5 (January 2021):

• p30 (38) 5.2 Assembler Mnemonics, 2nd to last para : should be 0.5µs for BBC model B or Master
• p102 (110) 6.1 OS Calls : OSWRSC does not write to paged ROM
• p113 (121) 6.5.3 OSWRSC : Y register is added to base address in &D6/D7
• p121 (129) 7.2 OSBYTE &0D/&0E : removed Y=0 from entry parameters
• p154 (162) 11 SHEILA table : added &18 Econet station number for Model B/B+
• p158 (166) 12.2 OSBYTE &70 : removed Y=0 from entry parameters
• p159 (167) 12.2 OSBYTE &71/&72 : removed Y=0 from entry parameters
• p162 (170) ACCCON &FE34 IFJ : 1 = cartridge at &FC00-&FDFF
• p178 (186) 13.1.8 OSBYTE &09 : removed Y=0 from entry parameters
• p179 (187) 13.1.8 OSBYTE &0A : removed Y=0 from entry parameters
• p224 (232) 14.7 OSBYTE &0B : removed Y=0 from entry parameters
• p224 (232) 14.8 OSBYTE &0C : removed Y=0 from entry parameters
• p225 (233) 14.9.1 OSBYTE &04 : removed Y=0 from entry parameters
• p241 (249) 15.3.2 OSBYTE &03 : removed Y=0 from entry parameters
• p298 (306) 17.4.1 reason code &08 : 'An OWORD call with A=7' should be 'An OSWORD call'...
• p347 (355) 18.9 OSWORD &05/06 : &FFFExxxx writes to 12K paged/sideways RAM on B+
• p386 (394) 22.3.2 Addressable latch B4,5 : 20K screen should be B5=1,B4=0 ; 10K should be B5=1,B4=1
• p413 (421) 23.7 OSBYTE &6B : removed Y=0 from entry parameters
• p415 (423) 23.7.2 Cartridge bus signal definitions : added hyperlinks to descriptions
• p415 (423) 23.7.2 Cartridge bus signal definitions : PHI2 (A-8) is PHI0 on the Electron
• p416 (424) 23.7.2 Cartridge bus signal definitions : PHI2 is PHI0 on the Electron
• p418 (426) 23.7.2 Cartridge bus signal definitions : AGND is pulled up to 5V with a 4K7 resistor on the Electron
• p418 (426) 23.7.2 Cartridge bus signal definitions : ADIN is n/c on the Electron
• p429 (437) 24.5.1 : added new section for NETV vector
• p431 (439) 24.5.2 : added new section for KEYV vector
• p442 (450) Index, under BRK : 'ERK vector' should be 'BRK vector'

Thanks to everyone who submitted corrections.

[Deleted User 13004]

Thank you for update to this oh-so-useful PDF version of the NAUG

[TobyLobster]

Just a couple of minor formatting consistency things around OSBYTE calls:

1. All OSBYTE calls show parameter A formatted like this "A=&B5 (181)", except:

p241 "A=&02 (*FX2)"
p241 "A=&03 (*FX3)"
p242 "A=&07 (*FX7)"
p242 "A=&08 (*FX8)"

2. p109, OSBYTE call 236 has:

"Read/write output stream flag OSBYTE call
A=&EC (236) Read/write output stream flag OSBYTE call"

It's correct but doesn't need the second "Read/write output stream flag OSBYTE call" comment.

[TobyLobster]

p157 "Entry paramter:" should read "Entry parameter:"

[TobyLobster]

p145 "the instructions “LDA (&FA),Y” will be required" -> should be "instruction" singular.

[dp11]

Page 35/Page 36 BBR/BBS take one extra cycle if the branch is taken.

[dp11]

Page 344 "a BBC series micro (i.e. 3 MHz)" should be "a BBC series micro (i.e. 2 MHz)"
Page 408 At the bottom. The Master CPU is clocked at 2MHz not 4MHz

[AndyGarton]

Just wanted to say thank you for these remastered manuals, they’re brilliant and I’m getting a lot of enjoyment from them. Is there any chance we might see the Master 128 Welcome Guide and Master 512 User Guides also please?

[dv8]

The PDF in the opening post has been updated to revision 7.
The SSD image has also been updated with a correction to the Tube Transfer ROM listing.

Changes since revision 6 (June 2022):

• p35 (43) 5.2 BBR : should take 5 cycles +1 if branch taken, +2 if to new page
• p36 (44) 5.2 BBS : should take 5 cycles +1 if branch taken, +2 if to new page
• p45 (53) 5.2 BRK : 'facilites' should be 'facilities'
• p109 (117) 6.2.11 OSBYTE &EC : removed redundant text 'Read/write output stream flag OSBYTE call'
• p120 (128) 7.1 event 3 ADC conversion complete : channel number returned in X not Y
• p145 (153) 9.10 OSBYTE &98 (a) last para : 'instructions' should be 'instruction'
• p157 (165) 12.2 OSBYTE &85 : 'Entry paramter' should be 'Entry parameter'
• p158 (166) 12.2 OSBYTE &70 X=0 : 'ie' should be 'i.e.'
• p168 (176) 13.1.2 VDU23 : 'ie' should be 'i.e.'
• p196 (204) 13.3.9 Light Pens : 'ususally' should be 'usually'
• p241 (249) 15.3.1 OSBYTE &02 : replaced (*FX2) with (2)
• p241 (249) 15.3.2 OSBYTE &03 : replaced (*FX3) with (3)
• p242 (250) 15.3.3 OSBYTE &07 : replaced (*FX7) with (7)
• p242 (250) 15.3.4 OSBYTE &08 : replaced (*FX8) with (8)
• p250 (258) 16.1 Filing system calls : 'cassettte' should be 'cassette'
• p259 (267) 16.2 Master Filing Systems : 'Auxilary' should be 'Auxiliary'; 'facilites' should be 'facilities'; 'relevent' should be 'relevant'
• p266 (274) 16.3.3 Sector 1 &0E : 'signifcant' should be 'significant'
• p267 (275) 16.3.4 ADFS : 'facilites' should be 'facilities'
• p270 (278) 16.4 Introduction : 'memoires' should be 'memoirs'
• p287 (295) 17.2 Paged ROM/RAM installation : 'Prgrammable' should be 'Programmable'
• p304 (312) 17.4.1 Reason code &FE : On entry Y=&FF if tube present, Y=0 if absent.
• p331 (339) 18.5 6502 second processor, para 3 : 'miniscule' should be 'minuscule'
• p344 (352) 18.8 Tube Transfer ROM : removed top para 'The timing delay loops...'
• p346 (354) 18.8 Tube Transfer ROM listing : replaced delays with more sensible values for 2MHz processor
  1050 LDX #6
  1110 NOP
  1120 NOP
  1130 NOP
• p408 (416) 23.5 Cleaning up NPGFC/NPGFD : removed incorrect reference to 4MHz CPU on Master
• p409 (417) 23.5.1 Problem 1 : 'labeled' should be 'labelled'
• p415 (423) 23.7.2 Cartridge bus signal definitions : on the Electron A-20 is pulled up to +5V and A-21 is n/c

[andrew_rowland]

OMG This is amazing! Thank you so much. What a magnificent job -- and the time it will save me too!

[james]

p103 / 6.2.1 OSWRCH Write character routine
This routine outputs the character in the accumulator to the currently selected input stream(s).

Should be “output stream(s)”

[jgharston]

KEYV:
Various callers rely on the return from VC+CC to be in *both* the flags *and* the A register.

C=0, V=0
Test the SHIFT and CTRL keys,
exit with the N (minus) flag set and A bit 7 set if the CTRL key is pressed,
and the V flag (overflow) flag set and A bit 6 set if the SHIFT key is pressed.

In other words, b7+b6 of the flags and b7+b6 of A should be the same. This
can be done before returning to the KEYV caller by doing PHP:PLA if the flags
have been set up correctly.

This bit me several times when writing keyboard drivers. The VDU driver reads the returned flags, but the Startup routine reads the returned A register.

C=1, V=0
Scan the keyboard. Exactly as Called by OSBYTE call &79, OSBYTE &7A and OSBYTE &81
add: On entry, X=&00-&7F scan range, X=&80-&FF scan for single keypress
On exit, the accumulator is equal to the X register. add: with bit 7
set if the requested key is pressed.

[james]

P321 / 17.6.1 OSRDRM, read byte from paged ROM routine

Should, I think, be OSRDSC (to match the renaming everywhere else)

Hmmm. OSRDRM turns up in a number of places. So maybe best to leave it alone.