Discussion:
An open letter to The AppleWin Team about APPLE2E.SYM
(too old to reply)
James Davis
2019-10-22 16:30:23 UTC
Permalink
;==============================================================
; An open letter to The AppleWin Team about APPLE2E.SYM
;==============================================================

;--------------------------------------------------------------
; **[Best viewed in a monotyped font like 12pt. Courier New]**
;--------------------------------------------------------------

I changed the heading a little bit
[on my personal copy of the APPLE2E.SYM]:

; Apple 2 Rom Symbol Table
; Version 5 Renamed "KBD/CLR80COL" -> "KBD/CLR80STORE"
; Renamed "SET80COL" -> "SET80STORE"
; Renamed "CLR80VID" -> "CLR80COL"
; Renamed "SET80VID" -> "SET80COL"
; Renamed "RD80COL" -> "RD80STORE"
; Renamed "RD80VID" -> "RD80COL"

;--------------------------------------------------------------

I also added these to AppleWin's APPLE2E.SYM to fill in a few of the
gaps you guys left empty:

C01B RDMIXED
C01D RDHIRES
C040 STROBE
C063 BUTN2
C065 PADDL1
C066 PADDL2
C067 PADDL3

;==============================================================
*** WARNING: ANNUNCIATOR TERMINOLOGY WAS COUNTER INTUITIVE! ***
[See (Apple II Errata): Tech Info Library Article Number 1062.]
;==============================================================

So, I fixed these [on my personal copy of the APPLE2E.SYM]:

AppleWin's APPLE2E.SYM FORMAT:

;--------------------------------------------------------------
; Corrected Annunciator Labels [See Tech Info Library Errata]
;--------------------------------------------------------------
C058 CLRAN0
C059 SETAN0
C05A CLRAN1
C05B SETAN1
C05C CLRAN2
C05D SETAN2
C05E CLRAN3
C05F SETAN3
;--------------------------------------------------------------

{
6502bench SourceGen Disassembler SYM65 FORMAT (with comments):

;--------------------------------------------------------------
; Corrected Annunciator Labels [See Tech Info Library Errata]
;--------------------------------------------------------------
CLRAN0 @ $C058 ;[R/W] Reset AN0: Toggle OFF (0VDC)
SETAN0 @ $C059 ;[R/W] * Set AN0: Toggle ON (+5VDC)
CLRAN1 @ $C05A ;[R/W] Reset AN1: Toggle OFF (0VDC)
SETAN1 @ $C05B ;[R/W] * Set AN1: Toggle ON (+5VDC)
CLRAN2 @ $C05C ;[R/W] Reset AN2: Toggle OFF (0VDC)
SETAN2 @ $C05D ;[R/W] * Set AN2: Toggle ON (+5VDC)
CLRAN3 @ $C05E ;[R/W] Reset AN3: Toggle OFF (0VDC)
SETAN3 @ $C05F ;[R/W] * Set AN3: Toggle ON (+5VDC)
;--------------------------------------------------------------
;[Stars (*) are just for balancing out the look of this chart.]
;--------------------------------------------------------------
}

;--------------------------------------------------------------
; Uncorrected Annunciator Labels [See Tech Info Library Errata]
;--------------------------------------------------------------
; SETAN0 ¯\/¯ $C058 ;[R/W] * Set AN0: Toggle OFF (0VDC): WRONG!
; CLRAN0 _/\_ $C059 ;[R/W] Reset AN0: Toggle ON (+5VDC): WRONG!
;--------------------------------------------------------------
; SETAN1 ¯\/¯ $C05A ;[R/W] * Set AN1: Toggle OFF (0VDC): WRONG!
; CLRAN1 _/\_ $C05B ;[R/W] Reset AN1: Toggle ON (+5VDC): WRONG!
;--------------------------------------------------------------
; SETAN2 ¯\/¯ $C05C ;[R/W] * Set AN2: Toggle OFF (0VDC): WRONG!
; CLRAN2 _/\_ $C05D ;[R/W] Reset AN2: Toggle ON (+5VDC): WRONG!
;--------------------------------------------------------------
; SETAN3 ¯\/¯ $C05E ;[R/W] * Set AN3: Toggle OFF (0VDC): WRONG!
; CLRAN3 _/\_ $C05F ;[R/W] Reset AN3: Toggle ON (+5VDC): WRONG!
;--------------------------------------------------------------
; I wanted these to shout out to everyone that they are: WRONG!
; But, it didn't work. So now they're just notes. The big X's
; mean that the labels should have been swapped originally.
;--------------------------------------------------------------

