BUGS

   1 // This file is part of the Doxygen Developer Manual
   2 /** @page bugs Bug Reporting
   3
   4 Please report bugs by subscribing to the OpenOCD mailing list and
   5 posting a message with your report:
   6
   7         openocd-development@lists.berlios.de
   8
   9 To minimize work for OpenOCD developers, you should try to include
  10 all of the information listed below.  If you feel that some of the
  11 items below are unnecessary for a clear bug report, you may leave
  12 them out; likewise, feel free to include additional information
  13 that may be important.
  14
  15 - Target PCB/board description
  16 - Configuration scripts
  17 - OpenOCD command line
  18 - List of commands issued or GDB operations performed
  19 - Expected result
  20 - Actual result
  21 - Logs using <code>debug_level 3</code> (or with '-d 3' on the command line)
  22 - If the report is for a regression:
  23   - Include logs for both working and broken versions.
  24   - Find the precise version that caused the regression by binary search.
  25     You can use "git bisect" to expedite this binary search:
  26     http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html
  27
  28 If possible, please develop and attach a patch that helps to expose or
  29 solve the reported problem.  See the PATCHES.txt file for information
  30 about that process.
  31
  32 Attach all files directly to your posting.  The mailing list knows to
  33 transform attachments to links, but attachments must be less than 300KB
  34 in total.
  35
  36 @section bugscrashdump Obtaining Crash Backtraces
  37
  38 If OpenOCD is crashing, there are two very effective things you can do to
  39 improve your chances of getting help on the development mailing list.
  40
  41 Try to reproduce the problem using the dummy JTAG interface to allow other developers to replicate
  42 your problem robustly and use GDB to get a trace:@par
  43 @code
  44 % OPENOCDSRC/configure --enable-dummy ...
  45 % openocd -f interface/dummy.cfg -f target/xxx.cfg
  46 => SEGFAULT
  47 % gdb --args openocd ....
  48 (gdb) run
  49 (gdb) bt
  50 => here a stack trace is dumped.
  51 @endcode
  52
  53 @section bugsintreedebug Running and Debugging In-Tree
  54
  55 To run or debug the in-tree executable (not recommended), you must
  56 use libtool to set up the correct shared library paths:
  57 @code
  58   libtool gdb --args openocd ....
  59 @endcode
  60 or the more pedantic (and forward-compatible):
  61 @code
  62   libtool --mode=execute gdb --args openocd ....
  63 @endcode
  64
  65  */
  66 /** @file
  67 This file contains the @ref bugs page.
  68 */