Jeff's VIC 20 Book

[Jeff-20]

I like the line and block characters on page 15, I recently had to work some of these out myself. Perhaps the cell background should be light grey, that way it is easier to see where the set pixels are?

Great suggestion! I'll try it. Question for you: Do you approve of the machine language section? Pages 48 to around 59.

[srowe]

Great suggestion! I'll try it. Question for you: Do you approve of the machine language section? Pages 48 to around 59.

Some of the tables I'd find more useful with hex values, but I think you're going for the widest audience and, therefore, having decimal for POKEs makes sense. Perhaps have a light grey background for the instructions at the bottom of pages 50 & 51 to make them stand out a little?

A few more corrections:

Page 51: 'BPL' needs to be '2+'

Page 52: 'LSR' needs to be 'N Z C' (to match 'ASL')

Page 54: 'CINT' & 'IOINIT' don't exist, I think they were added to the C64 KERNAL

Page 55: 'LOAD', .A is the load/verify flag
'SECOND' & 'TKSA' the SA must be ORed with $60
Delete 'CINT' & 'IOINIT' as above

Page 58: The baud rates 4800 and above just don't exist

Page 59: 'M51AJB' user-defined baud rates are not implemented, these locations are never read
Last table, 'FLG2' & 'PA2' are the C64 pins

Page 66: 'User Port', again these are C64 pinouts

Page 68: 'A World at War' code is 'VIC-7303'

Page 70: 'Space Snake' code is 'VIC-7301'

[Jeff-20]

A few more corrections:

Awesome notes and info! I'll work on these later tonight, if I can! Thank you!

[Jeff-20]

I think I am almost ready to release a first official draft for the new year. Ready for final edits (or additions). Please take a look. I added more familiar ML tables and other stuff discussed here.

https://www.sleepingelephant.com/denial ... aftv01.pdf

I'd like to have an official public domain PDF release early in the year.

[Mike]

Jeff, I made a similar remark earlier in this thread already: beginning with page 38, the listing of the entry points into the BASIC interpreter ($C000 onwards) and KERNAL ($E4A0 onwards) is practically useless without an accompanying ROM listing! Also in pages 49..51, mixing zeropage, I/O addresses, ROM routines, OS workspace addresses and then sorting them alphabetically completely destroys any inner structure that might be inherent due to the original address order. I could not imagine using that list for reference myself, sorry.

There are some smaller issues I'll put in a more comprehensive list later.

This one beforehand: you should consider replacing the UNNEW/OLD on page 91 with the method I published here:

viewtopic.php?t=6563&start=32

(see the PRINT/SYS statement at the bottom of the post): this one doesn't need to be installed - it can still be used after a NEW 'mishap' without destroying what was supposed to be rescued!

[srowe]

A few more observations:

Pages 10-13 - summary of BASIC commands

DEF FN, the pseudo example misses the fact a function name is required, i.e. something like DEF FN<name>(X)=<formula>

FOR...TO..STEP, the psuedo example needs the step increment, i.e. FORX=<start>TO<limit>[STEP<increment>]

Page 56, there is no immediate mode ASL instruction, it should be accumulator mode
Page 59, there is no immediate mode LSR instruction, it should be accumulator mode
Page 60, there are no immediate mode ROL or ROR instructions, they should be accumulator mode

Page 80, "Programmers Aid", or "Programmer's Aid" or "Programmers' Aid" (the manual and label are contradictory)

Page 83, "IEEE-488 Cartridge" is number VIC-1112, it has a 2K ROM in it
"Machine Language Monitor" has a 4K ROM in it

Page 96, Non-standard error code 240 is returned by OPEN and CLOSE for an RS-232 device

Final page, The following have the wrong parameter: ASC() CHR$() STR$()

[chysn]

In the instruction reference, all of the (indirect),y instructions are templated with ,X (see, for example, ADC).

[Jeff-20]

Thank you for the feedback, everyone!

Mike, I really value your input but seem to be missing some of your suggestions.

Jeff, I made a similar remark earlier in this thread already: beginning with page 38, the listing of the entry points into the BASIC interpreter ($C000 onwards) and KERNAL ($E4A0 onwards) is practically useless without an accompanying ROM listing!

