mjohnson@APPLE.COM (Mark B. Johnson) (12/02/89)
This message was originally submitted by mjohnson@APPLE.COM to the APPLE2-L
list at BROWNVM. If you simply forward it back to the list, it will be
distributed with the paragraph you are now reading being automatically removed.
If you edit the contributions you receive into a digest, you will need to
remove this paragraph before mailing the result to the list. Finally, if you
need more information from the author of this message, you should be able to do
so by simply replying to this note.
----------------- Message requiring your approval (352 lines) -----------------
Apple II
Technical Notes
_____________________________________________________________________________
Developer Technical Support
Apple IIGS
#25: Apple IIGS Firmware Reference Updates
Revised by: Jim Luther November 1989
Written by: Rilla Reynolds October 1987
This Technical Note includes updates to the May 1987 edition of the Apple IIGS
Firmware Reference, published by Addison-Wesley (Part Number 030-3121-A). The
new Monitor commands require an Apple IIGS revised ROM (Part Number 342-0077-
B), which is available without charge from an authorized Apple dealer. Please
contact Apple II Developer Technical Support at the address listed in Apple II
Technical Note #0 if you have additional corrections or suggestions for this
manual.
Changes since May 1989: Added correction to Chapter 5, pages 97 and 105,
on the Serial-Port Firmware, Chapter 7, page 124 and 141, on the SmartPort
Firmware, and Chapter 8, page 184, on the Interrupt-Handler Firmware.
_____________________________________________________________________________
Contents
Page vii, Chapter 7 SmartPort Firmware: Change "Generic SmartPort
callsJJJ121" to "Standard and Extended SmartPort callsJJJ121."
Chapter 3: System Monitor Firmware
Page 24, Table 3-1 (continued), Monitor commands grouped by
type: Add a miscellaneous-type and a debugging-type Monitor command to
the table, as follows:
Command type Command format
...
Quit Monitor Q
Install Visit Monitor and MemoryPeeker desk accessories #
...
Enter mini-assembler !
Set flags (e, m, x) for full-native mode Control-N
Page 43, Back to BASIC: The last paragraph should read: "If you are
using DOS 3.3 or ProDOS(R), use the Monitor Q (Quit) command to return to
the language you were using with your program and variables intact."
Page 48, Table 3-6, Commands for program execution and
debugging: Add a Monitor command to the table:
Command type Command format
...
Enter mini-assembler !
Set flags (e, m, x) for full-native mode Control-N
Page 66, after final paragraph: Add a new Monitor instruction heading
and description:
Native Mode Set Control-N (Native Mode)
Control-N sets the m, x, e flags to 0 for full-native mode. All
other registers are unchanged.
Page 67, after final paragraph: Add a new Monitor instruction heading
and description:
Turn on ROM Desk Accessories, #
Enables the currently available ROM desk accessories, Visit Monitor
and Memory Peeker. These desk accessories remain active in the desk
accessory menu until power is shut off. Control-Open Apple-Reset has
no affect on these items. To exit the Visit Monitor desk accessory,
press Control-Y then press Return. To exit the Memory Peeker desk
accessory, press Q.
Chapter 5: Serial-Port Firmware
Page 82, Compatibility: The second half of the third sentence in the
first paragraph should read: "...the Apple IIGS hardware is different from
that used on the SSC."
Page 91, Input buffering, BE and BD: This heading should be
"Input/Output buffering, BE and BD."
Page 94, Table 5-6: The Extended Interface footnote which states, "If the
function call returns with the carry bit set..." is incorrect. For Apple
IIGS ROM 01, the Extended Serial Interface does not return the error
condition in the carry bit. Programs using the Extended Serial Interface
should check for a non-zero result value in the result code rather than the
carry bit to determine if an error has occurred. For additional error
handling information using the Extended Interface, see Apple IIGS Technical
Note #50, Extended Serial Interface Error Handling.
Page 95, Error handling: The second sentence should read: "If the
character has a framing or parity error (assuming that the parity option is
not set to None), the character is deleted from the input stream and the
appropriate mode bit is set."
Page 96, Note: The Note should read: "The InQStatus elapsed-time
counter functions correctly only if a heartbeat interrupt task has been
started. A heartbeat interrupt task is a set of functions called by
interrupt code that run automatically at one-thirtieth of a second
intervals.
Page 96, Interrupt notification: The fourth sentence in the first
paragraph should be: "The system interrupt handler will transfer control
to the user's interrupt vector at $03FE in bank $00."
Page 97, Interrupt notification: The last three paragraphs should be
replaced with this paragraph: "The interrupt completion routine executes
as part of the firmware interrupt handler and must be run in that
environment. The interrupt completion routine must preserve the DBR,
speed, 8-bit native mode, D register, stack pointer (or just use the
current stack), and MSLOT for proper operation. A/X/Y need not be
preserved."
Page 100, SetModeBits: The first sentence in the paragraph following
the CMDLIST should read: "Use this call to alter any of the mode bits
whose function is described below."
Page 105, GetIntInfo: The command list should read:
CMDLIST DFB $03 ;Parameter count
DFB $0C ;Command code
DW $00 ;result code (output)
DW $00 ;interrupt setting (output)
DL Completion address ;(output)
The following should be added after the command list, "Note: The
Parameter count of $03 is correct even though there are four parameters."
The following should be added after the last paragraph: "Note: Before
making this call from an interrupt completion routine, you must set the
operating environment to look and act exactly like a 6502 in all respects.
During interrupt completion routines, you must preserve the DBR, speed, 8-
bit native mode, D register, stack pointer (or just use the current stack),
and MSLOT for proper operation. A/X/Y need not be preserved. See
"Environments for the Firmware Routines" in chapter 2, Notes for
Programmers for details about setting and restoring the operating
environment.
Page 106, SetIntInfo: The command list should read:
CMDLIST DFB $03 ;Parameter count
DFB $0D ;Command code
DW $00 ;result code (output)
DW Interrupt setting ;(input)
DL Completion address ;(input)
The following should be added after the command list, "Note: The
Parameter count of $03 is correct even though there are four parameters."
Chapter 7: SmartPort Firmware
Page 120, Issuing a call to SmartPort: The standard and extended
SmartPort call examples should be:
This is an example of a standard SmartPort call:
SP_CALL JSR DISPATCH ;Call SmartPort command dispatcher
DC i1'CMDNUM' ;This specifies the command type
DC i2'CMDLIST' ;Word ptr to param list in bank $00
BCS ERROR ;Carry is set on an error
This is an example of an extended SmartPort call:
SP_EXT_CALL JSR DISPATCH ;Call SmartPort command dispatcher
DC i1'CMDNUM+$40' ;This specifies the ext cmd type
DC i4'CMDLIST' ;Pointer to the parameter list
BCS ERROR ;Carry is set on an error
Page 121, Generic SmartPort calls: Change occurrences of "Generic
SmartPort Calls" to "Standard and Extended SmartPort Calls" in the header
and the first sentence. Refer to SmartPort Technical Note #2, SmartPort
Calls Updated, for updated information on the SmartPort STATUS call.
Page 122, Statcode = $00: Change the function of bit 0 of the first
device status byte to: "1 = Device currently open (character devices only)
or disk switched (block device only)."
Page 124: SmartPort device types should be same as those documented in
Apple II SmartPort Technical Note #4, SmartPort Device Types.
Page 125, SmartPort driver status: This section should read: "A
status call with a unit number of $00 and a status code of $00 is a request
to return the status of the SmartPort driver. This function returns the
number of devices as well as the current interrupt status. Devices should
return $00 in the reserved bytes and exit with a transfer count of $0008.
The format of the status list returned is as follows:
STATLIST Byte 0 Number of devices
Byte 1 Reserved
Byte 2 $00 Vendor Unknown
$01 Apple
$02...$FF Vendor Unique
Byte 3 Reserved
Byte 4 Reserved
Byte 5 Reserved
Byte 6 Reserved
Byte 7 Reserved
The number of devices field is a one-byte field indicating the total number
of devices connected to the slot or port. This number will always be in
the range 0 to 127.
Vendors must request a Vendor ID Assignment from Apple II Developer
Technical Support before using a specific value in byte two.
Page 125, Possible errors: Add the following:
$1F No interrupt. Interrupts not supported.
$2B No write. Disk write-protected.
$2F Offline. Disk off-line or no disk in drive.
Page 126, ReadBlock: Add a sentence at the end of the first paragraph
which reads, "On return, the X and Y registers indicate the number of bytes
transferred."
Page 131, Open: The following changes apply for the CMDNUM:
Standard call Extended call
CMDNUM $06 $46
Page 132, Read: Add a sentence at the end of the first paragraph which
reads, "On return, the X and Y registers indicate the number of bytes
transferred."
Page 140, Figure 7-8, Disk-sector format: Change to the following:
_____________________________________________________________________
|13 |F|D|A|9|T|S|S|F|A|D|A|F|1 |F|D|A|A|S|699 |4|D|A|F|
|5-Nibble|F|5|A|6|r|e|i|o|d|E|A|F|5-Nibble|F|5|A|D|e|GCR | |E|A|F|
|SelfSync| | | | |a|c|d|r|r| | | |SelfSync| | | | |c|Nibbles |C| | | |
|Fields | | | | |c|t|e|m|s| | | |Fields | | | | |t|Fields |h| | | |
| | | | | |k|o| |a|L| | | | | | | | |o| |e| | | |
| | | | | | |r| |t|R| | | | | | | | |r| |c| | | |
| | | | | | | | | |C| | | | | | | | | | |k| | | |
| | | | | | | | | | | | | | | | | | | | |s| | | |
| | | | | | | | | | | | | | | | | | | | |u| | | |
| | | | | | | | | | | | | | | | | | | | |m| | | |
_____________________________________________________________________
A SelfSync Field is four 20 microsecond selfsync nibbles written as
a sequence of five 16 microsecond nibbles.
Page 140, ResetHook: The Control code and Control list should be:
Control Code Control list
$06 Count low byte $04
Count high byte $00
Hook reference number $xx, $00, $00, $00
Page 141, SetInterleave: The Control code and Control list should be:
Control Code Control list
$0A Count low byte $01
Count high byte $00
Interleave $01 to $0C
Page 143, UniDiskStat: The Status code and Status list should be:
Status Code Status list
$05 Byte $04
Soft error $00
Retries $xx
A register after execute $xx
Y register after execute $xx
P register after execute $xx
Byte $xx
Page 152, Passing parameters to a ROM disk: Add a sentence to the
end of the second paragraph which reads: "These locations will not be
preserved between SmartPort calls."
Page 156, Table 7-6, SmartPort error codes: Add the following error
code:
Acc value Error type Description
$69 IOTERM I/O terminated due to new line
Page 166, Table 7-8, Standard command packet contents":
Byte 3 descriptions should read "Byte 2 of param list."
Byte 4 descriptions should read "Byte 3 of param list."
Byte 5 descriptions should read "Byte 4 of param list."
Byte 6 descriptions should read "Byte 5 of param list."
Byte 7 descriptions should read "Byte 6 of param list."
Byte 8 descriptions should read "Byte 7 of param list."
Byte 9 descriptions should read "Byte 8 of param list."
Chapter 8: Interrupt-Handler Firmware
Page 184, Serial-port interrupt notification: The last three
paragraphs should be replaced with this paragraph: "The interrupt
completion routine executes as part of the firmware interrupt handler and
must be run in that environment. The interrupt completion routine must
preserve the DBR, speed, 8-bit native mode, D register, stack pointer (or
just use the current stack), and MSLOT for proper operation. A/X/Y need not
be preserved."
Chapter 9: Apple DeskTop Bus Microcontroller
Page 191, Sync, $07: The first sentence should read: "This command
performs the three preceding commands in sequence."
Page 194, Receive Bytes, $48: The fourth sentence should read: "The
second byte value is a combination of the device address in the high nibble
and the ADB command in the low nibble (see the Apple IIGS Hardware
Reference)."
Chapter 10: Mouse Firmware
Page 201: Mouse button positions should be changed as follows:
o X data byte
If bit 7 = 0, then mouse button 1 is down.
If bit 7 = 1, then mouse button 1 is up.
o Y data byte
If bit 7 = 0, then mouse button 0 is down.
If bit 7 = 1, then mouse button 0 is up.
Page 205, Figure 10-1, Position and status information:
Bit 7 description should be: "Currently, button 0 is up/down (0/1)."
Bit 6 description should be: "Previously, button 0 was up/down (0/1)."
Appendix B: Firmware ID Bytes
Page 223, Table B-2, Register bit information: Change the table to
show that Bits 7-0 of the Y register hold the ROM version number, and the X
register is reserved. In addition, the table description should read:
"The Y register contains the machine ID and the ROM version number. The X
register is reserved."
Page 249, COUT1: In the third sentence, change the value of line feed
from $8C to $8A.
Page 277, RDALTZP: Change the comment to read: "Bit 7 = 1 if alt zp
enabled."
Further Reference:
_____________________________________________________________________________
o Apple IIGS Firmware Reference
o Apple IIGS Technical Note #50, Extended Serial Interface Handling