;==============================================================

Also, I am wondering where you got these mnemonics from:

[I have not changed these in AppleWin's APPLE2E.SYM, yet!--I
might put my names in front of yours with a slash separator
like C08B below. (I did it differently, see P.S. below).]

C080 STEPPER ;I call this one LCRAMIN2 | Same as C084
C08A ENABLE1 ;I call this one LCROMIN1 | Same as C08E
C08B LCBANK1/ENABLE2 ; <-- Where? for ENABLE2 | Same as C08F
C08C DATASTROBE ;I call this one LCRAMIN1 | Same as C088
C08D LOADLATCH ;I call this one ROMIN1 | Same as C089
C08E SETREADMODE ;I call this one LCROMIN1 | Same as C08A
C08E WRITEPROT ;I call this one LCROMIN1 | Same as C08A
C08F SETWRITEMODE ;I call this one LCBANK1 | Same as C08B

Maybe combine: C08E SETREADMODE/WRITEPROT; or vice-versa!

Who decided on these names (above) [other than LCBANK1]?

;--------------------------------------------------------------
; **[Best viewed in a monotyped font like 10pt. Courier New]**
;--------------------------------------------------------------

Why I call these what I do is for LC BANK1/BANK2 parallelism.

See the following excerpt, from (my very own {incomplete & unpublished}):

"Apple IIe Memory Equates for Assembly Programmers" by James Davis

. . .

;=====================================================================
; MMU High-Memory [16K Language Card (LC)] Enabling & Bank-Switching:
;=====================================================================

;----------------------- ; ===========================================
; BANK2-On (MMU LC Bank Select) Switches:
; -------------------------------------------
; ROM/RAM Bank-Switched Area: $D000-$FFFF;
; LC RAM Bank-Switched Area: $D000-$DFFF.
; ===========================================
LCRAMIN2 EQU $C080 ; [R] BANK2-On Sw0: Read RAM; No Write;
; or EQU $C084 ; Use LC Bank 2.
; -------------------------------------------
ROMIN EQU $C081 ; [RR/W] BANK2-On Sw1: Read ROM; Write RAM;
; or EQU $C085 ; Use LC Bank 2. [ROMIN2 would be a more
; appropriate mnemonic for this switch.--JPD]
; -------------------------------------------
LCROMIN2 EQU $C082 ; [R] BANK2-On Sw2: Read ROM; No Write;
; or EQU $C086 ; Use LC Bank 2. [AKA (A.McFadden): ROMINRO]
; -------------------------------------------
LCBANK2 EQU $C083 ; [RR/W] BANK2-On Sw3: Read & Write RAM;
; or EQU $C087 ; Use LC Bank 2.
; ===========================================
; Warning: Do not use these switches without
; careful planning. Careless switching
; between RAM & ROM is almost certain to have
; catastrophic effects.
; -------------------------------------------
; Note: Write access to an odd address in the
; $C08X range controls HRAMRD (see above)
; without affecting the state of HRAMWRT'
; (see below).
; -------------------------------------------
; Note: LC Bank-Switching is independent of
; Main/Auxiliary Memory-Bank Switching.
; -------------------------------------------
; Note: HRAMRD & HRAMWRT' are Jim Sather
; mnemonics; LCRAMIN2, ROMIN2, & LCROMIN2,
; are Jim Davis mnemonics.
;----------------------- ; ===========================================

