ZD-Bug v1.1 ("pseudopostbeta") General Documentation: ----------------------------------------------------- CONTENTS: 1 - What is it? 2 - What are its uses? 3 - How do I install it? 4 - How do I use it? 5 - What's new in version 1.1? 6 - What's coming up? 7 - Bugs 8 - Notes 9 - Credits 10 - Who am I and how can you find me? 11 - That odd clause from someone who doesn't know the difference between copyright law and a half cooked chicken who flosses its teeth daily. 1) WHAT IS IT? ZD-Bug is a combination of simple debugger for ZShell programs and a simple utility pack, both accessable from a screen that pops up when you press ON+PRGM. Ok, so maybe you don't know what a debugger is. In that case, a debugger is a program that helps programmers remove errors from their programs. They typically let you view variables, step bit by bit through a program, trace execution, and view the output screen. This debugger lets you view registers, view & edit memory (including text memory where variables are stored), step through somewhat irregularly sized bits of the program, and view the output screen & graph memory. As a special feature very useful for ZShell programming, it can crash back to ZShell. It lacks a trace function and is not good at debugging interrupt handlers and greyscale programs. To debug them, you can't use the popup; you have to use the API call. Read ZDB_API.txt for more information on the very primitive API. As for utilities, it can capture the screen, increase & decrease contrast, and slow down the calculator by varying degrees. It also has a ZHEdit built-in, which is, in my opinion, the best hexeditor/viewer available for ZShell. What makes these special is that they can be accessed anytime, anywhere, within any ZShell program and TI-OS. Note that popping it up terminates some TI-OS processing functions because it sees that you pressed the ON key. NOTE: All numbers in ZD-Bug, except for in the Delay screen, are in hex (base 16: it uses digits 0-9 followed by A-F). It is necessary that you understand hex if you are going to use ZD-Bug for debugging or memory browsing/editing. 2) WHAT ARE ITS USES? * Debugging ZShell programs Explained below * Studying the TI-85 Looking at the VAT, other memory structures, and the ROM * Customizing ZShell's text Searching for ZShell and editing the textual messages * Changing contrast and screen capturing from within a program Most programs won't let you change the contrast. You can use screen captures for reviews, image piracy;), etc. * Running games properly on a turboed calculator Set the Delay to a factor that makes games run well. * Protecting the contents of memory if a programs hangs (usually) If a program locks, you can usually 'crash back to ZShell.' * Renaming and hiding variables You can fiddle with the data in the VAT to rename variables or make them undeletable and render them invisible from TI-OS. Just change the variable's type to an unspecified one to make it undeletable and invisible. * Fun Well, you know... 3) HOW DO I INSTALL IT? To install ZD-Bug, you need to do one of two things. You either send the included 'ZD-BugEB.85b' memory backup file, which will erase your calc's programs, or you can send 'ZD-Bug11.85g' and run the 'ZDBSetup' PRGM (for some reason, if you use this second method, ZD-Bug often won't search through memory or jump to an address when launched from TI-OS). Once you've done one of these, you run the 'ZD-Bug' ZShell program, which will activate ZD-Bug. To deactivate it, run ZD-Bug again or press ON+CLEAR while ZD-Bug is popped up. If it doesn't appear to be working, run the 'ZD-Bug' ZShell program again once or twice until it says it's activated. ZD-Bug requires minimally 4093 (recommended 4183) bytes of space, in addition to ZShell. It causes NO PERCEPTABLE PERFORMANCE HIT, so you can leave it activated all the time. 4) HOW DO I USE IT? For a command quick-reference, see the included ZDB_CMDS.TXT. For debugging a program, make sure ZD-Bug is activated, and run the prototype program. At various points in the program, you can pop up ZD-Bug and view Text Memory variables by pressing F4 8 0 D F. F4 opens the Jump To Address screen, so by typing 80DF, you set the address at the top of the screen to addr of the beginning of Text Memory. You can also view the registers by pressing MORE. From the register-view screen, you can hold down ON and press RIGHT to execute a small chunk of the program and return to the register view screen. That way, you can see how the registers change. If you want to see what's on the program's screen, press GRAPH. If the program uses Graph Memory as an alternate image storage place and you want to see what's in it, press LOG. To return to the program, press EXIT. In the event that the program locks up, pop up ZD-Bug and press ON+CUSTOM, to return you to ZShell (it's not guaranteed, since a misbehaving program can occasionally do more than ZD-Bug can get past, but it usually works). You can also add a special command to your program to open ZD-Bug at that specific spot (read ZDB_API.TXT for more information). To change the contrast (in the middle of a game, etc., for when TI-OS's contrast change function is not available), pop up ZD-Bug and press RIGHT to increase it, LEFT to decrease it. To capture the screen to Graph Memory (where you can then transfer it to computer with a TI-Graphlink or save it to a PIC), pop up ZD-Bug and press ON+GRAPH. Do not use this on a program that uses Graph Memory for storage space. To jump to ZShell from TI-OS, pop up ZD-Bug and press ON+CUSTOM. You could even remove ZShell from the custom menu if you wanted to and you didn't use any greyscale programs, though this is not recommended. To browse through memory, you can just pop up ZD-Bug and use the up and down arrows. The left column is the addresses of the beginnings of the middle column, which is 10 lines of 8 bytes from memory, in hex. The right column is those same bytes in restricted ASCII (shows 00h and >=D8h as '.'). As a shortcut, you can use + to scroll down a whole screen and - to scroll up one. * scrolls down by 1000h and / scrolls up by 1000h. F4 followed by an address jumps to that address. To change the ROM page, press F2 and use the up and down arrows. F5 starts the search function. It needs it own explaination. To search through memory, pop up ZD-Bug and press F5. You then need to type in the address from which to begin searching. Next, you need to type in the address at which to stop searching. Finally, you type in what you want to search for as up to 78 whole bytes in hex. After, you press enter. If no match was found in the range supplied, you'll find yourself back in the main screen, with no change, after a little while (1 to 5 seconds). If a match is found, you'll find yourself in the main screen with the address of the item at the top. If you search with a range including the address 90B2h, you may end up having found the search buffer (if the address at top is 90B2h, then you have found the search buffer). In that case, search again, but start your range after 90B2h. To edit a memory location, pop up ZD-Bug and scroll to a screenful where that location is visible. Press F3 and then use the arrows to move the bar that appears to under the location you want to edit. Then, press ENTER and type the new value you want in that location. Press enter once again, or any other key to abort (for if you mistyped it). To set or change the the slowdown factor (Delay), pop up ZD-Bug and press the comma key. Use the up and down arrows to change the value. Note that the scale is rather irregular, and that Game Wizard has the same problem. In this case, the scale goes from 0 to 6, and then starts over with 3 at 7, approximately. I can't figure out how to fix this. There's an important new feature in ZD-Bug 1.1: a simple API. Read ZDB_API.TXT for more information. 5) WHAT'S NEW IN VERSION 1.1: Although this version has one significant and a few minor improvements, there are a number things I was unable to implement and a couple of finishing touches I couldn't fit in for this version, due to time constraints. * An API call to popup ZD-Bug (read ZDB_API.txt for more information) * A few changes in the documentation * A slightly improved interrupt loader that can detect if ZD-Bug was turned off by some types of interrupt handlers * Documented a minor bug * Compatibility with CShell-NT version 2.1 is confirmed (of course you can't use ZD-BugEB.85b, you must use ZD-Bug10.85g for installation, and you have to edit ZDBSetup, replacing every time it says ZShell with CShell) 6) WHAT'S COMING UP: Realistically: * An improved interface * Optomized code * A faster search * An easier editing tool Optomistically: * A better API * A piggybacking interrupt handler 7) NOTES: * ZD-Bug requires ZShell version 4.0 or CShell-NT version 2.1 and minimally, 4093 bytes (4183 bytes for the better ZD-BugEB.85b setup method) of memory. * Running a greyscale program or interrupt handler deactivates ZD-Bug and the ZShell program (string) must be run twice to reactivate it. * If you try to send a memory backup to a calculator with ZD-Bug running, the calculator will freeze, so deactivate it first. * The program does not have much internal documentation, so learn it here and in ZDB_CMDS.TXT * This program uses little snippets of interrupt handler and key reading code from Game Wizard by Jimmy Mardell. * ZD-Bug's interrupt handler is loaded into an addition to the end of the ZShell string. I just added the 804 bytes of the 'memory' program. Don't ask my why I did that. Don't ask me why I didn't change it either. * ZD-Bug causes NO PERCEPTABLE PERFORMANCE HIT. (In terms of the program 'Speed Timer,' the hit is ~500/~20000 which is about .003=.3% drop in performance: negligable. By the way, I thought Speed Timer would be thrown off by ZD-Bug's interrupt handler, but a makeshift benchmark confirms its reading.) 8) BUGS: There are no confirmed ones that can lock up the calculator (except for a few situations that aren't part of normal ZD-Bug or TI-85 operation) and no known ones that can cause damage. For a list of the currently known bugs and oddities, see the included ZDB_BUGS.TXT. 9) CREDITS: * Big thank you to Jimmy Mardell for making Game Wizard and for releasing its source code. * Thank you to Per Finander for making Interrupt Demo. * Thank you to whomever made HexView (for the inspiration). * Thank you to Pascal Bouron for making Debugger (so I knew it could be done and for the inspiration). * Big thank you to the List-ZShell staff for making a place for learning and discussing problems. * And, of course, gigantic thankyou to Magnus Hagander, Dan Eble, and Rob Taylor for ZShell! 10) WHO AM I AND HOW CAN YOU FIND ME? * My name is Micah Brodsky. * I am not terribly Internet proficient. * In the occasional moment when I'm on IRC, you'll see 'eightyfiv.' * During the school year, my email: micah_brodsky@lakeside.sea.wa.us During the summer: micahbro@msn.com * You can send any questions, comments or complaints (no flames, please) about ZD-Bug or my other programs to my currently in-use email account. * I typicaly sign off my emails --MZB. * Sorry, I don't have a web page at the moment. 11) ODD CLAUSE: ZD-Bug requires a TI-85 with ZShell 4.0 or CShell-NT 2.1 and minimally, 4093 bytes of free memory. Additional information is contained in the files ZDB_CMDS.TXT, ZDB_BUGS.TXT, and ZDB_API.TXT. ZD-Bug is distributable freely as long as it is destributed in its original form and with all the included files or as a memory backup from calculator to calculator, but MAY NOT be sold. I (Micah Brodsky) and Jimmy Mardell cannot be held responsable for damages from use or misuse of ZD-Bug. This entire document and ZD-Bug Copyright (C) 1997 Micah Brodsky. ZD-Bug uses small portions of interrupt handler and key reading code from Game Wizard. Those parts, Copyright (C) Jimmy Mardell. (4-20-97, modified for 1.1: 6-4-97, version 1.01 docs for ZD-Bug version 1.1)