Command Glossary
This section lists all the commands used by uBug12. The commands fall into several categories:
Registers: RD, RM, D, X, Y, SP, PC, A, B, CCR, CCH, PP, EP, RP, GP
Memory: BF, BFW, MD, MDW, MM, MMW
Flash/EEPROM: FBULK, EBULK, FPERASE, FLOAD, FLOADBIN, ELOAD, RLOAD, VERF, FVERF, FSAVE
Informational: DEVICE, MEMINFO, VERSION, HELP
Debugging: GO, HALT, RESET, TRACE, BR, BRB, BRC, BRD, DISASM
GUI: CON, DISCON, ABORT, EXIT, DOS, TERM, CLEAR, VT100, INSTALL, L, DEL
Each of the uBug12 commands will now be listed in ASCII order. Command options will be shown in curly braces, like {filename}. Required parameters will be in italics, such as data8value. All numbers are assumed to be in hexadecimal by the parser. For 8 bit values, if a number is provided larger than 8 bits, then only the lower 8 bits are used. For 16 bit values, if a number is provided larger than 16 bits, then only the lower 16 bits are used.
A
Syntax: A data8value
Name: Modify A Register
Description: Changes the current value of the A register to data8value.
Other Considerations: None
ABORT
Syntax: ABORT
Name: Abort the currently running command thread.
Description: When a command is executed, it is forked off as another process. ABORT can be used on only potentially long running commands such as VERF, FLOAD, FSAVE, MD, MDW, etc., to end that process in a clean way.
Other Considerations: On commands that are expected to run quickly, ABORT has no affect. Instead, internal timeout counters will abort the thread if it does not complete in a timely fashion.
B
Syntax: B data8value
Name: Modify B Register
Description: Changes the current value of the B register to data8value.
Other Considerations: None.
BF
Syntax: BF startAddress endAddress data8value
Name: Block Fill with byte values
Description: Fills each byte in the specified data range, inclusive, with the value of data8value.
Other Considerations: WARNING: It is not recommended to use BF to program Flash or EEPROM memory. These memories are best programmed by word values rather than byte values.
BFW
Syntax: BFW startAddress endAddress data16value
Name: Block Fill with Word value.
Description: Fills each 16-bit word in the specified data range, inclusive, with the value of data16value.
Other Considerations: It is best to use this command starting at an even word boundary. (i.e. Address Bit 0 has a value of 0.)
WARNING: Flash and EEPROM should only be programmed on even word boundaries with 16 bit values.
BR
| Syntax: | BR | address12 | {gpage} |
| BRB | address12 | {gpage} | |
| BRC | address12 | {gpage} | |
| BRD | address12 | {gpage} |
Name: Define Breakpoint A, B, C, or D in the MCU Debug module.
Description: Sets the hardware debug module with a breakpoint to a memory location. That breakpoint is triggered when it is accessed, either by an instruction execution, or a read or write of data at that location.
Other Considerations: It is possible to enter up to either two or four breakpoints, depending on the MCU type. However there are several rules to keep in mind when using Breakpoints:
- You must use the BR command to enter the first breakpoint. Doing so will clear out any other breakpoints that have been set.
- Never set a breakpoint on an instruction that changes the system clock, even if it is to the same value. If you do, when the breakpoint is hit, uBug12 will drop the connection.
- The BR command can be followed by BRB, BRC, and/or BRD. It is recommended that they be set in this order.
- Since the S12X series uses a 23 bit physical address space, the actual address used by the S12X type Debug module is a Global Address, which is why the GPage for the breakpoint can be entered as part of the command. If this is left out, the program assumes a value of $7F, which will work for any standard Flash location in that series. (PPAGE = $FE)
- If a breakpoint is set for any other location for the S12X series (i.e. RAM or EEPROM), You will need to set GPAGE value AND adjust the address accordingly to be in the Global address space.
- Use of the TRACE command clears out all breakpoints.
- Once a breakpoint is triggered, the Debug module is disarmed. You will need to re-enter at least one breakpoint to rearm the module.
CCH
Syntax: CCH data8value
Name: Change Condition Code Register High byte value for S12X series.
Description: This sets the upper byte of the 16-bit Condition Code register in the S12X CPU. The lower three bits are the only ones used, and they hold the Interrupt Priority Level (IPL) value. IPL can only have values between 0 and 7 inclusive. This is a way of prioritizing interrupts so that no interrupts at this level or below will be serviced.
Other Considerations: If IPL is set to 7, no maskable interrupts will be serviced, even if the I bit is cleared in standard Condition Code register (Lower 8 bits of Condition Code register).
CCR
Syntax: CCR data8value
Name: Change Condition Code Register value
Description: This changes the flags in the Condition Code Register, which is used to control program flow, arithmetic operations, and interrupt handling. The bits correspond to the following flags:
| Bit 7 | Stop enable |
| Bit 6 | XIRQ mask |
| Bit 5 | Half Carry |
| Bit 4 | Interrupt mask |
| Bit 3 | Negative |
| Bit 2 | Zero |
| Bit 1 | Overflow |
| Bit 0 | Carry/Borrow |
Other Considerations: Changing the CC register can cause the user program behavior to become unpredictable.
CLEAR
Syntax: CLEAR
Name: Clear the screen display.
Description: Clears the text area on the screen.
Other Considerations: None.
CON
Syntax: CON {comport {baudrate}}
Name: Connect to target board.
Description: This sets up the communication between uBug12 and the serial monitor in the Flash memory. It will search for the Serial port if it is not specified. Otherwise it must be given the OS name for the port. The default value for 'baudrate' is 115200, and need only be specified here if there is a modification to the serial monitor in Flash that requires a different value.
Other Considerations: CON will report a failure if the cable is not physically making a connection, the port name listed is incorrect, or if the baud rate is not matching between uBug12 and the serial monitor. If using CON to search for the port causes uBug12 to hang, then you will need to EXIT uBug12, restart the program, and specify the port explicitly with CON. Also, incorrect parameters will put uBug12 in a state that will require a restart of the program.
Port names are case sensitive, even with Windows! (e.g. COM5)
You may also use a shortcut for Windows of only specifying a port number (i.e. '5' for 'COM5'). uBug12 will then prepend the 'COM' string.
D
Syntax: D data16value
Name: Change D register to value.
Description: Changes the current value of the D register to data16value.
Other Considerations: Remember that D is a concatenation of the A and B registers, with A being the most significant byte.
DEL
Syntax: DELfilename
Name: Delete file in project directory.
Description: Deletes a file in the current project directory. This is best used when working on a project. The entire filename must be given. No wildcard chars accepted.
Other Considerations: DEL does not delete the contents of any arbitrary directory, or any subdirectories.
DEVICE
Syntax: DEVICE
Name: Print out device type connected to uBug12.
Description: This checks the Device ID register on the chip, and prints out the device type. Sample output is:
MC9S12XDP512 Rev 1.0
Other Considerations: None.
DISASM
Syntax: DISASM {num_instr {address}}
Name: Disassemble instruction(s) in memory.
Description: Show assembler source for num_instr lines, specified in decimal, and starting at address, given in hexadecimal. If address is absent, the current PC value is used. If the number of instructions to decode is not specified, then only the next instruction will be done.
Other Considerations: Some indexed instructions may appear in a non-standard format. Also, if decoding in the PPage area of Flash, it will use the current PPage value.
DISCON
Syntax: DISCON
Name: Disconnect from target board.
Description: Terminates the serial communication between uBug12 and the Technological Arts module. uBug12 will respond with "DISCONNECTED". The CON command will be needed to establish the connection again if needed.
Other Considerations: This is only useful if you want to have another application use the same serial port to talk to the target board, and don't want to terminate uBug12 while that communication is taking place.
DOS
Syntax: DOS Native_OS_command
Name: Native Operating System command execution
Description: This is designed to be used in a command script to allow automation of the troubleshooting process. For example, to start up a text editor, a command line in Windows could be set up as:
DOS "C:\Program Files\WinEdit\WinEdit.exe" "C:\S12XIDE\IDE\Fcode.asm"
Other Considerations: For Windows, it is best to enclose command components in double quote characters, particularly if pathnames have spaces in them. It is also recommended using the full pathname for the executable, and any parameters that need it, as in the example above. This command is intended mainly for use in command script text files, rather than manual use with the input text box. Windows built-in commands must be entered as in this example:
dos cmd /c dir
EBULK
Syntax: EBULK
Name: Erase Full EEPROM
Description: Erases all of the on-chip EEPROM memory, except protected memory at the top of EEPROM if that has been set up.
Other Considerations: WARNING: If you are planning to use the serial monitor to program and erase the EEPROM, it is recommended that you NOT write protect the EEPROM. This means the module will prevent further erasing or programming of the specified section by the serial monitor. Be careful, as the possibility exists that a value could be accidentally written into the memory location that will disable the entire EEPROM from any further writing or erasure. Should that occur, the only way to reset the EEPROM memory will be with the use of a BDM pod.
ELOAD
Syntax: ELOAD {filename}
Name: EEPROM program of S-record.
Description: Programs EEPROM memory with an S1 or S2 S-record file.
Other Considerations: If a filename is not provided, uBug12 will present a dialog box for the user to select the S-record file. S1 files will use the default EPAGE value of $FE for the S12X series. S2 files are assummed to be in a banked format. This means that the most significant byte of the 24 bit address in each record line is used to program the associated EPAGE register on the S12X. The other 16 bits in the address must be in the bank area for that memory. EEPROM S2 records must have the 16 bit address between $0800 and $0BFF. What this means is that to use an S2 file to program EEPROM starting at $0C00, the S-record will have its start address as $FF0800.
WARNING: If you are planning to use the serial monitor to program and erase the EEPROM, it is recommended that you NOT write the EEPROM location at $0FFD for S12X devices, etc. (Check the documentation for your MCU for the precise memory location used to set write protection.) This will set write protection for the EEPROM, which includes that location. This means the module will prevent further erasing or programming of the specified section by the serial monitor. If this is done, the possibility exists that a value could be accidentally written into this memory location that will disable the entire EEPROM from any further writing or erasure. Should that occur, the only way to reset the EEPROM memory will be with the use of a BDM pod.
EP
Syntax: EP data8value
Name: Set EPAGE register to value.
Description: This is an S12X series command. Setting the EPAGE register determines which EEPROM 1K bank is visible in the CPU address space from $0800 to $0BFF. Usually EEPROM size is 4K, so there are only four banks available.
Other Considerations: If the PC register is currently pointed to somewhere in this range, unpredictable results will occur when a TRACE or GO instruction is used. The standard valid values are from $FC through $FF. uBug12 will reject any other values.
EXIT
Syntax: EXIT
Name: Exit uBug12 program.
Description: This terminates the uBug12 program.
Other Considerations: Aliases of BYE and QUIT are also accepted.
FBULK
Syntax: FBULK
Name: Erase all Flash and EEPROM memories.
Description: This will erase all Flash and EEPROM memory on the MCU, except for any protected areas.
Other Considerations: If the protected area of EEPROM needs to be reprogrammed, a BDM pod will be required to do this.
FLOAD
Syntax: FLOAD {filename}
Name: Load Flash memory from S-record.
Description: Programs Flash memory with an S1 or S2 S-record file in either banked or linear format.
Other Considerations: If a filename is not provided, uBug12 will present a dialog box for the user to select the S-record file. S1 files will use the default PPAGE value of $FE, $3D, or $3E, as appropriate for the MCU type. S2 files are determined to be in either banked or linear format based on MCU type and address range in the S-record. This means that for the banked format, the most significant byte of the 24 bit address in each record line is used to program the associated PPAGE register on the MCU. The other 16 bits in the address must be in the bank area for that memory. Flash S2 records must have the 16 bit address between $8000 and $BFFF. What this means is that to use a banked S2 file to program S12X Flash starting at $4000, the S-record will have its start address as $FD8000.
FLOADBIN
Syntax: FLOADBIN data8value startAddress {filename}
Name: Load Flash memory directly from file contents.
Description: Programs Flash memory directly with the binary contents of a file into the PPAGE band specified by data8value and starting at the address in the range $8000 to $BFFF specified by startAddress.
Other Considerations: If a filename is not provided, uBug12 will present a dialog box for the user to select the binary file. The provided address must be between $8000 and $BFFF. If the file contents go beyond the end of the 16K selected page, the contents will continue automatically into the next sequential page number. This command is a good way to get large sections of text into Flash, or table data generated by an external program.
FPERASE
Syntax: FPERASE {data8value}
Name: Erase specific PPAGE in Flash memory space.
Description: Erases the specified 16K page in Flash memory.
Other Considerations: Only valid values for the MCU type are allowed. All others are rejected. If no value is given, the default reset value will be used.
FSAVE
Syntax: FSAVE {filename}
Name: Save Flash contents to file.
Description: The entire contents of the MCU Flash is written to disk using the provided filename. If a filename is not provided, you will be prompted for one.
Other Considerations: The S-record file is in banked S2 format.
FVERF
Syntax: FVERF {filename}
Name: Fast Verify Flash memory contents with S-record.
Description: This is an optimized compare for an S-record file with the current contents of Flash memory ONLY. S1 or S2 records can be used.
Other Considerations: If a filename is not given with the command, uBug12 will prompt for one. The output will also be lengthy if the S-record is completely different from memory.
GO
Syntax: GO {address}
Name: Start User application execution.
Description: This starts the user application code at {address}.
Other Considerations: Internally this does an RTI assembly instruction. If the address is not specified, the current value of the PC register is used.
GP
Syntax: GP data8value
Name: Set GPAGE register value.
Description: This is an S12X command. This sets the GPAGE register with the lower 7 bits of data8value. GPAGE can not have bit 7 set, so the command will always keep this bit at zero.
Other Considerations: The GPAGE register is only used by instructions made for Global Addressing, like GLDAA.
HALT
Syntax: HALT
Name: Halt user application execution.
Description: This command is used when a user application is running, to stop program execution immediately, and force the serial monitor to take over.
Other Considerations: HALT is generally used to troubleshoot when an application is stuck in a loop, or not behaving properly.
HELP
Syntax: HELP {command}
Name: List uBug12 commands to screen.
Description: List uBug12 commands that are currently allowed, based on current connection status to MCU and type of MCU, or show detailed help for the stated command.
Other Considerations: None.
INSTALL
Syntax: INSTALL [ASM12|PERL|USBDM|TERATERM|NOTEPAD++|ALL]
Name: Install third party utility to be used by uBug12.
Description: Downloads associated 3rd party utility installer via the Internet, and starts it. uBug12 can then call that utility as needed to extend its functionality. The ALL option is
best used by Windows users when first setting up uBug12. See the section in this manual titled 'Extending uBug12 Using INSTALL' for a more detailed explanation.
Other Considerations: Since 3rd party programs retain theircopyright, uBug12 can not include these programs outright. Therefore uBug12 will download and run the installer, just as you would if you went to the associated URL directly. TERATERM and NOTEPAD++ will set those programs as the default under File > Program Options.
L
Syntax: L {regular expression}
Name: List files in project directory.
Description: Prints out a list of files in the current working directory. This is best used when working on a project. The list of files given can be filtered using an optional regular expression. For example, to view just text files, type: L *.txt
Other Considerations: L does not take a parameter to show the contents of any arbitrary directory, or any subdirectories. You can read about regular expressions at:
http://www.zytrax.com/tech/web/regex.htm
MD
Syntax: MD startAddress {endAddress}
Name: Memory Display byte
Description: Displays the memory locations from startAddress to endAddress inclusive. If endAddress is not provided, MD will display eight bytes starting at startAddress.
Other Considerations: None.
MDW
Syntax: MDW startAddress {endAddress}
Name: Memory Display Word
Description: Displays the memory locations from startAddress to endAddress inclusive. If endAddress is not provided, MDW will display eight words starting at startAddress.
Other Considerations: None.
MEMINFO
Syntax: MEMINFO
Name: Show device memory information.
Description: Displays the memory parameters for this MCU, such as ranges for PPAGE, RAM and other memory as applicable for this device.
Other Considerations: None.
MM
Syntax: MM address data8value
Name: Memory Modify byte
Description: The byte in memory at address is written to have the value of data8value.
Other Considerations: If address is in RAM, then the MM command is automatically re-entered on the command line with the next sequential address. All that is needed is the new value for that location to be entered. This allows small routines to be entered quickly into RAM for testing. The repeat mode is exited by just pressing the Enter key without inputting a value to write to the prompted location.
WARNING: It is not recommended to use MM to program Flash or EEPROM memory. These memories are best programmed by word values rather than byte values.
MMW
Syntax: MMW address data16value
Name: Memory Modify Word
Description: The word in memory at address is written to have the value of data16value.
Other Considerations: It is best to use this command at an even word boundary. (i.e. Address Bit 0 has a value of 0.)
WARNING: Flash and EEPROM should only be programmed on even word boundaries with 16 bit values.
PC
Syntax: PC data16value
Name: Set Program Counter value.
Description: Changes the current value of the Program Counter register to data16value.
Other Considerations: Changing the PC register will change what the next instruction executed will be when TRACE or GO are used, if GO does not have an address specified.
PP
Syntax: PP data8value
Name: Set PPAGE register value.
Description: This changes the Flash page visible in the CPU address space from $8000 through $BFFF.
Other Considerations: If the PC register is set to an address in this region, changing PPAGE will cause unpredictable results if user program execution resumes with TRACE or GO. Only valid values are accepted. uBug12 will reject any other values.
RD
Syntax: RD
Name: Register Display
Description: Displays the contents of the S12(X) CPU registers, along with PPAGE, and other related registers. A typical result would look like this:
PP PC SP X Y D = A:B CCR = SXHI NZVC IPL EP RP GP
FE FFFF 4000 0000 0000 00:00 1101 0000 00 FE FD 00
Other Considerations: The register values are as the application program sees them, not as the serial monitor is currently using them.
RESET
Syntax: RESET
Name: Reset target board
Description: Forces a hardware reset of the module.
Other Considerations: This command causes a COP timeout to force a hardware reset on the board.
RLOAD
Syntax: RLOAD filename
Name: Load S-record into RAM memory.
Description: Programs RAM memory with an S1 or S2 S-record file.
Other Considerations: If a filename is not provided, uBug12 will present a dialog box for the user to select the S-record file. S1 files will use the default RPAGE value of $FD for the S12X series. S2 files are assummed to be in a banked format. This means that the most significant byte of the 24 bit address in each record line is used to program the associated RPAGE register on the S12X. The other 16 bits in the address must be in the bank area for that memory. RAM S2 records must have the 16 bit address between $1000 and $1FFF. What this means is that to use an S2 file to program RAM starting at $2000, the S-record will have its start address as $FE1000.
RM
Syntax: RM registerName data8/16value
Name: Register Modify
Description: Updates the specified register with the value provided. Valid register names are: A, B, D, CCH, CCR, SP, PC, X, Y, PP, EP, RP, and GP.
Other Considerations: This command is included for compatibility, as usually one would just reference the register itself to modify its contents.
RP
Syntax: RP data8value
Name: Set RPAGE register value.
Description: This is an S12X command, and sets which 4K page of RAM memory is visible in the CPU memory space from $1000 through $1FFF.
Other Considerations: If the PC register is currently pointed to somewhere in this range, unpredictable results will occur when a TRACE or GO instruction is used. Only valid values will be accepted. uBug12 will reject any other values.
SP
Syntax: SP data16value
Name: Set Stack Pointer register value.
Description: Changes the current value of the Stack Pointer register to data16value.
Other Considerations: If this is changed and the user application is currently in a subroutine, when an RTS is done the program will return to whatever value is on the top of the stack. Also, since the serial monitor keeps all the CPU register values on the stack when it is running, changing the Stack Pointer here will change all the values shown for the other registers. It is best to only let the application program change the SP value.
TERM
Syntax: TERM {terminal-program-path}
Name: Terminal program
Description: Calls the terminal program. By default this is TeraTerm Pro on Windows systems, which you can obtain for free at http://logmett.com/. However you can choose to specify a path to your own terminal program. You can also change the default program called, by going to the Menu bar to: File > Script Paths
Other Considerations: The program will first close the serial connection from uBug12 to the board before calling the terminal program, which is assumed will reopen the same serial connection when it is opened.
TRACE
Syntax: TRACE
Name: Trace Single instruction of user application.
Description: This executes one CPU instruction of the user's application, pointed to by the PC register. Immediately after using TRACE, the Enter key can be hit repeatedly to single step through the subsequent instructions. The mode can be exited by simply entering a different command on the text line.
Other Considerations: Using TRACE clears out all previously set breakpoints. It can not be used to single step through the serial monitor itself. It must not be used to single step through any code that is setting the CPU clock, even if it is to the same value as the serial monitor, as this will cause communication to break between uBug12 and the serial monitor.
VERF
Syntax: VERF {filename}
Name: Verify memory contents with S-record.
Description: This command compares the contents of an S-record file with the current contents of Flash/EEPROM/RAM memory. There is no distinction between the memory types when doing the comparison. S1 and S2 records can both be used.
Other Considerations: If a filename is not given with the command, uBug12 will prompt for one. Execution of this command can take a long time with large S-record files. The output will also be lengthy if the S-record is completely different from memory.
VERSION
Syntax: VERSION
Name: Show current Serial Monitor Version in Flash.
Description: This reads a fixed location in the serial monitor code where the version numbers are recorded. It prints to the screen the version number, along with the date of that version. Sample output is:
Serial Monitor Version 2.3 5/19/9
Other Considerations: None.
VT100
Syntax: VT100 {-E} {baud_rate}
Name: VT100 integrated emulator
Description: Calls the VT100 integrated emulator. An optional baud rate can be specified. If '-E' is part of the command, then typed characters will be locally echoed.
Other Considerations: If the baud rate is specified, the current connection from uBug12 to the board will be reset with that rate, and will then reopen the same serial connection when it starts.
X
Syntax: X data16value
Name: Set X register value.
Description: Changes the current value of the X register to data16value.
Other Considerations: None.
Y
Syntax: Y data16value
Name: Set Y register value.
Description: Changes the current value of the Y register to data16value.
Other Considerations: None.
