The Hitchhiker's Guide to GEOS v2020

pbm66 · Oct 24th 2020

This is the soon to be released digital update to the original The Hitchhiker's Guide to GEOS. It is fully hyperlinked and setup specifically for use in PDF readers. Weighing in at 808 pages and 194k words is has everything the original had and more.

This is to be a companion release with the new geoProgrammer' 2.0. The 2.0 version has the upgrades that were planned but never released by Berkeley plus lots more features that were not on the 2.0 roadmap.

Looking for beta readers to get feedback before final release.

Also look for someone interested providing a translation into German.

pbm66 · Oct 25th 2020

Sample API page. All of the bold Variable and API entries are linked (and other types as well). Clicking on curDrive will take you to the Variable declaration with all of the information related it.

zorro · Oct 25th 2020

I would be interested in providing a translation to german. Although 808 pages are a lot. What is the timeframe?

pbm66 · Oct 25th 2020

There would be no real timeframe on the translation. The release of geoProgrammer' 2.0 and the english version do not need to happen at the same time.

So really the time frame would be up to you.

syshack · Oct 25th 2020

Would be interested to read it, even if beta, do you have any link for a download?

pbm66 · Oct 25th 2020

Quote from syshack

Would be interested to read it, even if beta, do you have any link for a download?

Message sent with link...

zorro · Oct 25th 2020

Message sent

pbm66 · Nov 5th 2020

Sample from the atom section... Part of the new additional content

strik · Nov 5th 2020

Alternative nib2hex, another size-optimized version (8 byte, 16 cycles):

Code

sed ; (2 cycles)
clc ; (2 cycles)
adc #$90 ; (2 cycles)
adc #$40 ; (2 cycles)
cld ; (2 cycles)
rts ; (6 cycles)

This routine is best suited if you want to convert multiple nibbles at once (omitting the sed/cld sandwich, and thus, 4 cycles)

pbm66 · Nov 5th 2020

That is a new trick to me, excellent. If you want I will give you credit for its inclusion as I had yet to have discovered this oddity of decimal mode and will add it to the manual as another alternative.

Thanks

FeralChild · Nov 5th 2020

What about the interrupts? AFAIK the standard C64 interrupt handlers are not compatible with decimal mode.

strik · Nov 5th 2020

Quote from pbm66

That is a new trick to me, excellent. If you want I will give you credit for its inclusion as I had yet to have discovered this oddity of decimal mode and will add it to the manual as another alternative.

That's a known trick that works with many machines. I don't need the credits for this one.
I once knew a source where it seems to be mentioned for the first time, but I do not remember now. I know, however, that L.A. Leventhal has it in his 6502 book.

Quote from FeralChild

What about the interrupts? AFAIK the standard C64 interrupt handlers are not compatible with decimal mode.

That's right. I should have mentioned that one must be careful when using it.
In fact, I have used it mostly in interrupt routines themselves, so this was not a problem.

From my point of view, this version works best of you want to convert multiple values at once: SEI/SED, then convert everything, then CLD/CLI.

For a subroutine, it might not be best suited.

pbm66 · Nov 5th 2020

"The Decimal Mode Flag

GEOS adopts the convention that the normal operating state of the computer has decimal mode disabled. Any

routine that enables decimal mode must also disable it. Versions of GEOS 64 prior to v1.2 do not disable decimal

mode during interrupt level processing. If operating under one of these versions, it is necessary to disable

interrupts prior to using the decimal mode flag."

I had checked with the GEOS section on decimal mode. The GEOS interrupt handlers post 1.2 are able to deal with Decimal Mode being active when the interrupt starts. This would take some research to see if that makes it safe to use anytime while in GEOS.

strik · Nov 5th 2020

From http://www.6502.org/tutorials/decimal_mode.html, even shorter (6 byte, 14 cycles) and slightly modified to not use undocumented behaviour:

Code

CMP #$0A ; 2 cycles
SED ; 2 cycles
ADC #$30 ; 2 cycles
CLD ; 2 cycles
RTS ; 6 cycles

Even with an additional SEI/CLI sandwich, we get 8 byte / 18 cycles.

pbm66 · Nov 5th 2020

Just played with that in the debugger. cmp #$0A is setting the carry flag. 0-9 has carry clear and A-F has carry set. in BCD $30 + $0A + carry = $41. Back to binary mode and that is 'A'.

Tested this in VICE and it does correctly handle the "undocumented" behavior of the BCD mode. I wonder why it was not originally documented. It "seems" like intentional designed behavior but perhaps not.

This is for sure the size winner. Too bad that it is undocumented and therefore not guaranteed to be supported in every virtual environment.

strik · Nov 5th 2020

Oh, the way I wrote it does not use undocumented behaviour.

That's why I swapped the CLD and the CMP w.r.t. the document I linked to: In BCD mode, the CMP behaviour is not document.

As I use the CLD only after this, though, this is all inside of the 6502 defined behaviour.

pbm66 · Nov 6th 2020

True, but the natural progression would be to batch it up and that would then require going back and forth from BCD to stay documented. As a standalone library entry with comments warning of about the undocumented nature of using that code in a loop without the sed/cld being used every time. Which of course would be the natural way someone would want to do it.

There needs to be a retro standards body that can make "official" previous undocumented behaviors , so long as those behaviors where the same with every known version of the CPU's. Looking way into the future.. People playing with now century old tech in the year 2120 would not care that the BCD behavior only became officially documented in 2020.