;----------------------- ; ===========================================
; BANK1-On (MMU LC Bank Select) Switches:
; -------------------------------------------
; ROM/RAM Bank-Switched Area: $D000-$FFFF;
; LC RAM Bank-Switched Area: $D000-$DFFF.
; ===========================================
LCRAMIN1 EQU $C088 ; [R] BANK1-On Sw0: Read RAM; No Write;
; or EQU $C08C ; Use LC Bank 1.
; -------------------------------------------
ROMIN1 EQU $C089 ; [RR/W] BANK1-On Sw1: Read ROM; Write RAM;
; or EQU $C08D ; Use LC Bank 1.
; -------------------------------------------
LCROMIN1 EQU $C08A ; [R] BANK1-On Sw2: Read ROM; No Write;
; or EQU $C08E ; Use LC Bank 1. [AKA (Jim Davis): ROMIN1RO]
; -------------------------------------------
LCBANK1 EQU $C08B ; [RR/W] BANK1-On Sw3: Read & Write RAM;
; or EQU $C08F ; Use LC Bank 1.
; ===========================================
; Warning: Do not use these switches without
; careful planning. Careless switching
; between RAM & ROM is almost certain to have
; catastrophic effects.
; -------------------------------------------
; Note: Write access to an odd address in the
; $C08X range controls HRAMRD (see above)
; without affecting the state of HRAMWRT'
; (see below).
; -------------------------------------------
; Note: LC Bank-Switching is independent of
; Main/Auxiliary Memory-Bank Switching.
; -------------------------------------------
; Note: HRAMRD & HRAMWRT' are Jim Sather
; mnemonics; LCRAMIN1, ROMIN1, & LCROMIN1,
; are Jim Davis mnemonics.
;----------------------- ; ===========================================

. . .

;=====================================================================

I will email a copy of any of my incomplete & unpublished works to
anyone who requests them personally. I will probably never finish
them, anyway!--Because I am getting too old!--And, because I never
finish any of my personal projects, just paid-$-work related ones!
[But, I have been retired now for a very long time.]


Sincerely yours,

James Davis


P.S.

;--------------------------------------------------------------
; **[Best viewed in a monotyped font like 12pt. Courier New]**
;--------------------------------------------------------------

I went ahead and added or changed these (w/o ";<--" comments)
[on my personal copy of the APPLE2E.SYM]:

