D-Bug 12 patches for gdb

This page describes a patch for the m6811-elf version of gdb that allows the use of the D-bug12 based BDM pods. This includes

• MiniDragon+
• DragonBDM
• Technological Arts uBDM12SX Super BDM Pod
• Freescale BDM pod
• My 9S12DP256 micro in POD mode
• A variety of 9S12DP256 development boards that have BDM12 out connectors or hand wired adapters.

This driver is an update of the older D-Bug12 pod driver. That driver did not support chips that had a PPAGE register.

The POD I am using is a MiniDragon+. Expect the same results from a Technological Arts Pod, Motrola 912EVB in pod mode, or from any 9S12DP256 development board with the approriate I/O pins connected to the BDM connector on another target board. Also expect the same results using d-bug12 in EVB mode on a development board without BDM (in which case no flash is availble for developer use, unfortunately).

Reasons for using this particular Pod:

• It is a development board with BDM in and BDM out connectors as well as connectors for every pin on the 9S12 cpu.
• It is among the cheaper pods (the few that are significantly chaper lack supstantial functionality). There is also
• Fungability: It is interchangable with development board. If you have 4 boards, you can have 2 targets with a Pod each or one Pod with 2 targets. As long as you preserve the boot loader, you can even wipe out d-bug12 and use them all as development boards and reload d-bug12 later.
• It can be used for other purposes, with appropriate software:
  • stimulus generator
  • slow logic analyzer
  • canbus simulator
  • SPI simulator
  • simulator for parts of your target system other than processor.
  Either you use a third board for these purposes or you run without BDM while using those features.
