left arrow - move cursor back 1 character right arrow - move cursor forward 1 character Home - move cursor to first character End - move cursor to last character delete left - delete to left of cursor Del - delete at cursor position CTRL End - delete from cursor position to end of line Ins - insert at cursor position (cursor changes to blocked cursor) up arrow - recall last entered command down arrow - recall last command in recall buffer Esc - Clear command line
In addition, the Esc key can be used to terminate most commands in progress. e.g. MD, DASM, ASM.
The 4 lines above the command line provide a trace of the last 4 commands executed.
The next line above this displays break point and last error messages.
An error code is returned to MS-DOS?, with one of the following meanings:
Error Code Meaning ---------- ------- 0 No error 1 VERF error 2 MS or BF error 3 Talker communication failure.
In MS-DOS? Batch files the error code can be checked with ERRORLEVEL.
ASM addr [mne|dir] - Call symbolic macro line assembler, with option to auto insert mnemonic or directive BAUD [rate] - Display/Set serial baud rate BF addr1 [addr2] byte|word - Block fill memory with byte or word BL - Display breakpoints BR [addr [macroname]] - Display/Set break point [with optional Command Macro execution] CALL addr - Execute the subroutine at addr CLRM - Clear all Command Macros CLS - Clear main window CONTROL [parameter] - Display/Change PCbug11 system parameters DASM addr1 [addr2] - Disassemble from addr1 [to addr2] DB startaddr [endaddr] - Display MCU Memory DEBUG - Reserved word DEFINE symbol value|address - Define a symbol DEFM macrnam|TRACE|AUTOSTART - Define Command,Trace or Autostart Macro DELM macrnam|TRACE|AUTOSTART - Delete Command,Trace or Autostart Macro DIR [mask] - Display Disk Directory DOS [command] - Shell to DOS/Execute DOS command EDITM macrnam - Edit a macro EEPROM [startaddr [endaddr]] - Display/Clear/Set EEPROM Address Range(s) EEPROM DELAY option - Set EEPROM erase/write programming time EEPROM ERASE [option] - Display/Change EEPROM Erase-before-Write EPROM [startaddr [endaddr]] - Display/Clear/Set EPROM Address Range(s) EPROM DELAY option - Set EPROM erase/write programming time FIND byte|word addr1 addr2 - Find all occurrences of byte or word between addr1 & addr2 FIND mnemonic addr1 addr2 - Find all occurrences of mnemonic between addr1 & addr2 G [addr] - Start User Code Execution HELP - Display Help Information KLE - Kill last error message LOADM [filename] [macroname] - Load Macro Definitions from Default/User File LOADS filename [loadaddr] - Load S Record File into MCU Memory LS symbol - Display symbols LSTM [mname|TRACE|AUTOSTART] - Display Macro Names/Definitions MD startaddr [endaddr] - Display MCU Memory MM addr - Modify memory from addr MOVE addr1 addr2 addr3 - Move MCU Memory between addr1 & addr2 to addr3 MS addr byte|word [byte|word]- Set MCU Memory Byte(s) or Word(s) MSG [string] - Display Message in Main Window NOBR [address] - Remove all/specified Break Points PAUSE [ms] - Wait for any Key Press/Delay Time PRINT - Display PCbug11 version number PROTECT [startaddr [endaddr]]- Display/Clear/Set Write Protected Address Range(s) QUIT [Y] - Terminate PCbug11 session [without confirming] RD [T] - Display/Trace MCU Registers RESET [addr] - MCU Hardware Reset with Existing/New Reset Vector. RESTART [option] - Restart PCbug11 with Same/New Option. RM - Modify MCU Registers in window RS register value - Set value of MCU register S - Stop User Code Execution SHELL ["command" ;P] - Shell to DOS/ Execute DOS command SAVEM [filename] - Save Macro Definitions in Default/User File T [addr] - Trace User Code TERM [X1 Y1 X2 Y2] - Simple windowed terminal emulator TYPE filename - Display Disk file in Main Window UNDEF symbol - Undefine a symbol VER - Display version number VERF ERASE addr1 [addr2] - Verify that memory contains $FF VERF SET addr1 addr2 value - Verify that memory contains value VERF filename [memaddr] - Verify S record disk file against memory WAIT [ms] - Wait for ms Special Key operations: CTRL B - Send Break on COM channel CTRL P - Toggle MCU Memory Write Protect/RTS line CTRL R - Attempt to re-synchronise talker
6.2.1.1 EVM Compatible commands
These commands operate in a similar manner to the command of the same name on the Motorola 68HC11 EVM systems. ASM, BF, BR, G, HELP, MD, MM, NOBR, RD, RM
Macros may be defined by the user either in PCbug11 or externally using a text editor. It is possible to define more than one macro while using PCbug11 and the area where the macros are held is called the macro library. Macros have two main elements - names and definitions. Every macro is known by a name. This name can be any sequence of letters up to 80 characters long except for reserved commands within PCbug11. The macro is run by typing its name in the same way as for other PCbug11 commands.
The macro definition consists of the commands which are to be carried out by the macro. The commands are executed in the order in which they are defined.
The total space within PCbug11 allowed for the macro library is limited only by the size of the memory on the PC. This should be more than enough for most applications. There is no limit on the maximum number of macros allowable as long as the maximum memory limit is not exceeded. If a macro is defined which has the same name as a macro which existed previously then the macro which existed is automatically deleted, although PCbug11 does warn the user before proceeding.
Macros in the macro library are lost when PCbug11 is terminated. For this reason it is possible to store macro libraries on disk and load them again when required by PCbug11. Macros are stored on disk in a special text format.
The files may be edited by text editors provided the special format is always obeyed. When macros are stored after being defined from within PCbug11 this special format is automatically generated. When a macro library file is loaded all macros within that file are loaded and added to the current macro library.
It is possible to have macros refer to other macros in their definition. This means that a macro can be called by another macro as if it were a standard PCbug11 command. This nesting of macros is allowed to be up to 5 levels deep. This means of course that a macro should never call itself.
Macros can also be passed parameters. That is, a macro may be defined with certain parameters left as blanks to be filled in later. When the macro is called the parameters called with it are used to fill the blanks in the definition. Parameters are defined by using the "@" character followed by a number to indicate which parameter is to be used. @0 indicates the first parameter passed, @1 the second up to @9 which is the last parameter. Macros will not accept parameter numbers greater than 9.
Secondly, the macro may be defined within a text file. A standard format is used. The definition of this format is under the DEFM command. The format is very simple. The first line of the macro must contain the reserved word DEFM followed by the name of the macro being defined. This must be followed by a line containing the word BEGIN on its own. After this any number of lines may be entered containing PCbug11 commands. It is usual to proceed these lines by a tab or space character. The macro definition is terminated by the reserved word END. Another macro may be defined immediately following this line.
As described before parameters may be passed into a macro. They replace special symbols according to their position in the macro command. The parameter positions are defined by the @ symbol followed by a number from 0 to 9. The parameter expressed first on the macro command line replaces the @0 symbol. The second parameter replaces the @1 symbol.
For example, suppose a macro named RUNIT has been defined which uses two parameters. The definition of RUNIT is:
DEFM RUNIT {Macro definition} BEGIN LOADS @0 {Load S-record whose name is 1st parameter} VERF @0 {Verify the S-record} G @1 {Run a program at the second parameter} ENDComments are enclosed in {} and are ignored and thrown away by PCbug11.
This macro can now be used to automatically load and verify and run a program with one simple command. To load, verify and run an S-record called TRYIT.S19 and run it from address $E000 simply type :
RUNIT TRYIT $E000
Macros may be loaded automatically when PCbug11 is run from the DOS prompt. This is done by placing the name of the macro library file on the command line after the talker/boot option. If there is a macro within this file called "AUTOSTART" then this macro is run automatically before the user begins working. This is very useful where the user has to run certain commands before using the hardware. Parameters may be passed to the AUTOSTART macro by enclosing them in brackets () in the PCbug11 command line immediately following the macro= option. Due to the way PCbug11 stores macros internally, it is possible for a macro to exist which does not contain any commands. The definition for such a macro would be:
DEFM macro1
BEGIN
END
Macros like this are termed null macros. They can be run, saved, deleted etc. like any other macro. They can be defined as breakpoint macros. Null macros are normally used in development work when a macro is required, but its exact operation is unclear. The user would therefore define a macro, but leave it null - basically as a reminder.
The text file has an additional advantage in that comments may be included in the file. Macros in text files may be regarded as 'source' files for PCbug11. In fact macros are run using an interpretive system (no compilation is needed), but text files are easier to maintain than libraries created in PCbug11 itself. Note that by using the DOS command the user may work on macro text files without having to exit and restart PCbug11.
Bear in mind that although macros may be saved from PCbug11, any comments which existed in a library previously loaded are discarded. This means that if a macro file is loaded (including comments) and then saved then the comments in the original file will be lost.
Macros may be deleted in two ways. Firstly, all macros may be removed at the same time. This is achieved by using the CLRM command. No check is made by PCbug11 before this is done. Secondly, a single macro may be deleted using the DELM command.
Note that if a macros is loaded which has the same name as a macro already existing then the current macro is replaced by the new one. This is not true of the definition (DEFM) of a new macro when a check with the user is made.
A breakpoint is placed at a certain point in the program by the user to allow the examination of internal variables etc. When the program reaches that point it will stop. This feature may be implemented in several different ways. In PCbug11 breakpoints are created by using the SWI (software interrupt) command of the 68HC11. When the program executes a SWI an interrupt is caused which allows PCbug11 to regain control of the HC11. This has two main implications.
For PCbug11 to be able to insert a breakpoint, the memory containing the program must be alterable. PCbug11 simply replaces the opcode at the address of interest with the SWI opcode. If the memory containing the program is ROM then no breakpoints can be installed. In fact PCbug11 will warn of this, but will run the program anyway. In the second place, PCbug11 must be able to alter the SWI interrupt vector. Again if this is in ROM then no breakpoints maybe implemented.
This also means that the user is inhibited from using SWIs in his program - at least in a real time sense. PCbug11 will remember what the user has set the SWI vector to and if an SWI is encountered which is not intended to be a breakpoint then PCbug11 will cause the program to jump to he location indicated by the user SWI vector. This interference causes a delay in the response to a user SWI. If no breakpoints are installed then no delay will be experienced (above the normal latency).
Breakpoints are created by using the BR command. As soon as the breakpoint is specified PCbug11 will change the SWI vector to a new value for its own use and will store the user's SWI. The breakpoint itself will only be placed into the program when the program is run. The user opcode at the address of interest is read and stored by PCbug11. Multiple breakpoints may be specified and all will be written into the user program when it is run. As long as breakpoints exist the SWI vector will be reserved by PCbug11.
When a breakpoint is reached by the program a small program is run by the HC11. This informs PCbug11 that an SWI has been reached. PCbug11 checks to see whether this is a breakpoint or not. If it is then a message is displayed on the screen of the PC and a macro may be run if necessary. At this point PCbug11 will display the BREAK status.
Note that the SWI will remain in the program until a stop S instruction has been executed.
If the program exists in EEPROM or battery backed RAM then it is possible that the SWI vector and the SWI opcodes could be left in the memory. The SWI vector will be left if the hardware is powered down while breakpoints still exist. SWIs would be left in memory if a stop S has not been executed, after the program has been run, before the hardware is powered down.
Tracing is very similar to breakpointing. In practice it may be desirable to step through a program instruction by instruction. It is possible to do this by breakpoints. This involves placing a breakpoint at the address immediately following the assembly command to be executed. This would require a large amount of user involvement and so PCbug11 can do this automatically. This is achieved by the trace command T.
This is an extremely complex operation for PCbug11 to perform and therefore can be a noticeably slower process. The reason is that PCbug11 must find for itself the address of the next opcode in the program. This involves disassembling the opcode at the current address and deciding how many bytes follow it. The process is complicated if the opcode is a jump and even more so if a branch. In normal cases an SWI replaces the next opcode in the program. For a jump the destination opcode is replaced. For a branch two opcodes have to be replaced. The one following the branch instruction and the one at the destination of the branch.
Once the SWI has been placed in memory, PCbug11 will run the program. The second instruction it sees will be an SWI and so the program will be stopped. Again PCbug11 must be able to amend the contents of the SWI vector and the program memory. A macro may be specified which will be executed when the trace command hits a trace SWI. This macro must be called TRACE and can contain whatever the user requires. Typically the macro would disassemble the current instruction and perhaps read the registers. The macro can also contain the trace command T itself. In this case the program would step through all its instructions until stopped by the user or it hits a self loop The self loop condition occurs when a program jumps or branches to the location it is already at. In this case it is pointless to perform a trace and so the program continues to run and displays the status TRACE until stopped by the user (S command) or the branch condition is met/failed.
An alternative approach to this is to install the talker in the on-chip EEPROM of the HC11 or in an external memory. Then whenever the package is run it is not necessary to download the talker program to the board. Additionally, since the talker does not reside in RAM the only areas which the user may not use are the stack area and the interrupt vectors (for bootstrap mode).
Talkers which reside in EEPROM are loaded by first booting up the HC11 as normal. Then the EEPROM area must be defined. Then the talker must be installed using the LOADS instruction. It is probably best, next to verify the installation using the VERF command. Once verified correctly the talker is ready to use. The user should terminate PCbug11 and run it again selecting the correct .MAP file instead of the usual boot option (see section 7.5).
A special talker is available which already uses the internal EEPROM. This is called TALKEREE.
It is important that two files are available when using this option. These are TALKEREE.S19 and TALKEREE.MAP. The .S19 file is the S record format of the talker to be installed in EEPROM - this must be in the user's current directory. The .MAP file is a list of addresses which PCbug11 uses to ensure good communication with the board. The information contained in the .MAP file is normally handled internally by PCbug11 when the boot option is used. The .MAP file must also be in the user's current directory.
For example, to program the talker into EEPROM on a 68HC11E9 the following macro could be used:
DEFM AUTOSTART {Run this macro automatically}
BEGIN
MS $1035 0 {Clear BPROT register - not needed on A8}
EEPROM $B600 $B7FF {Enable EEPROM algorithm}
LOADS TALKEREE {Program talker into EEPROM}
VERF TALKEREE {Verify programming was OK}
QUIT Y {Exit PCbug11}
END
If the above macro is saved in a file called STARTUP.MCR then the following sequence can be followed.
1/ Startup PCbug11 by typing: PCBUG11 -E STARTUP 2/ Reset board. 3/ Startup PCbug11 by typing : PCBUG11 TALKEREE
The EEPROM talker is now running.
Notes :
Do not connect XIRQ to PD0/SCI Rx
Place the part in bootstrap mode and pull IRQ to Vdd Connect Vdd to the chip
Connect Vpp to the XIRQ pin via a 100 Ohm resistor
NOTE : DO NOT CONNECT ANY Vpp VOLTAGE UNLESS Vdd IS CONNECTED. FAILURE TO FOLLOW
THIS SEQUENCE WILL CAUSE THE CHIP TO BE DESTROYED.
Attach Vdd to your board and startup PCbug11 as follows:
PCBUG11 -E/D/K (For 711E9/711D3/711K4)
After ensuring that the board is working normally and that Vdd is applied then apply Vpp to the Vpp terminal on the board.
Type commands:
EPROM $D000 $FFFF To define the EPROM memory range
LOADS Load the S record file to be programmed
VERF To verify programming is successful
Once the part has been successfully program remove Vpp BEFORE Vdd.
In such cases the bootstrap talker would need to be rewritten. In practice this will normally be done by Motorola and so it would be wise to check that the program has not already been amended before proceeding to change a bootstrap talker.
However, ROMed talkers are more likely to require customisation by the user. Here PCbug11 requires two files to be created. Firstly, the talker itself must be supplied/modified and loaded into external memory. Secondly, a file called a mapfile containing the addresses of several key talker program routines. Together these allow PCbug11 to operate with any customised talker. The .MAP and .ASC files for TALKEREE should be used as templates when creating new ROMed talkers. By sticking to conventions obeyed there the user should avoid any major problems.
Boot talkers may be customised by modifying the source file for the most appropriate TALKXX.ASC file in TALKSRC or TALKSRCX. The new binary download file is created by using the ASMHC11 assembler with the ;B option. A typical command line would be :
ASMHC11 TALKXX ;B
This will search for the TALKXX.ASC file and create a download file with extension .BOO. If the file actually uses the XIRQ interrupt then the filename should be renamed to a .XOO file to avoid confusion.
The hardware places the part in bootstrap mode using the mode pins and the SCI communications port is translated to RS232 voltage levels using a MC145407 chip or equivalent. An oscillator or crystal is also required. Pulling up the IRQ pin will improve reliability. Pulling up other input pins will reduce current supply but is not necessary when working on the bench.
If the user has an alternative method of translating the voltage levels then the MC145407 solution could be replaced. Incidentally, the application note describes a simple program which does a much simpler task than PCbug11, but uses exactly the same principles and may provide interesting background reading for the user.
Note that the key elements are to place the part into bootstrap mode and to have access to the SCI.
There are three levels of error reporting within PCbug11:
1/ Errors which report a failed operation 2/ Errors which indicate a failed communication 3/ Errors which report a bad command stringErrors reported by the assembler are explained in section ASM.
Last error :wherefailed
Command Error This is returned when a command is entered which is neither a
PCbug11 command nor a currently defined macro.
Operand Error This is returned when the operand of a command is incorrect.
See the command list for the correct operands of
each command.
Range Error This is returned when a command which includes arange of addresses
has exceeded the maximum range allowed.
Disk PCBUG11.EXE+ PCbug11 program
PCBUGRTN.EXE+ Return program - user definable
CODES.P11+ Mnemonic tables for assembly/disassembly
OFFSETS.P11+ Mnemonic tables for assembly/disassembly
ASMHC11.EXE Absolute assembler program
CONVERT.EXE Program which converts older macro libraryfiles
to V3.0 text macro files. This program is only used
if the user has macro files generated under old
versions of PCbug11.
TALK??.BOO Talkers using SCI interrupt
TALK??.XOO Talkers using XIRQ interrupt
PCbug11.HLP This file contains all the help details forPCbug11.
The HELP feature will not work unless this file is
in the same directory as PCBUG11.EXE
TALKSRC This directory contains the source files and S-records
of all the talkers which can be loaded into EEPROM/EPROM
and use the SCI interrupt.
TALKSRCX This directory contains the source files and S-records
of all the talkers which can be loaded into EEPROM/EPROM
and use the XIRQ interrupt.
PCbug11 will not work unless these files/directories are all in the same directory
Periodically, this software may be updated and enhanced. Information on the latest version with respect to V3.20 may be included on this disk.
Remarques à Jacques.Weiss@supelec.fr