;C0XX <AppleName> ;<--Traditional mnemonic, *0
;--------------------------------------------------------------
C080 LCRAMIN2 ;<--Jim Davis mnemonic, based on *0
; or STEPPER ;<--AppleWin mnemonic, *1
C081 ROMIN ;<--Traditional mnemonic, *2
; or ROMIN2 ;<--Jim Davis mnemonic, based on *2
C082 ROMINRO ;<--McFadden mnemonic, based on *2
; or LCROMIN2 ;<--Jim Davis mnemonic, based on *2
C083 LCBANK2 ;<--Traditional mnemonic, *3
;--------------------------------------------------------------
; (*X = eXtra or ALTernate Address)
; [Missing hardware address bits makes these same as above.]
C084 LCRAMIN2X ;<--Jim Davis mnemonic, based on *0
; or STEPPER2X ;<--Jim Davis mnemonic, based on *1
C085 ROMINX ;<--Jim Davis mnemonic, based on *2
; or ROMIN2X ;<--Jim Davis mnemonic, based on *2
C086 ROMINROX ;<--Jim Davis mnemonic, based on *2
; or LCROMIN2X ;<--Jim Davis mnemonic, based on *2
C087 LCBANK2X ;<--Jim Davis mnemonic, based on *3
;--------------------------------------------------------------
C088 LCRAMIN1 ;<--Jim Davis mnemonic, based on *0
; or STEPPER1 ;<--Jim Davis mnemonic, based on *1
C089 ROMIN1 ;<--Jim Davis mnemonic, based on *2
C08A ROMIN1RO ;<--Jim Davis mnemonic, based on *2
; or LCROMIN1 ;<--Jim Davis mnemonic, based on *2
; or ENABLE1 ;<--AppleWin mnemonic
C08B LCBANK1 ;<--Traditional mnemonic, *4
; or ENABLE2 ;<--AppleWin mnemonic
;--------------------------------------------------------------
; (*X = eXtra or ALTernate Address)
; [Missing hardware address bits makes these same as above.]
C08C LCRAMIN1X ;<--Jim Davis mnemonic, based on *0
; or DATASTROBE ;<--AppleWin mnemonic
; or STEPPER1X ;<--Jim Davis mnemonic, based on *1
C08D ROMIN1X ;<--Jim Davis mnemonic, based on *2
; or LOADLATCH ;<--AppleWin mnemonic
C08E ROMIN1ROX ;<--Jim Davis mnemonic, based on *2
; or LCROMIN1X ;<--Jim Davis mnemonic, based on *2
; or SETREADMODE ;<--AppleWin mnemonic
; or WRITEPROT ;<--AppleWin mnemonic
C08F LCBANK1X ;<--Jim Davis mnemonic, based on *4
; or SETWRITEMODE ;<--AppleWin mnemonic
;--------------------------------------------------------------

I could add more for the whole $C0XX IOU/MMU soft-switch area, but not now.
Brian Patrie
2019-10-23 06:10:20 UTC
Permalink
Post by James Davis
;--------------------------------------------------------------
; Corrected Annunciator Labels [See Tech Info Library Errata]
;--------------------------------------------------------------
C058 CLRAN0
C059 SETAN0
C05A CLRAN1
C05B SETAN1
C05C CLRAN2
C05D SETAN2
C05E CLRAN3
C05F SETAN3
;--------------------------------------------------------------
Argh; been here before. This is a long-time point of confusion and
argument.

What i gather is that the reason for the seemingly backassward symbols
is that, from a hardware standpoint, the annunciator outputs are
asserted low (gnd). So SETAN0 sets it to 0Vm and CLRAN0 clears it to +5V.

At this stage of the game, it's probably not a good idea to swap the
existing labels, as it would just cause more confusion. More sensible
would be to keep them, and add labels like AN0OFF, AN0ON, etc. (The
addition of something like DGRON, DGROFF might be good for AN0, too.)

--Brian
[donning my asbestos underwear]
James Davis
2019-10-25 01:27:23 UTC
Permalink
Post by Brian Patrie
Post by James Davis
;--------------------------------------------------------------
; Corrected Annunciator Labels [See Tech Info Library Errata]
;--------------------------------------------------------------
C058 CLRAN0
C059 SETAN0
C05A CLRAN1
C05B SETAN1
C05C CLRAN2
C05D SETAN2
C05E CLRAN3
C05F SETAN3
;--------------------------------------------------------------
Argh; been here before. This is a long-time point of confusion and
argument.
What i gather is that the reason for the seemingly backassward symbols
is that, from a hardware standpoint, the annunciator outputs are
asserted low (gnd). So SETAN0 sets it to 0Vm and CLRAN0 clears it to +5V.
At this stage of the game, it's probably not a good idea to swap the
existing labels, as it would just cause more confusion. More sensible
would be to keep them, and add labels like AN0OFF, AN0ON, etc. (The
addition of something like DGRON, DGROFF might be good for AN0, too.)
--Brian
[donning my asbestos underwear]
Okay, I renamed them:

