Path: news1.icaen!news.uiowa.edu!news.physics.uiowa.edu!math.ohio-state.edu!uwm.edu!chicago-news-feed1.bbnplanet.com!su-news-hub1.bbnplanet.com!cpk-news-hub1.bbnplanet.com!news.bbnplanet.com!news1.bellglobal.com!torn!nott!cunews!freenet-news.carleton.ca!p45t3.std.dialup.ncf.carleton.ca!user From: be946@freenet.carleton.ca (Simon C.Hall) Newsgroups: comp.sys.apple2.programmer Subject: RE: APPLE2 GS FiRmWaRe Date: Fri, 14 Aug 1998 12:27:41 -0500 Organization: Apple IIGS User's Group Lines: 342 Sender: be946@freenet.carleton.ca (Simon C.Hall) Message-ID: NNTP-Posting-Host: p45t3.std.dialup.ncf.carleton.ca X-Given-From: be946@freenet.carleton.ca (Jim AKA Simon) Xref: news1.icaen comp.sys.apple2.programmer:10152 Getting Into the Toolbox Unlike using a built-in subroutine, where a JSR will suffice to get the routine working, a toolbox call requires establishment of several toolbox routines before using a call. The following sequence will initiate most tool calls: 1. Start Tool Locator 2. Start Miscellaneous Tools 3. Get ID from Miscellaneous Tools 4. Start up Memory Manager To make a toolbox call, it is necessary to examine the parameters of the call you wish to make. You need to examine: 1. The tool number 2. The stack before the call 3. The stack after the call First. It is necessary to reserve room on the stack for workspace for the information that will be returned after the call and/or information required by the call. Examine the stack diagram before the call, and for each word of workspace, use PEA $0000 to reserve room on the stack. If the stack requires other information before the call, use PEA to push whatever is required onto the stack. For example, the following diagram shows what the ReadMouse call requires: Figure 13-2 Stack before call workspace <---- 16 bit word workspace <---- 16 bit word workspace <---- 16 bit word <---- Stack pointer It expects three words (or double bytes) on the stack before the call. On your assembler, you would type in: PEA $0000 PEA $0000 PEA $0000 There is now enough room on the stack for the information the call will return. Sometimes there is nothing required to be pushed onto the stack before a call. If that is the case, don't put anything there. Second. Once there is room on the stack, use LDX in the immediate mode to load the toolbox call into the X register. For example, the ReadMouse call is a Miscellaneous Tool Set call with the number $1703. The instruction on your assembler would be: LDX #$1703 Once that is accomplished, use a long jump (JSL) to $ElOOOO. JSL $E1000 Third. If there is something on the stack, according to the stack diagram, then you will want to pull it off the stack and store the information somewhere or use it for something else. For every PEA used, youll need a 16-bit pull. Sometimes that means youll be pulling two values off at the same time, usually a linked 16-bit value. For example, after the ReadMouse call, your stack diagram will look like this: Figure 13-3 High Byte X pos- \ =Word / Low Byte X pos- High Byte Y pos- \ =Word / Low Byte Y pos- MouseStatus- \ =Word / MouseMode- In this case, the MouseMode is at the top of the stack, and the high byte of the X position (horizontal) is at the bottom. Therefore, the first thing that will come off the stack with a 16-bit PLA is the MouseMode and MouseStatus. Sometimes, you really don't care about all the information that is on the stack. For example, you may only want the X and Y positions of the mouse and are not interested in the MouseMode and MouseStatus values. However, everything on the stack must be pulled off, or problems will arise. For example, to clear the stack in the ReadMouse call, it is necessary to have three PLA's or other pull instructions. You also want to store the data somewhere, so your program looks something like the following after the call: PLA STA $300 PLA STA #302 PLA STA #304 Mouse status and mode are found in addresses $300 to $301, while $302 to $303 contain the Y (vertical) position of the mouse, and $303-$304 has the X position. If you do not want to store the mouse status and mode, you can just use a PLA without using a STA to put the information somewhere. If there is nothing on the stack after a call, even if you pushed a value onto the stack at the beginning of the call, you do not have to pull it off. For example, the InitMouse call requires a value to be pushed on the stack, but it does not leave anything on the stack after the call. Using the Toolbox and the Rest of Your Computer The toolbox has many uses, but you don't want to have to give up using the rest of the built-in subroutines and other goodies on your Apple IIGs. It is very simple to use many different tools once you're inside the toolbox. However, there are times when you want to go outside the toolbox, back into the 8-bit mode to use your built-in subroutines, and then return to the toolbox. In this case, you use the routines for changing modes, primarily XCE and its attending op- codes. Basically, follow these steps: 1. Set up toolbox 2. Use toolbox routine 3. Return to 8-bit mode 4. Use built-in subroutines 5. Back to 16 bits for more toolbox material 6. Loop back until end condition met 7. Must be in 16-bit mode to turn off toolbox sets 8. When all finished, turn to 8 bits and quit Getting Out of the Toolbox The final step is shutting down the various toolbox sets. This must be planned carefully, for you do not want to do things out of order. The following is an example of one shutdown sequence: 1. Turn off Setmouse 2. Drop the ID used 3. Shut down miscellaneous tools 4. Shut down memory manager 5. Shut down tool locator An Example: Reading and Using the Mouse A simple application would be to make a "mouse arrow" from one of the ASCII characters. The character that looks like an arrow in your alternate character set is $42 (66). Well read the value of the mouse, and use those values in placing the arrow character on the screen. Well also use some placement routines from the 8-bit mode. The VTAB routine at $FC22 reads its vertical position from zero page address $25, so well put the Y position of the mouse in $25 and do a JSR to $FC22 to arrive at the correct vertical placement of the arrow. The X or horizontal position will be made by putting X number of blank spaces between the left side of the screen and the arrow character. The PRBL2 routine that does this is at $F94A. Since it uses the value of the X register, we can place the X position of the mouse in the X register, and the Y position first in the A register and then in $25. That should give us a moving arrow. Here's the program: Merlin 1 ****************************** 2 * 3 * Mouse Pointer 4 * 5 ****************************** 5 7 JSR $FC58 8 XC 9 XC 10 ****************************** 11 CLC 12 XCE 13 REP $30 14 BOX EQU $El0OOO l5 ID EQU $300 16 BUFFER EQU $304 17 LYPOS EQU BUFFER 18 LXPOS EQU BUFFER+2 19 ARROW EQU $OA ;Homemade cursor 20 LDA #$42 ;arrow 21 STA ARROW 22 STZ $COOF ;Alt chr set on 23 ****************************** 24 LDX #$0201 ;StartupTool 25 JSL BOX ;Locator 26 ****************************** 27 LDX #$0203 ;Misc Tools 28 JSL BOX ;startup 29 ****************************** 30 PEA $0000 ;Get id from 31 PEA $1000 ;misc. tools 32 Lnx #$2003 33 JSL BOX 34 PLA 35 STA ID 35 ****************************** 37 PEA $0000 ;MMstartup 38 LDX #$0202 39 JSL BOX 40 PLA 41 ****************************** 42 PEA $0 43 LDX #$1803 ;InitMouse 44 JSL BOX 45 ****************************** 46 PEA $01 ;transparent 47 LDX #$1903 ;Setmouse 48 JSL BOX 49 ****************************** 5D * 51 * Read Mouse Data 52 * and Store it 53 * 54 ****************************** 55 Pos PEA $0 ;X pos 56 PEA $0 ;Y pos 57 PEA $0 ;Mouse status 58 LDX #$1703 ;ReadMouse 59 JSL BOX 60 PLA 61 PLA 62 STA BUFFER 63 PLA 64 STA BUFFER+2 55 ****************************** 66 SEC ;Back to 8 bits 67 XCE 68 ****************************** 59 * 70 * Connect Arrow to Mouse 71 * Position 72 * 73 ****************************** 74 LDX LXPOS ;PointerRoutine 75 CMP #$27 76 BEQ END 77 LDA BUFFER 78 STA $25 79 JSR $FC22 80 CMP #$18 81 BEQ END 82 JSR $F94A 83 LDA ARROW ;Arrow character into A 84 JSR $FDED ;put it on the screen 85 LDY #$07 86 PAUSE LDX #$FF ;Slow down to see the 87 HOLDIT DEX ;arrow on the screen 88 CPX #$00 s9 BNE HOLDIT 90 DEY 91 CPY #$0 92 BNE PAUSE 93 JSR $FC58 94 ****************************** 95 CLC ;Deloop 95 XCE ;to de 97 REP $30 ;mouse 98 JMP POS ; in 15 bits 99 ***************************** 100 * 101 * Shutdown 102 * 103 ***************************** 104 END CLC 105 XCE 106 REP 107 ***************************** 108 PEA $00 ;turn off 109 LDX #$19D3 ;Setmouse 110 JSL BOX 111 ***************************** 112 PEA $0000 ;Drop ID 113 LDX #$2103 114 JSL BOX 115 ***************************** 115 LDX #$0303 ;auit Misc Tools 117 JSL BOX 118 ***************************** 119 LDX #$0302 ;Quit MM 12D JSL BOX 121 ***************************** 122 LDX #$0301 ;Quit TL 123 JSL BOX 124 ***************************** 125 SEC 126 XCE 127 RTS TAKEN FROM: Library of Congress Cataloging-in-Publication Data Sanders, William B., 1944- Elementary assembly language for the Apple IlGS and the 65816 / William B. Sanders. P. cm. Includes index. ISBN 0-673-18814-0 : $19.95 1. Assembler language (Computer program language) 2. Apple IIGS (Computer)-Programming. 3. 65816 (Microprocessor)-Programming. 1. Title. QA76.73.A8S25 1988 OO5.265-dc19 87-16756 CIP 1 2 3 4 5 6 MAL 92 91 90 89 88 87 ISBN 0-673-18814-0 Copyright 1988 William B. Sanders. All Rights Reserved. Printed in the United States of America. Path: news1.icaen!news.uiowa.edu!news.physics.uiowa.edu!math.ohio-state.edu!howland.erols.net!news-peer.gip.net!news.gsl.net!gip.net!sunqbc.risq.qc.ca!torn!nott!cunews!freenet-news.carleton.ca!p5t3.std.dialup.ncf.carleton.ca!user From: be946@freenet.carleton.ca (Simon C.Hall) Newsgroups: comp.sys.apple2.programmer Subject: RE: Apple IIGS FirmWare Date: Fri, 14 Aug 1998 12:37:46 -0500 Organization: Apple IIGS User's Group Lines: 6 Sender: be946@freenet.carleton.ca (Simon C.Hall) Message-ID: NNTP-Posting-Host: p5t3.std.dialup.ncf.carleton.ca X-Given-From: be946@freenet.carleton.ca (Jim AKA Simon) Xref: news1.icaen comp.sys.apple2.programmer:10151 Erata; line 32 Lnx #$2003 Should read 32 LDX #$2003 Go Figure ! Sorry (; Newsgroups: comp.sys.apple2.programmer Subject: Re: APPLE2 GS FiRmWaRe From: dempson@actrix.gen.nz (David Empson) Date: Sun, 16 Aug 1998 16:59:11 +1200 Message-ID: <1ddv11t.67qain1rof4m6N@dempson.actrix.gen.nz> References: Organization: Empsoft X-Newsreader: MacSOUP 2.3 NNTP-Posting-Host: 202.49.157.176 X-Trace: 16 Aug 1998 16:58:20 -1200, 202.49.157.176 Lines: 415 Path: news1.icaen!news.uiowa.edu!NewsNG.Chicago.Qual.Net!nyd.news.ans.net!newsfeeds.ans.net!news.idt.net!newsfeed.internetmci.com!203.97.37.7!newsfeed.clear.net.nz!news.iprolink.co.nz!news.actrix.gen.nz!dempson Xref: news1.icaen comp.sys.apple2.programmer:10154 Simon C.Hall wrote: > Getting Into the Toolbox > > Unlike using a built-in subroutine, where a JSR will suffice to get > the routine working, a toolbox call requires establishment of several > toolbox routines before using a call. The following sequence will > initiate most tool calls: > > 1. Start Tool Locator > 2. Start Miscellaneous Tools > 3. Get ID from Miscellaneous Tools > 4. Start up Memory Manager Good grief. I'm getting forboding feelings about this article. I am assuming this is documenting how to use a limited subset of the toolbox from a ProDOS-8 application. The terminology used here is confusing at the least, wrong at the worst. The above paragraph should say "... to get the routine working, using toolbox calls requires starting up several toolsets before using a call." ("Toolsets", not "toolbox routines", and this isn't required for every single call to the toolbox, only once for the entire program.) Secondly, the code sequence described is wrong. In a ProDOS-8 program which uses the toolbox, you need to make the following call sequence: Enable 16-bit native mode. If possible, set up a new stack somewhere other than $0100-$01FF. Start the Tool Locator. Start the Memory Manager. If the Memory Manager returns error $0207 then Start the Miscellaneous Toolset. Get a new ID from the Miscellaneous Toolset. Call the Memory Manager to allocate all memory from $000800 to $00BFFF to your new ID. Possibly repeat for $010800 to $01BFFF. Start the Memory Manager. Remember that you did all this so you can clean up again when your program terminates. Else (no error on original Memory Manager startup) Save the user ID returned by the Memory Manager. Start the Miscellaneous Toolset. End If When your program completes: If you allocated a new ID and memory on startup then Release the memory allocated. Shut down the Memory Manager. Release the ID. Shut down the Miscelleous Toolset. Else Shut down the Miscellaneous Toolset. Shut down the Memory Manager. End If Shut down the Tool Locator. Restore the original stack pointer if you set up a new stack. Disable native mode, returning to emulation mode. If you are always running the program after launching ProDOS-8 under GS/OS, then you will never get an error from the MMStartUp call, which simplifies it a lot. The extra stuff is only needed when booting ProDOS-8 directly. > To make a toolbox call, it is necessary to examine the parameters > of the call you wish to make. You need to examine: > > 1. The tool number > 2. The stack before the call > 3. The stack after the call > > First. > > It is necessary to reserve room on the stack for workspace > for the information that will be returned after the call and/or > information required by the call. Examine the stack diagram before > the call, and for each word of workspace, use PEA $0000 to reserve > room on the stack. It isn't necessary to use PEA for the majority of toolbox calls - it will just waste two bytes of code space. Use PHA instead. (If you want the return value to be zero in the case of an error, then use PEA.) > If the stack requires other information before the call, use PEA to push > whatever is required onto the stack. Or calculate the required value and use PHA, etc. PEA is only useful if you are pushing a predetermined constant value. [snip] > Once that is accomplished, use a long jump (JSL) to $ElOOOO. > > JSL $E1000 That should be JSL $E10000, of course, and it is not a long jump but a long jump-to-subroutine. [snip] > You also want to store the data somewhere, so your program looks > something like the following after the call: > > PLA > STA $300 > PLA > STA #302 > PLA > STA #304 Those should be $302, $304. > Mouse status and mode are found in addresses $300 to $301, > while $302 to $303 contain the Y (vertical) position of the mouse, > and $303-$304 has the X position. $304 to $305 has the X position. > Using the Toolbox and the Rest of Your Computer > > The toolbox has many uses, but you don't want to have to give up > using the rest of the built-in subroutines and other goodies on your > Apple IIGs. It is very simple to use many different tools once you're > inside the toolbox. However, there are times when you want to go > outside the toolbox, back into the 8-bit mode to use your built-in > subroutines, and then return to the toolbox. In this case, you use the > routines for changing modes, primarily XCE and its attending op- > codes. Basically, follow these steps: > > 1. Set up toolbox > 2. Use toolbox routine > 3. Return to 8-bit mode > 4. Use built-in subroutines > 5. Back to 16 bits for more toolbox material > 6. Loop back until end condition met > 7. Must be in 16-bit mode to turn off toolbox sets > 8. When all finished, turn to 8 bits and quit No problem there, except that all references to "8-bit mode" should say "emulation mode" (there is also an 8-bit native mode). Note that you follow my suggestion of using a separate stack while in native mode, you need to save and restore the appropriate stack pointers on each mode change. > Getting Out of the Toolbox > > The final step is shutting down the various toolbox sets. This must > be planned carefully, for you do not want to do things out of order. > The following is an example of one shutdown sequence: > > 1. Turn off Setmouse > 2. Drop the ID used > 3. Shut down miscellaneous tools > 4. Shut down memory manager > 5. Shut down tool locator This should be modified according to my example earlier. > An Example: Reading and Using the Mouse > > A simple application would be to make a "mouse arrow" from one of the > ASCII characters. The character that looks like an arrow in your alternate > character set is $42 (66). Well read the value of the mouse, and use those > values in placing the arrow character on the screen. > Well also use some placement routines from the 8-bit mode. > The VTAB routine at $FC22 reads its vertical position from zero page > address $25, > so well put the Y position of the mouse in $25 and do a JSR to $FC22 to > arrive at > the correct vertical placement of the arrow. The X or horizontal position > will be > made by putting X number of blank spaces between the left side of > the screen and the arrow character. The PRBL2 routine that does > this is at $F94A. Since it uses the value of the X register, we can > place the X position of the mouse in the X register, and the Y position > first in the A register and then in $25. That should give us a moving > arrow. > > Here's the program: > There are many instances of 'O' (the letter) in place of '0' (the digit) and 'l' (the letter) instead of '1' (the digit) in this. It will not assemble without correcting these. Was this OCRed? > Merlin > > 1 ****************************** > 2 * > 3 * Mouse Pointer > 4 * > 5 ****************************** > 5 > 7 JSR $FC58 > 8 XC > 9 XC > 10 ****************************** > 11 CLC > 12 XCE > 13 REP $30 > 14 BOX EQU $El0OOO > l5 ID EQU $300 > 16 BUFFER EQU $304 > 17 LYPOS EQU BUFFER > 18 LXPOS EQU BUFFER+2 > 19 ARROW EQU $OA ;Homemade cursor > 20 LDA #$42 ;arrow > 21 STA ARROW Note that this is overwriting location $0B with a value of $00. > 22 STZ $COOF ;Alt chr set on This instruction is also writing to $C010, so it will clobber any key pending in the keyboard buffer. This step should have been done before the CLC/XCE earlier. There should also be code on exit to restore the primary character set. > 23 ****************************** > 24 LDX #$0201 ;StartupTool > 25 JSL BOX ;Locator > 26 ****************************** > 27 LDX #$0203 ;Misc Tools > 28 JSL BOX ;startup > 29 ****************************** > 30 PEA $0000 ;Get id from > 31 PEA $1000 ;misc. tools > 32 Lnx #$2003 Should be LDX. > 33 JSL BOX > 34 PLA > 35 STA ID > 35 ****************************** > 37 PEA $0000 ;MMstartup > 38 LDX #$0202 > 39 JSL BOX > 40 PLA See earlier for my comments on the toolbox startup sequence. Getting the ID in this manner is completely pointless. > 41 ****************************** > 42 PEA $0 > 43 LDX #$1803 ;InitMouse > 44 JSL BOX > 45 ****************************** > 46 PEA $01 ;transparent > 47 LDX #$1903 ;Setmouse > 48 JSL BOX I'm assuming the details of the mouse calls are correct. I haven't verified them. > 49 ****************************** > 5D * > 51 * Read Mouse Data > 52 * and Store it > 53 * > 54 ****************************** > 55 Pos PEA $0 ;X pos > 56 PEA $0 ;Y pos > 57 PEA $0 ;Mouse status > 58 LDX #$1703 ;ReadMouse > 59 JSL BOX > 60 PLA > 61 PLA > 62 STA BUFFER > 63 PLA > 64 STA BUFFER+2 > 55 ****************************** > 66 SEC ;Back to 8 bits > 67 XCE > 68 ****************************** > 59 * > 70 * Connect Arrow to Mouse > 71 * Position > 72 * > 73 ****************************** > 74 LDX LXPOS ;PointerRoutine > 75 CMP #$27 > 76 BEQ END This is only working by accident, since A still happens to contain the X position that was stored in BUFFER+2 back on line 64. I assume this supposed to be doing a CPX #$27. It also isn't checking for values greater than $27, which will cause screen holes and/or areas outside the text screen memory to be overwritten. > 77 LDA BUFFER > 78 STA $25 Whoa! What if the Y position is greater than 23? This will result in potential memory corruption of anything past the text screen. There should be a range check on both X and Y, clipping values greater than 39 and 23 respectively to the appropriate limits. Use CMP/BCS to check for an out of range value (BCS = BGE). > 79 JSR $FC22 > 80 CMP #$18 > 81 BEQ END It should never be equal to $18 (24 decimal), and this call should not have been issued if it was this high. > 82 JSR $F94A If the screen is going to be cleared anyway, why print spaces? Just poke the desired position into $24, assuming 40-column mode (which seems to be the case elsewhere). > 83 LDA ARROW ;Arrow character into A > 84 JSR $FDED ;put it on the screen > 85 LDY #$07 > 86 PAUSE LDX #$FF ;Slow down to see the > 87 HOLDIT DEX ;arrow on the screen > 88 CPX #$00 The CPX instruction is unnecessary, except to slow the loop down. > s9 BNE HOLDIT > 90 DEY > 91 CPY #$0 > 92 BNE PAUSE The pause loop is dependent on the CPU speed. It would be a better idea to call the WAIT routine at $FCA8 to get a reasonably predictable delay. > 93 JSR $FC58 > 94 ****************************** > 95 CLC ;Deloop > 95 XCE ;to de > 97 REP $30 ;mouse > 98 JMP POS ; in 15 bits > 99 ***************************** > 100 * > 101 * Shutdown > 102 * > 103 ***************************** > 104 END CLC > 105 XCE > 106 REP That should be REP $30. > 107 ***************************** > 108 PEA $00 ;turn off > 109 LDX #$19D3 ;Setmouse > 110 JSL BOX > 111 ***************************** > 112 PEA $0000 ;Drop ID > 113 LDX #$2103 > 114 JSL BOX Given the earlier call to get an ID, this should be pushing the ID value that was returned, not $0000! If this program is run about 255 times, the computer is likely to crash since no more user IDs are available. > 115 ***************************** > 115 LDX #$0303 ;auit Misc Tools > 117 JSL BOX > 118 ***************************** > 119 LDX #$0302 ;Quit MM > 12D JSL BOX The user ID must be pushed before this call. This will cause the program to crash on exit, as its return address has just been swallowed. > 121 ***************************** > 122 LDX #$0301 ;Quit TL > 123 JSL BOX > 124 ***************************** > 125 SEC > 126 XCE > 127 RTS Well that was fun! :-) Given the evidence, I wouldn't trust anything else from the book that this was quoted from. > TAKEN FROM: > > Library of Congress Cataloging-in-Publication Data > Sanders, William B., 1944- > Elementary assembly language for the Apple IlGS and the 65816 / > William B. Sanders. > P. cm. > Includes index. > ISBN 0-673-18814-0 : $19.95 > 1. Assembler language (Computer program language) 2. Apple IIGS > (Computer)-Programming. 3. 65816 (Microprocessor)-Programming. > 1. Title. > QA76.73.A8S25 1988 > OO5.265-dc19 87-16756 > CIP > > 1 2 3 4 5 6 MAL 92 91 90 89 88 87 > > ISBN 0-673-18814-0 > > Copyright 1988 William B. Sanders. > All Rights Reserved. > Printed in the United States of America. -- David Empson dempson@actrix.gen.nz Snail mail: P.O. Box 27-103, Wellington, New Zealand