• Protocol is documented (d-bug12 manual)
• can be used as rs-232 or USB (with $18 byterunner usb/serial cable).
• RS-232 lends itself to optical isolation
• Works with NoICE debugger
• Works with gdb (sort of)
• works without any host software other than a terminal emulator (you give up symbolic debugging in this case but are otherwise fucntional including line at a time assembler/disassembler.
• Can be used with a PDA/palmtop computer with no special host software.
• full schematics
• based on same CPU as target system, which means you can use the same development tools to customize (unfortunatley motorola/metrowrks doesn't provide d-bug12 source code).
• Maximum speed appears to be 12Mhz bus clock (24Mhz core clock). (1.5x faster than Kevin Ross Pod). With custom software, even 24Mhz might be possible, if it used a routineoptimized for that speed only. Since the Pod speed limits how fast the processor can run (unless you twiddle a bit and make the BDM run at XTAL/2 instead of PLL/2 which may be possible but is not adequately documented).
• It can be powered off the target or you can use the AC adapter and supply power to the target from the BDM board. This is handy if your target board does not have a power connector and is normally powered in an inconvenient way (like a dc-dc converter from a 300V supply with ground connected to -150V (unfortuantely, this is NOT a hypothetical example). Do put a heatsing on the regulator if you do this.
• It has a reset button you can punch to reset pod (not target).
• true 6 pin bdm cable, not a 10 pin with holes plugged, fits in tight spaces on target board.
• breadboard area

• Motorola/metroworks doesn't supply d-bug12 source code.
• Flash download is frightfully slow using only motorola software.
• Lacks plastic enclosure. (www.evbplus.com). Use DragonBDM if you want plastic enclosure.

Download

gdb-ppage-patch-v2 you wil need gdb-6.0.tar.gz and m68hc1x-builder-2.91.tar.gz from the m6811-elf project .

compiling under linux

mkdir /dist
cd /dist
wget http://www.freelabs.com/~whitis//software/gdb_dbug12/gdb-ppage-patch-v2
wget http://m68hc11.serveftp.org/m68hc1x-builder-2.91.tar.gz
wget http://ftp.gnu.org/pub/gnu/gdb/gdb-6.0.tar.gz
cd /usr/local/src
mkdir m6811
cd m6811
mkdir v2.91
cd v2.91
cp /dist/gdb-ppage-patch-v2 .
tar zxvf /dist/gdb-6.0.tar.gz
tar zxvf /dist/m68hc1x-builder-2.91.tar.gz 
cd gdb-6.0
patch -p1 <../m68hc1x-builder-2.91/gdb-6.0-m68hc1x-20040222.diffs 
patch -p1 <../gdb-ppage-patch-v2
./configure --target=m6811-elf --prefix=/usr --program-prefix=m6811-elf- --host=i686-pc-linux-gnu
make
make install

Compiling under cygwin

Cygwin is a set of tools that provide a unix like environment on top of windoze.

mkdir /dist
cd /dist
wget http://www.freelabs.com/~whitis//software/gdb_dbug12/gdb-ppage-patch-v2
wget http://m68hc11.serveftp.org/m68hc1x-builder-2.91.tar.gz
wget http://ftp.gnu.org/pub/gnu/gdb/gdb-6.0.tar.gz
cd /usr/local/src
mkdir m6811
cd m6811
mkdir v2.91
cd v2.91
cp /dist/gdb-ppage-patch-v2 .
tar zxvf /dist/gdb-6.0.tar.gz
tar zxvf /dist/m68hc1x-builder-2.91.tar.gz 
cd gdb-6.0
patch -p1 <../m68hc1x-builder-2.91/gdb-6.0-m68hc1x-20040222.diffs 
patch -p1 <../gdb-ppage-patch-v2
./configure --target=m6811-elf --prefix=/usr --program-prefix=m6811-elf- 
make

make install

#make sure /usr/bin comes before the existing install of m6811 tools in path


# download program using srec9s12 before starting debugger

# note that serial ports under cygwin are /dev/com1, /dev/com2, etc.

# command line: 
m6811-elf-gdb -x gdb-script obj/S12/hi7_load.elf
# or graphical:
ddd --debugger 'm6811-elf-gdb -x gdb-script' obj/S12/hi7_load.elf &

#Note: do not forget to set altclk on pod if your program changes PLL
#frequency: pod altclk 24000

compilation of gdb takes aobut half an hour on my laptop.

Usage

Reading memory properly sets and then restores the PPAGE register.
The disassemble command works for code in bank switched flash.
Setting breakpoints in flash works.

Be aware that there are two versions of the PC register
   $pc   - synthetic 32 bit register that contains the gcc/gdb address
           corresponding to the PPAGE:PC if pointing to external
           flash.
   $ppc  = processor (raw) PC register.  16 bits.
   $page = processor PPAGE register 8 bits.

I will assume you know enough to replace "/dev/ttyUSB0" with the
appropriate port on your system and the name of your program.

The following commands must be given:
   # Load program using srec9s12 first.
   m6811-elf-objcopy --verbose --output-target=srec pintest_load.elf \
      pintest_intermediate.s19
   srec9s12 <pintest_intermediate.s19 >pintest_load.s19
   srec9s12 --send_to_pod --pod_port=/dev/ttyUSB0 \
        --input_file=pintest_load.s19 --srec_bytes=16 --delay_interval=1 \
        --input_map=3
   m6811-elf-gdb pintest_load.elf
   (gdb) set architecture m68hc12   (REQUIRED even if elf file loaded)
   (gdb) set remotebaud 115200
   (gdb) target dbugS12 /dev/ttyUSB0
If gdb has started your program without authorization (see below for why):
   Control-C
   (gdb) pod reset
To start your program (after doing above)
  (gdb) pod reset
  (gdb) pod nobr            // remove any leftover breakpoints on pod
  (gdb) delete              // remove any leftover breakpoints
                                // due to gdb bugs
  (gdb) display/i $pc
  (gdb) break main
  (gdb) run
       (breakpoint reached)
  (gdb) clear main
  (gdb) break emstdio_fputc   
  (gdb) cont
       (breakpoint reached)
  (gdb) print $ccr |= 0x10       // disable interrupts
  (gdb) nexti                    // singlestep cpu instructions
  (gdb) nexti
  (gdb) nexti
  (gdb) nexti
  (gdb0 next                     // singlestep source lines
  (gdb) next
  (gdb) next
 n
You don't have to stop at main as shown above before setting a breakpoint
somewhere eles.

Two commands have been added to gdb: "pod" and "addrcalc9s12".

Some useful commands:
   set debug remote 1   // print commands sent to pod and responses
   set debug remote 0   // turn back off
   info program        // display information about program
   break main          // set breakpoint at main()
   info breakpoints    // show breakpoints
   clear main          // clear breakpoint at main()
   delete 1            // delete breakpoint 1
   delete              // delete all breakpoints
   x/i $pc             // show current instruction
   display/i $pc       // show current instruction each time program stops
   print/x $ppc        // show hardware PC register
   print/x $pc         // show synthetic PC register
   print/x $page       // show PPAGE register
   print/x $d          // show D register
   print/x $x          // show X register
   print/x $y          // show Y register
   print/x $sp         // show SP register
   print $page=0x37    // set ppage register
                          // similarly for other registers
hex 

   x/xh $x             // show 16 bit value pointed to by X register
   x/xw $x             // show 32 bit value pointed to by X register
   x/xb $x             // show 8 bit value pointed to by X register
   x/10xb $x           // show ten 8 bit values pointed to by X register
   x/256xb 0x4000      // show 256 bytes at address 0x4000 (in gcc address
                          space, not banked)
   cont                // start/continue program
   step                // execute next line of source code
   next                // execute next line of source code, but don't
                       // trace into subroutine calls
                       // Note: sometimes fails, see below     
   stepi               // execute next instruction
   nexti               // execute next instruction but don't
                            // trace into subroutine calls
   until              // try this at the bottom of a loop
   list               // show source code near $pc
   where              // stack trace
   info frame         // current stack frame info
   info locals        // show all local variables in current function
   run                // start program over from begining
   print $ccr |= 0x10  // disable interrupts
   print bar           // show value of variable bar
   print bar=123       // set value of variable bar
   print foo(1,2,3)    // run subroutine foo   -- broken
   disass foo          // disassemble subroutine foo
   info target        // displays information on the various memory
                           // sections
   where              // broken
                      // first entry may be ok
   up                 // broken
   down               // broken
   set output-radix 16
   set input-radix 16
New command: "pod":
   pod command         // execute command on pod and print results
                           // up to 1023 characters
   pod reset           // resset target
   pod rd              // display registers in D-bug12 format instead
                           // of gdb format
   pod help            // DON'T DO THIS
   pod ALTCLK 24000    // set alternate BDM frequency 
   pod stop            // stop program
                            // may want to do "x/i $pc" afterwards

New command: addrcalc9s12:
   addrcalc9s12 cpu16 4000        // convert memory address
   addrcalc9s12 banked 3E8000     // convert memory address
   addrcalc9s12 mot_linear F4000  // convert memory address
   addrcalc9s12 offset10000 104000  // convert memory address
   addrcalc9s12 help
For example: 
   (gdb) addrcalc9s12 banked 3E89AB
    CPU16: 49AB
    Banked: 3E89AB
    Motorola Linear:: F89AB
    Offset10000: : 1089AB

Addrcalc9s12 is also availible as a standalone program as part of
the srec9s12 package.

Macro tricks:
    The following commands will result in a register display each time
    the system stops.
       define hook-stop
          pod rd
       end
    for some reason, "info registers" doesn't work in that macro

Pressing carriage return will repeat the last command. This is particularly useful for step, next, stepi, nexti.

Beware of executing any pod commands that may interfere with gdb; for example, tampering with breakpoints could cause trouble. Any command that does not return to a prompt could cause trouble. Commands such as "pod help" that print what look like prompt characters can cause trouble. "pod help" also waits for the user to press return after the first page.

The stepi and step commands usually use the bdm pod trace command so they do not require a breakpoint. However, next and nexti sometimes require a breakpoint, depending on whether they encounter a subroutine call. If you are short on breakpoints, try using step/stepi instead of next/nexti where possible.

Before running gdb

• resetting the pod is recommended Existing breakpoints or the processor being in the run state will cause trouble for gdb.
• make sure you don't have any other programs (such as a terminal emulator) running on the same serial port. Otherise, gdb will either not be able to open the port or it will succeed but the other program will steal messages intended for gdb.
• make sure the pod is running D-bug12 v4.x
• make sure the pod is in BDM mode
• make sure the pod baud rate has been set permanently to 115200
• make sure the pod has been set to the right xtal frequency for the the target system. Also, set ALTCLK if your target uses the PLL.
• if you have two breakpoints set and try to use next/step/etc. program execution will continue past current line.
• load your program into the pod using srec9s12
• running functions on the target using the print command that take string parameters requires that the target code have a malloc function. I.E. print printf("hello, world\r\n");
• there is no exception handling for when the pod gets into funny states: Running when it should be stopped, asking how to handle a target communications failure, stuck mid upload, etc.
• remember that you can run m6811-elf-gdb under gdb. If there is a segfault, use "where" to do a stack dump. Also, you can use the "ulimit -c unlimited" command at the shell prompt to enable core dumps on unix systems which can be examined with the debugger later.
• If you have trouble on a USB to serial adapter, try using a legacy serial port.

Unauthorized execution

When gdb starts, it will automatically begin executing your program without permission. This is a gdb bug if a "to_wait()" function has been defined in the target driver; omitting that function results in many other problems. When gdb starts, it will not only start your program it will wait for it to stop. Hit control-C to abort the wait and then issue a "pod reset" command.

Bootloader issues

The use of a boot loader (either freescales or mine) that allows you to download updates to your software without a BDM pod causes some problems for gdb. Gdb will be confused by the fact that there are two separate programs on the target and that you actually start in a program that it knows nothing about. Avoid the use of the run command in these situatiosn. Instead, do a "pod reset", "break main", and "continue" to start your program.

PLL

If your program switches from PLL to XTAL, it causes problems for the BDM pod. Use a command such as "pod altclk 24000" to tell the pod what the new frequency will be so it can automatically fall back to that frequency when the original one fails. Do not attempt to trace through changes to the PLL/busclock frequency or switching to PLL from XTAL operation. In fact, the BDM may not function for some time after such a change due to the clock frequency not being stable. Set a breakpoint some time after the call to the routine which changes the PLL frequency. Adding a delay loop to the PLL setting function helps insure the frequency is stable before additional code is executed, but if the delay isn't long enough you will still have problems.

Interrupts

Whether you are using the pod directly or with gdb, interrupts can cause problems while debugging. Single steps may jump into the interrupt routine. You may want to modify the contents of the CCR register to disable interrupts: "print ccr |= 0x10". Be aware, however, that turning off interrupts can also cause trouble. For example, if you have serial interrupts disabled, your program will hang waiting for the transmit queue to empty after it has printed enough.

GDB script

# create a gdb initialization script (optional) to save typing
cat >gdb-script <<\...EOF...
set architecture m68hc12
set remotebaud 115200
set remote hardware-breakpoint-limit 2
target dbugS12 /dev/ttyUSB0
pod reset
pod nobr
display/i $pc
info registers
...EOF...
ddd --debugger 'm6811-elf-gdb -x gdb-script' myprogram.elf &
# or
gdb -x gdb-script myprogram.elf

USB serial port issues

As far as I know, nobody makes a USB serial adapter that actually works properly. This is in large part due to deficiencies in the USB communications class specification. Many of the issues have to do with flow control handling. Correct implementation requires offloading such handling to the adapter because the CPU can only communicate with the adapter infrequently. Because of these flaws, a 115200 baud serial port is effectively slowed down to much less than 9600 if flow control is enabled. In the case of GDB, the issue doesn't appear to be flow control (i.e. it happens with flow control disabled) but something similar. Belkin USB serial adapters are INSANELY slow with gdb. A simple next instruction can take 5 to 15 seconds (depending on the computer I tested on). This is not a problem with a byterunner (FTDI chip based) USB to serial adapter . Besides the flow control issues, I have noticed differences in different USB drivers handling of buffering.

Using the unix "stty" command or the windoze "mode" command, make sure that xon/xoff flow control is disabled on the serial port. Gdb appears to use the existing settings.

Revisions

Revision 2 of this patch adds the to_wait() function and related code so that wait is called after various commands. It also adds a wait command you can execute. Wait will wait until D-Bug12 displays the "S>" prompt, meaning your program has stopped. It also prints the current location in a form recognized by ddd and can be used in situations where "ddd" is pointing to the wrong source line (for example if you have modified the program counter using pod commands). It also invalidates the register cache, eliminating stale data.

If you have programs which take 16 bit pointers to a particular memory section in banked memory (for example, all of a particular type of readonly data structure has been moved to the same bank to save space in non-paged flash), don't expect things like

   print *p

    i.e. for page=37, pointer=89ab
    addrcalc9s12 banked 3E89AB
    print *(foo_t *) 0x1089AB

You may use DDD, KDevelop, etc. as a GUI front end to gdb.

These patches were made against the prerelease 2.91 version of m6811-elf-gdb.

srec9s12 is availible from http://www.freelabs.com/~whitis/software/srec9s12

The first parameter is normally passed in the D register, additional paramters are passed on the stack. The return value is also passed in the D register.

Be careful of the limit of 2 hardware breakpoints. In addition to the breakpoints you set, gdb or ddd can set its own breakpoints when you use "nexti", "next", or "continue until here" commands. Do a "pod nobr" command to make sure there aren't any breakpoints already set that gdb doesn't know about. Use the "set remote hardware-breakpoint-limit 2" command.

Note that since the compiler/linker does not properly set the flag which indicates that the code is for an HCS12 cpu, this driver forces that flag to be set.

Support

This driver is not supported.

Bugs

The gdb support for the HCS12 is buggy as is the original driver this modified driver is based on. So, this driver is not by any stretch of the imagination up to my usual robust code standards.

• The driver is not sensitive to exceptional situations in pod communications. Thus messages like "target is running" or "unable to communicate with target" are not handled appropriately. The facility in gdb that allows you to define a new target driver by defining the commands to send to the pod to accomplish various tasks does not provide a facility for handling such errors. You can diagnose and fix many of these problems by using commands such as "set debug remote 1", "wait", and "pod ". For example, if the pod is displaying the "unable to communicate with target" message, you can use "pod 2" to select menu option 2. "pod rd" is a quick way to see what the status of the pod is.
• With "set debug remote 1", the output of some commands such as "info registers" is unreadable because it is mixed with debugging output. Use "pod rd" as a workaround.
• Existing breakpoints on the pod may not be reset when gdb loads. Use "pod nobr".
• Stack frame interprettation is wrong. This affects commands such as "where".
• The "next" command sometimes misbehaves. This is a bug in the HC12 support for gdb, not the BDM pod driver. Situations where it appears to misbehave are using next after the last line of executable code in a function and using next on a line that calls a function. In these situations, GDB can set the breakpoint at the wrong location. In the case of lines that call a function, it appears to set the breakpoint at the begining of the subroutine instead of after the call to the subroutine. These problems can cause your program to run away after a "next" command. Use temporary breakpoints instead. In DDD, right click on the left side of the source line you want to run to and select "continue until here". The "nexti" command might also be affected if it needs to skip over a subroutine call.
• GDB starts your program without your permission (see above).
• Can't load programs. Use srec9s12 for that before starting gdb. This is an exteremely low priority to fix since there is already a means to load programs and it is not trivial to make loading work given the flow control bugs in all known USB to serial adapters and the small receive buffer in D-bug12.
• Printing $a and $b is broken but $d works
• Note that the CPU only supports two hardware breakpoints and you can't set software breakpoints in flash.
• next and nexti may use either trace or breakpoint commands. That means if it needs to jump over a call instruction, it will use a breakpoint. If both hardware breakpoints are in use, it will fail to stop at the appointed line.
• If more than two breakpoints are needed (including those needed by "next" or "nexti" commands), it will fail to set one of the breakpoints without reporting an error.
• can't modify eeprom and you can't call a "far" routine in the target program that does, either. Maybe you could if it was a "near" function.
• can't modify flash. Note that it is not possible to modify flash memory on these CPUs except by whole 512 byte sectors and that aproximately 1K of RAM must be overwritten to download the data to be written and the flash helper routine.
• "where" command only shows current function many times instead of progressing up the stack. "up" has similar problems. This is probably a bug in m68hc11-tdep.c. Perhaps it is getting confused by the extra byte in the return address. It could also be that the target program was compiled -fomit-frame-pointer. Actually, looks like there is a similar problem on a program compiled without omit-frame-pointer.
• may not work on older HCS12 cpus that don't support PPAGE due to forcing elf_flags |= E_M68HC12_BANKS; in m68hc11-tdep.c
• gdb will restore certain breakpoints if you delete them.
• do not use the pod command (i.e. "pod reset") before issuing the target command or gdb will segfault.
• "interrupt" does not work.
• I did find one place where gdb seemed to get hung up on a next instruction. It appears that it was confused by the processor being in the run state. Control-C followed by "pod stop" helped.
• calling a function on the target system using the print command does not work properly. I think GDB is doing a near call to far functions. This is not a driver bug, it is a CPU support bug. Functions with trampolines will probably work if you give the name of the trampoline. m68hc11_push_dummy_call looks suspect. It always pushes 16 bits for the return address. This would be easy to correct if I knew how to tell if the called function was near or far.
• Note that "info registers" will update the register values but doesn't update the $pc register in the current stack context that is used to display the current source line. The new "wait" command, however, will invalidate gdb's notion of the current program counter causing it to be reread.
• Note that direct pod commands such as "pod rd" will not update or invalidate gdb's internal cache. Using the "wait" command will invalidate the cache, however.

Troubleshooting:

• try using control-c to exit any gdb commands that are hung up and try issuing some commands to the pod such as "pod rd", "pod stop", "pod nobr", and "pod reset".
• set debug remote 1
• use a terminal emulator to talk to the pod to see if it is having problems communicating with target
• Make sure you don't have a terminal emulator running concurrently with gdb on the same port
• make sure you have the same version of the program loaded in gdb and the target.
• exit gdb, reset target cpu and pod, and restart gdb
• Make sure you can do what you are trying to do with D-Bug12 by itself. Problems with interrupts, switching to the PLL, serial port communications issues, hung pod, etc. are not gdb specific and are easier to diagnose if you talk to the pod directly.

GDB internals

Here is some info on files related to HCS12 BDM pods.

   remote-bdm12.c  - The high level code for the driver for the 
                     keven ross? bdm12 pod.
   remote-bdm12.h
   bdm12.c         - The low level code to speak the binary protocol
                     for the keven ross bdm12 pod.
   bdm12.h
   m68hc11-rom.c   - The code to support the buffallo HC11 pod and 
                     older versions of D-bug12 that did not support
                     banked memory.   Inappropriately named, should
                     have started with "remote-"
   m68hc11-tdep.c  - The 68HC11/12 CPU specific debugging code
   dbug-rom.c      - The code to support the dbug based pods for
                     the coldfire processor.   Inappropriately named, should
                     have started with "remote-"


   remote.c        - general remote support
   remote-*        - Support for debuggers on many other systems
                     not particularly relevent to 68HC11.c
   *-rom.c         - support for more debuggers that are not
                     particularly relevent.

There is a GDB Internals document but it omits a lot of important information.