;--------------------------------------------------------------
; Renamed Corrected Annunciator Labels
; [See: Tech Info Library Article No. 1062: Apple II Hardware:
; Errata in Apple II Reference Manual (Part 2 of 2)]
;--------------------------------------------------------------
C058 AN0OFF ;[R/W] CLRAN0: Reset AN0: Toggle OFF (0VDC)
C059 AN0ON ;[R/W] SETAN0: * Set AN0: Toggle ON (+5VDC)
C05A AN1OFF ;[R/W] CLRAN1: Reset AN1: Toggle OFF (0VDC)
C05B AN1ON ;[R/W] SETAN1: * Set AN1: Toggle ON (+5VDC)
C05C AN2OFF ;[R/W] CLRAN2: Reset AN2: Toggle OFF (0VDC)
C05D AN2ON ;[R/W] SETAN2: * Set AN2: Toggle ON (+5VDC)
C05E AN3OFF ;[R/W] CLRAN3: Reset AN3: Toggle OFF (0VDC)
C05F AN3ON ;[R/W] SETAN3: * Set AN3: Toggle ON (+5VDC)
;--------------------------------------------------------------
; Uncorrected Annunciator Labels [See Tech Info Library Errata]
;--------------------------------------------------------------
;C058 SETAN0 ;[R/W] * Set AN0: Toggle OFF (0VDC): WRONG!
;C059 CLRAN0 ;[R/W] Reset AN0: Toggle ON (+5VDC): WRONG!
;C05A SETAN1 ;[R/W] * Set AN1: Toggle OFF (0VDC): WRONG!
;C05B CLRAN1 ;[R/W] Reset AN1: Toggle ON (+5VDC): WRONG!
;C05C SETAN2 ;[R/W] * Set AN2: Toggle OFF (0VDC): WRONG!
;C05D CLRAN2 ;[R/W] Reset AN2: Toggle ON (+5VDC): WRONG!
;C05E SETAN3 ;[R/W] * Set AN3: Toggle OFF (0VDC): WRONG!
;C05F CLRAN3 ;[R/W] Reset AN3: Toggle ON (+5VDC): WRONG!
;--------------------------------------------------------------
TomCh
2019-11-09 12:08:30 UTC
Permalink
Post by James Davis
Post by Brian Patrie
Post by James Davis
;--------------------------------------------------------------
; Corrected Annunciator Labels [See Tech Info Library Errata]
;--------------------------------------------------------------
C058 CLRAN0
C059 SETAN0
C05A CLRAN1
C05B SETAN1
C05C CLRAN2
C05D SETAN2
C05E CLRAN3
C05F SETAN3
;--------------------------------------------------------------
Argh; been here before. This is a long-time point of confusion and
argument.
What i gather is that the reason for the seemingly backassward symbols
is that, from a hardware standpoint, the annunciator outputs are
asserted low (gnd). So SETAN0 sets it to 0Vm and CLRAN0 clears it to +5V.
At this stage of the game, it's probably not a good idea to swap the
existing labels, as it would just cause more confusion. More sensible
would be to keep them, and add labels like AN0OFF, AN0ON, etc. (The
addition of something like DGRON, DGROFF might be good for AN0, too.)
--Brian
[donning my asbestos underwear]
;--------------------------------------------------------------
; Renamed Corrected Annunciator Labels
; Errata in Apple II Reference Manual (Part 2 of 2)]
;--------------------------------------------------------------
C058 AN0OFF ;[R/W] CLRAN0: Reset AN0: Toggle OFF (0VDC)
C059 AN0ON ;[R/W] SETAN0: * Set AN0: Toggle ON (+5VDC)
C05A AN1OFF ;[R/W] CLRAN1: Reset AN1: Toggle OFF (0VDC)
C05B AN1ON ;[R/W] SETAN1: * Set AN1: Toggle ON (+5VDC)
C05C AN2OFF ;[R/W] CLRAN2: Reset AN2: Toggle OFF (0VDC)
C05D AN2ON ;[R/W] SETAN2: * Set AN2: Toggle ON (+5VDC)
C05E AN3OFF ;[R/W] CLRAN3: Reset AN3: Toggle OFF (0VDC)
C05F AN3ON ;[R/W] SETAN3: * Set AN3: Toggle ON (+5VDC)
;--------------------------------------------------------------
; Uncorrected Annunciator Labels [See Tech Info Library Errata]
;--------------------------------------------------------------
;C058 SETAN0 ;[R/W] * Set AN0: Toggle OFF (0VDC): WRONG!
;C059 CLRAN0 ;[R/W] Reset AN0: Toggle ON (+5VDC): WRONG!
;C05A SETAN1 ;[R/W] * Set AN1: Toggle OFF (0VDC): WRONG!
;C05B CLRAN1 ;[R/W] Reset AN1: Toggle ON (+5VDC): WRONG!
;C05C SETAN2 ;[R/W] * Set AN2: Toggle OFF (0VDC): WRONG!
;C05D CLRAN2 ;[R/W] Reset AN2: Toggle ON (+5VDC): WRONG!
;C05E SETAN3 ;[R/W] * Set AN3: Toggle OFF (0VDC): WRONG!
;C05F CLRAN3 ;[R/W] Reset AN3: Toggle ON (+5VDC): WRONG!
;--------------------------------------------------------------
Thanks for the missing symbols and suggestions.

