DB11 source package Copyright (c) 1996-2000, Clifford Heath, cjh@osa.com.au This is DB11, the loader/debugger for 68HC11 embedded development. It's POSTCARDWARE - try it, and if you want to use it, send me a postcard at the address below. Any use you can find for any of the source code is fine, as long as neither I nor Open Software Associates are blamed for anything it does or doesn't do, and as long as you leave the copyright and postcardware notices intact. DB11 can load programs from S19 files into EPROM/OTPROM, EEPROM, internal or external RAM, and will shortly support FLASH programming as well. Terminal emulation modes include direct or hexadecimal output and/or input (with or without local echo) and MIDI (Music Instrument Digital Interface) protocol interpreta- tion into readable text. Options may be changed interac- tively during a session. As a debugger, db11 communicates through a small "talker" program to implement memory read and examine, breakpoints, single stepping, and code disassembly. db11 is fully scriptable - all commands and commandline options may be embedded in scripts. For more information, read the manual page (db11.man when formatted). Compiling: You need to be using Unix, preferably Linux, and have the g++ compiler. Building DB11 is as simple as saying "make". The resultant files will land in the "inst" directory. Some parts of DB11 require tools you might not have; the "make" will fail for these parts, but they come pre-built so you can ignore the errors. In particular, to reformat the manual page, you need "groff". To rebuild the talkers and example program, you need the GNU tools (gcc, as and binutils) for the 68HC11. If you need a ROM/EEPROM talker to load at an address other than those supplied, you'll need these tools, which are currently maintained by Stephane Carrez and available at <http://home.worldnet.fr/stcarrez/m68hc11_port.html>. Installing permanently: DB11 will pick up *.s19 and *.db11 files from various places, including the current directory, $HOME/.db11/ and /usr/local/db11. You can move those files from the inst directory. The executable and manual page are also installed into the inst directory. You might wish to move them somewhere more convenient. Getting started: Read the manual page first - it's "inst/db11.man". It might be worth having a printed copy at hand. Then create "machine.db11" as a script containing these commands: "bootbaud", "baud", "tty" - see tty*.db11 as examples. With an 8MHz crystal, DB11 always switches to 9600 baud on startup, after bootstrapping at 1200 or 9600, so bootbaud should be one of the latter, and "baud" should be 9600. Increase or decrease these if your clock oscillator differs. You should now be able to run "db11 debug.db11", which will bootload the RAM talker and enter debug mode. Note that if you're using a K series chip, you'll need to change the scripts to use the K series talkers (talkk*.s19). Similar changes are required for D series chips, which place all the CPU device registers at location zero, and page0 RAM (including bootstrap programs) starts at 0x80. You'll almost certainly need external memory with a D series chip. There's a script called "loadhello.db11" which loads a small Hello World demonstration program. You can use it to experiment with disassembly and with setting breakpoints. Various other scripts exist to start the debugger after entering expanded mode, and to enable the 'F1 chip select features, for example. The hello example won't work on A series chips, since it loads at 0x100, and the A series doesn't have memory there. Instead, you should load the eeprom talker - use "db11 debug.db11" to get started, then say "file talkB700.s19". This should load the talker program into EEPROM at 0xB700, and you can start it from a bootstrap script using the "jump 0xB700" command, in place of "boot talkram.s19". This will enable you to load programs into normal RAM at location zero. The K series EEPROM talker is different, but loads at the same address, and for the F series chips, there's an EEPROM talker which it loads at 0xFE80. Finally there's an E2 series talker which loads at 0xFEFE. Be aware that the bootstrap-mode interrupt vectors start at 0xC4 (DB11 uses the SWI vector for breakpoints), and just before that address, DB11 stores seven bytes of variables. The default stack is just below that, and DB11 expects to be able to push five bytes in addition to the 9-byte SWI (software interrupt) frame. So if your program doesn't move the stack, and doesn't push anything onto the stack, you have free RAM from address 0 through 0xAF, 175 bytes in all. In a chip with more RAM than an A series, it's a good idea to move the stack to the top as the first instruction in your program, then you have page0 RAM free from 0 through 0xBC. You'll get mystifying hangs and synchronisation errors if you corrupt the variables, and modifying the SWI vector will stop breakpoints working. I set the memory.x page0 settings to prevent me linking code or data into these areas, but that's perhaps a more advanced topic. If you have external memory, you'll need to poke the appropriate registers to enter special test mode. Look at "expand.db11" for an example. You can include this file from your startup script, or copy in the commands. Read the manual page and experiment with the commands. When you've gained a little familiarity you might wish to load an EEPROM talker into your chip, to save RAM and bootup time for future development. Address for postcards: Clifford Heath, C/- ManageSoft P.O. Box 625, Box Hill 3128, Australia.