Yes, I recall removing it and adding it back again. I was using Russ Davies' Mapping the VIC as a guide and think I felt there was intrinsic value in having the information included. You seem to feel strongly about it. Could you help me better understand? What do you mean by accompanying ROM listing? Or are you suggesting this all be removed to save pages?

Also in pages 49..51, mixing zeropage, I/O addresses, ROM routines, OS workspace addresses and then sorting them alphabetically completely destroys any inner structure that might be inherent due to the original address order. I could not imagine using that list for reference myself, sorry.

I wanted a compact index (cross reference) to recall where things are in the previous listing. For example, I listed the BASIC entry points elsewhere, but something like "STOP" (test stop key) could be looked up alphabetically and referenced in the previous sequential listing. Do you think this kind of inclusion is problematic? Do you think it just needs to be sorted into groups or removed all together?

There are some smaller issues I'll put in a more comprehensive list later.

Yes, please. Do not let my questions/misunderstandings discourage you.

This one beforehand: you should consider replacing the UNNEW/OLD on page 91 with the method I published here:

Yes! I will trade it out right away. How should I credit you? Thanks!

A few more observations:

Thank you, srowe! Excellent notes. I am correcting these points today!

Page 80, "Programmers Aid", or "Programmer's Aid" or "Programmers' Aid" (the manual and label are contradictory)

I have also noticed this. I figured I would just pick one and stick to it. I am likely the only one using this book, and I haven't used the Aid yet.

Page 96, Non-standard error code 240 is returned by OPEN and CLOSE for an RS-232 device

Could you please explain? I don't remember from which book I got this information?

Final page, The following have the wrong parameter: ASC() CHR$() STR$()

Thanks! More typos! Argggh. However, I believe ASC() does require a string. Correct?

In the instruction reference, all of the (indirect),y instructions are templated with ,X (see, for example, ADC).

Thanks, chysn! I knew copy and paste was a false shortcut. Corrected.

[Mike]

"Yes, I recall removing it and adding it back again. I was using Russ Davies' Mapping the VIC as a guide and think I felt there was intrinsic value in having the information included. You seem to feel strongly about it. Could you help me better understand? What do you mean by accompanying ROM listing? Or are you suggesting this all be removed to save pages?

First, the symbol names: even if many of those are somewhat universally accepted, these are labels from the original source code of BASIC and KERNAL, and as such these just don't easily tell what they're for, even less how they should be called, i.e. used.

Most routines in the BASIC interpreter need the CPU registers, OS workspace (zeropage, buffers) and possibly even tokenized program text being set up in a very delicate way so they can perform their intended function. The interpreter itself takes care about this by executing all those routines in a sensible order as it steps along the BASIC program, keeping information in its workspace in sync.

Each of these routines would deserve at least half a page of documentation, so it could be sensibly used by code outside the interpreter. Such a documentation still might miss out on the finer aspects of the routine's operation. More likely - what I've been doing all the years! - one would consult a ROM listing, i.e. a thoroughly commented disassembly of the entire ROM. Here, all information can be extracted to fit own routines into the gears of the BASIC interpreter.

In tendency, the KERNAL contains more routines that can be used by an own program, but again you need CPU registers and other things being set up correctly. But there also quite some routines here to keep up the heartbeat of the VIC-20: you'd practically never go and call these routines from outside, they're executed as they're sequenced from higher level routines - the system interrupt, the screen editor, and the tape and RS232 routines are fine examples for this.

That means, yes, the complete list in pages 38 from $C000 onwards upto $FF8A could go. $FF8A onwards contains the KERNAL jump table that you cover at another place - it's up to you whether to keep those or not. Personally, I prefer them sorted by address, not alphabetically, as the former method keeps the calls grouped by function ...

I wanted a compact index (cross reference) to recall where things are in the previous listing. For example, I listed the BASIC entry points elsewhere, but something like "STOP" (test stop key) could be looked up alphabetically and referenced in the previous sequential listing. Do you think this kind of inclusion is problematic? Do you think it just needs to be sorted into groups or removed all together?