FYI, there was a long discussion about AppleWin symbols a few years ago, here:
https://github.com/AppleWin/AppleWin/issues/425

I've created a new branch and will add the missing symbols and (try!) to improve the names for LC and DiskII (slot-6) DEVICE I/O symbols.

Tom
fadden
2019-11-09 16:04:01 UTC
Permalink
Post by TomCh
I've created a new branch and will add the missing symbols and (try!) to improve the names for LC and DiskII (slot-6) DEVICE I/O symbols.
I still haven't figured out a good way to deal with the $c080-c0ff range. Even if you assume everybody has their disk controller in slot 6 and SSC in slot 1, you're often still dealing with code that does indexed loads on the slot 0 range (LDA $c08c,X) rather than the final address ($c0ec).

With an emulator-based debugger there's a possibility of coordinating the slot configuration and current contents of the X register to arrive at an unambiguous mapping. With a static analyzer it's a lot harder.

On the other hand, overlapping zero-page definitions are easier to handle when you're focused on a single program.
TomCh
2019-11-21 22:17:16 UTC
Permalink
Post by fadden
Post by TomCh
I've created a new branch and will add the missing symbols and (try!) to improve the names for LC and DiskII (slot-6) DEVICE I/O symbols.
I still haven't figured out a good way to deal with the $c080-c0ff range. Even if you assume everybody has their disk controller in slot 6 and SSC in slot 1, you're often still dealing with code that does indexed loads on the slot 0 range (LDA $c08c,X) rather than the final address ($c0ec).
With an emulator-based debugger there's a possibility of coordinating the slot configuration and current contents of the X register to arrive at an unambiguous mapping. With a static analyzer it's a lot harder.
On the other hand, overlapping zero-page definitions are easier to handle when you're focused on a single program.
For the emulator case, for LDA $C08C,X, when it knows that X=#$60, what do you show?

If DATASTROBE=$C0EC then showing "LDA DATASTROBE,X" isn't correct.
Perhaps "LDA $C08C,X ; DATASTROBE" is better?

Tom

James Davis
2019-11-09 21:59:58 UTC
Permalink
Post by TomCh
Thanks for the missing symbols and suggestions.
https://github.com/AppleWin/AppleWin/issues/425
I've created a new branch and will add the missing symbols and (try!) to improve the names for LC and DiskII (slot-6) DEVICE I/O symbols.
Tom
Hi Tom,

Thanks for the link.

I am working on all the symbols in the Apple II Plus ROM image. When it is complete, I will send you and Andy McFadden a copy of the SourceGen files.

I am creating a verbose analysis of the whole ROM image (using all kinds of source materials).

James Davis
Loading...