re-enabling serial

[clinton/Smoothieware.git] / gcc4mbed / notes / mri.creole

=Monitor for Remote Inspection (MRI) Notes
==Updates
* **1/9/2012:**  Added semihost support for stdin/stdout/stderr.  This allows functions like printf() and scanf() to function.  Their I/O gets redirected over the serial port to the gdb console.
* **2/22/2012:**  Switched to low level UART support to work with any of the 4 serial ports on the mbed.  It also uses auto baud detection so that user just selects their desired baud rate in gdb at runtime.  Also default interrupt priorities to 1 instead of 0, increasing the chance that MRI can debug ISRs.
* **2/29/2012:**  Added notes about GCC4MBED_TYPE environment variable in Usage section.
* **3/3/2012:**  Added support for LocalFileSystem I/O redirection to the current directory on the gdb host computer.
* **3/12/2012:**  Added notes about imprecise nature of data watchpoints.
* **4/29/12012:**  Updated stack and double fault notes since MRI has been updated to lessen these concerns.

==Installation
There are a few things that you need to download and install for MRI:
* Download [[http://mbed.org/media/uploads/simon/mbedmicrocontroller_21164.if]].  Copy this file to your mbed device and then reset it.  This will update the firmware on the interface chip so that the JTAG portion can be disabled.
* Install the MRI repository version of gcc4mbed on your local machine.  There are two ways to do this:
** **Recommended:**  Clone the repository so that you can pull down updates easily.  {{{git clone git@github.com:adamgreen/mri.git}}}
** Go to [[https://github.com/adamgreen/mri/downloads]] and download an archive of the project and decompress it to your local machine.
* Follow the instructions at [[https://github.com/adamgreen/mri#readme]] to allow the MRI project to pull down and install its dependencies.

==Usage
By default the gcc4mbed project builds binaries of a **Release** type which don't include any debugging support.  This will need to be changed to a **Debug** build type to enable the MRI debugger in the binaries.  The GCC4MBED_TYPE environment variable is used to set the build type.

On Windows:
{{{
set GCC4MBED_TYPE=Debug
}}}

On OS X and Linux:
{{{
export GCC4MBED_TYPE=Debug
}}}

Run the BuildShell script found in the root of the MRI project directory.  This script configures your PATH to make sure that the correct version of gdb is used for debugging.

The following is an example of running the HelloWorld sample under gdb on OS X.
{{{
bash-3.2$ export GCC4MBED_TYPE=Debug
bash-3.2$ cd samples/HelloWorld/
bash-3.2$ make clean all deploy
rm -f ../../src/gcc4mbed.o ../../src/syscalls.o  ./main.o
rm -f HelloWorld.hex
rm -f HelloWorld.elf
rm -f HelloWorld.map
rm -f HelloWorld.bin
rm -f HelloWorld.disasm
arm-none-eabi-g++ -O0 -gstabs+3 -mcpu=cortex-m3 -mthumb -mthumb-interwork -fshort-wchar -ffunction-sections -fdata-sections -fpromote-loop-indices -Wall -Wextra -Wimplicit -Wcast-align -Wpointer-arith -Wredundant-decls -Wshadow -Wcast-qual -Wcast-align -fno-exceptions -I./ -I../../external/mbed -I../../external/mbed/LPC1768 -I../../external/FATFileSystem -I../../mri -DTARGET_LPC1768 -DGCC4MBED_DELAYED_STDIO_INIT=1 -c ../../src/gcc4mbed.c -o ../../src/gcc4mbed.o
arm-none-eabi-g++ -O0 -gstabs+3 -mcpu=cortex-m3 -mthumb -mthumb-interwork -fshort-wchar -ffunction-sections -fdata-sections -fpromote-loop-indices -Wall -Wextra -Wimplicit -Wcast-align -Wpointer-arith -Wredundant-decls -Wshadow -Wcast-qual -Wcast-align -fno-exceptions -I./ -I../../external/mbed -I../../external/mbed/LPC1768 -I../../external/FATFileSystem -I../../mri -DTARGET_LPC1768 -DGCC4MBED_DELAYED_STDIO_INIT=1 -c ../../src/syscalls.c -o ../../src/syscalls.o
arm-none-eabi-g++ -O0 -gstabs+3 -mcpu=cortex-m3 -mthumb -mthumb-interwork -fshort-wchar -ffunction-sections -fdata-sections -fpromote-loop-indices -Wall -Wextra -Wimplicit -Wcast-align -Wpointer-arith -Wredundant-decls -Wshadow -Wcast-qual -Wcast-align -fno-exceptions -I./ -I../../external/mbed -I../../external/mbed/LPC1768 -I../../external/FATFileSystem -I../../mri -DTARGET_LPC1768 -DGCC4MBED_DELAYED_STDIO_INIT=1 -c main.cpp -o main.o
arm-none-eabi-g++ -mcpu=cortex-m3 -mthumb -O0 -Wl,-Map=HelloWorld.map,--cref,--gc-sections,--no-wchar-size-warning -T../../build/mbed.ld -L ../../external/gcc/LPC1768 ../../src/gcc4mbed.o ../../src/syscalls.o  ./main.o  ../../mri/mri.ar ../../external/mbed/LPC1768/mbed.ar ../../external/mbed/LPC1768/capi.ar  -o HelloWorld.elf
arm-none-eabi-size HelloWorld.elf
   text	   data	    bss	    dec	    hex	filename
  73335	   1500	   1084	  75919	  1288f	HelloWorld.elf
arm-none-eabi-objcopy -R .stack -O ihex HelloWorld.elf HelloWorld.hex
arm-none-eabi-objcopy -O binary HelloWorld.elf HelloWorld.bin
arm-none-eabi-objdump -d HelloWorld.elf >HelloWorld.disasm
cp HelloWorld.bin /Volumes/MBED/

***RESET MBED DEVICE***

bash-3.2$ arm-none-eabi-gdb HelloWorld.elf --baud 115200 -ex "set target-charset ASCII"
GNU gdb (Sourcery G++ Lite 2011.03-42) 7.2.50.20100908-cvs
Copyright (C) 2010 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-apple-darwin10.8.0 --target=arm-none-eabi".
For bug reporting instructions, please see:
<https://support.codesourcery.com/GNUToolchain/>...
Reading symbols from /depots/mri/samples/HelloWorld/HelloWorld.elf...done.
(gdb) target remote /dev/tty.usbmodem412
Remote debugging using /dev/tty.usbmodem412
__main () at ../../src/gcc4mbed.c:96
96	    __debugbreak();
(gdb) break main
Breakpoint 1 at 0x73c: file main.cpp, line 26.
(gdb) c
Continuing.
Note: automatically using hardware breakpoints for read-only addresses.

Breakpoint 1, main () at main.cpp:26
26	        myled = 1;
(gdb) bt
#0  main () at main.cpp:26
(gdb) 
}}}

==Important Notes
There are a few things to note about the MRI debug monitor functionality:
* LocalFileSystem I/O is redirected to the current directory on the gdb host computer when using MRI.  This introduces a few limitations:
** Slower performance since I/O is being redirected over the serial port to the gdb host computer.
** No directory enumeration support (opendir,readdir,closedir).  Calling such functions for the LocalFileSystem while running under MRI will result in stops like.
\\{{{Program received signal SIGTRAP, Trace/breakpoint trap.}}}\\{{{0x00011a00 in mbed::LocalDirHandle::readdir() ()}}}\\
* The monitor and associated UART exception handler run at priority level 0.  This means that the debugger can't preempt another interrupt service routine that is also running at priority level 0.  By default, the mbed SDK allows its ISRs to use the default priority level of 0.  MRI switches this default priority level to 1.  If you have an ISR that must be run at priority level 0 then you will need to increase its priority level manually.\\ \\{{{NVIC_SetPriority(SysTick_IRQn, 0);}}}\\ \\
* The monitor requires the use of a UART to communicate with gdb and it defaults to using the USB based serial connection.  This means you will end up with a conflict if your firmware also sends data to the PC over the default USB based serial port on the mbed.  Your makefile can be used to override the mbed serial pins used by MRI.  For example to switch to the UART on pins 9 and 10 of the mbed, you could add this line to your makefile:\\ \\{{{MRI_UART=MRI_UART_MBED_P9_P10}}}\\ \\
You can find all of the supported MRI_UART_* selections in the public mri/mri.h source file.
* Data watchpoints on the LPC1768 are imprecise.  This means that the line of code on which the debugger stops may be a line or two after the actual line of code which accessed the watched variable.

==Known Issues
Known issues that will be investigated for future fixes include:
* On Mac OS X, I see a hang in gdb when issuing the {{{target remote}}} command.  The workaround is to disconnect the mbed device from the Mac by unplugging the USB cable and then reconnecting it to force reenumeration.
** It may be possible to workaround this issue in the gdb source code as well and I am currently dogfooding such a build of arm-none-eabi-gdb on my Mac.  Please contact me if you would like to help test this fix on your Mac.
* Can't dump objects from the mbed SDK.  This includes objects of class types such as DigitialIn, InterruptIn, AnalogOut, etc. and even user created classes which derive from these classes.
* User must be careful when debugging hard faults.  Attempting to read/write from/to invalid memory locations could cause a double fault hang.
** MRI does tell gdb which address ranges are invalid but it is still possible to attempt a write to a read-only peripheral memory mapped register and this could lead to a double fault.
* While MRI has been shown to work on some other LPC17xx based development systems, this isn't currently a supported scenario.  However, as long as the device doesn't have a JTAG debugger attached and you can connect the PC to one of the UARTs on the device, it should work.


==Hit a Problem!
GDB allows for all of the data sent between your PC and the remote MRI target to be captured to a log file.  If you enter the following command in GDB before issuing the "target remote" command then everything for your session will be logged to a file called mri.log in the current directory where GDB was launched:
{{{
set remotelogfile mri.log
}}}

Describe as clearly as possible what you were doing when you encountered the problem and then e-mail me this description along with a log file captured as described above.  I have an electronic mail account at yahoo.com.  The alias I use there is adamgrym.