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