... and this is what is destroyed by this 'index' on pages 49..51. It lumps zeropage and OS workspace variables, I/O registers (VIC and VIAs) and ROM entry points into one big list and the alphabetically sorted result is just unusable for any kind of reference (those are the most kind of words I could find to describe what I've otherwise just call a big mess. Sorry.)

Yes, please. Do not let my questions/misunderstandings discourage you.

srowe and chysn already have pointed out some issues, I'll add a few remarks later - I found it important to give you an early and more detailed reply concerning the two paragraphs you asked about.

In general I'd prefer you think about where you duplicate information. Not only does this waste space (and there's no need to increase page count!) it also might result in contradictory info, as srowe already has pointed out. Less is more. Unless it omits vital parts: with my memory map for example, I took quite some time to think about what should be in there, and what not. Whatever you omitted from it when you transferred it to your document, let me tell you - you missed out on important information! I will gladly explain that in more detail if you want.

[Jeff-20]

"Yes, I recall removing it and adding it back again. I was using Russ Davies' Mapping the VIC as a guide and think I felt there was intrinsic value in having the information included. You seem to feel strongly about it. Could you help me better understand? What do you mean by accompanying ROM listing? Or are you suggesting this all be removed to save pages?

First, the symbol names: even if many of those are somewhat universally accepted, these are labels from the original source code of BASIC and KERNAL, and as such these just don't easily tell what they're for, even less how they should be called, i.e. used.

Thanks for explaining further. I found what I was trying to do in Mapping the VIC here on page 338: https://archive.org/details/Computes_Ma ... 9/mode/2up

The cross-reference is not intended to show how these areas are used. They're just meant to help a reader find a label more quickly (assuming you already know or use the location by that label). The alphabetical listing is meant to reference the sequential listing. It is far from a comprehensive guide with annotated disassembly. I understand it not being useful to you, but it seems you might find it actually detrimental to include. Do you think the Compute guide has also made a mistake to include it?

There are plenty of intentional redundancies in the book. For example, the hex table on page 62 is meant to be a slightly faster reference for information already found on pages 2-9. These choices may be just for me. I don't think this project will replace long-standing books and online guides including your memory map.

[srowe]

Page 96, Non-standard error code 240 is returned by OPEN and CLOSE for an RS-232 device

Could you please explain? I don't remember from which book I got this information?

I've not seen a clear explanation of why this is done but it seems to indicate that the top of memory has changed to allocate/free the two buffers. It's documented in pages 325 & 266 of "Compute's VIC-20 Tool Kit KERNAL".

Final page, The following have the wrong parameter: ASC() CHR$() STR$()

Thanks! More typos! Argggh. However, I believe ASC() does require a string. Correct?

You're right, ASC() is correct, just CHR$() and STR$() should take numeric arguments.

[Jeff-20]

Typo corrections in progress: https://www.sleepingelephant.com/denial ... ftv01b.pdf.

[srowe]

A few I missed to spot before:

Page 5 - all the bit patterns are missing b5 being set

Page 6 - 140/$8C is F8

Page 38 - IO2 is 38912-39935, IO3 is 39936-40959. I don't understand the comment 'unreliable reflections'

Page 74 - expansion port pinout, IO2 is at $9800

[Mike]

Page 80, "Programmers Aid", or "Programmer's Aid" or "Programmers' Aid" (the manual and label are contradictory)

From what I see, cartridge label, box art and manual all feature "Programmer's Aid" (singular possessive case with apostrophe-s, and without trailing "e" as in "Aide"), it is just the start-up prompt after SYS 28681 that tells "Programmers' Aid" (i.e. plural possessive case with s-apostrophe). Just my 2 cents.

[Jeff-20]

I am starting a new thread for a new draft of my book project. The PDF should be viewed in two page mode. It is arranged as front cover, front cover interior, and so on...)

I started working on it again and had a test copy made. I determined the book needs to be at least 128 pages for proper "feel" (as well as a page count divisible by 16 for printing concerns).

The purpose of the handbook is a "quick reference", so please look at the PDF with that in mind. It may not meet the needs or tastes of all.

A blank page was inserted after the front cover so viewing the PDF in two-page mode will give the intended "lay-flat" appearance. Please alert me to any errors you see. I also welcome suggestions.

PDF

My plan is to print a handful of copies for anyone that wants one and make the PDF available to others.