undodb-gdb
Section: User Commands (1)
Index
NAME
undodb-gdb - reversible debugging accelerator for gdb.
SYNOPSIS
undodb-options undodb-options gdb-parameters debuggee
DESCRIPTION
undodb-gdb is a wrapper for gdb (the GNU debugger) that connects it to the UndoDB reverse execution engine. It effectively replaces the `process record' feature of gdb 7 with a highly-optimized implementation that records with a typical slow-down of less than 2x, and similarly efficient use of memory. (The `legacy UI' can also be used to allow operation with older versions of gdb.) undodb-gdb is used as though it were a drop-in replacement for gdb (it works by wrapping the locally installed gdb).
For the most part undodb-gdb is used exactly as one would use gdb, except that recording performance is improved by several orders of magnitude, and that there are a few new commands available. undodb-gdb may be passed the same command-line options as gdb, plus some additional options (see below).
TIME AND UNDODB
undodb-gdb keeps track of time using `simulated nanoseconds'. These units approximate nanoseconds if the program were to be run outside of the debugger. These units are somewhat abstract - they do not model real-life nanoseconds exactly.
Programs running under the control of undodb-gdb run in one of two modes. When a program is first executed, it is executed in record mode This means that the program is being run "live", and this is the first time that a given simulated nanosecond has elapsed. In record mode, the program's interactions with the system are recorded in an event log. When the user winds the program backwards in time (e.g. with the reverse-continue or reverse-next commands), it enters replay mode where a given simulated nanosecond elapses for a second or subsequent time. A program may be executing in replay mode either forwards or backwards (record mode execution is necessarily forwards). There are no interactions with the system in replay mode. Events are replayed from the event log to ensure that in replay mode the program follows exactly the same path as it did in record mode.
For example, if the first thing the user does at the prompt after starting undodb-gdb is to issue the `run' command, the program will be started in record mode. If after two seconds the user interrupts the program and steps backwards two instructions, then the program will be in replay mode. If the user steps forward one instruction, the program is still in replay mode. If the user steps forward another instruction, the program switches back to record mode. The program will remain in record mode until the user moves backwards in time again.
Although there is no correlation between wall-time and simulated nanoseconds, the measurement of time is perfectly repeatable - if an event (such as the execution of a particular instruction or reception of a signal) happened at time X in record mode, then that event will always happen at precisely time X in replay mode.
There can sometimes be a significant difference in the time programs take to execute in record and replay modes. Generally, when in record mode, a program will run slower than in "real life" (exactly how much slower depends varies a lot between programs, though a slow-down of around 70% is typical for CPU-intensive applications). When running forwards in replay mode, a program can run considerably faster than this, and sometimes even faster than it would run in "real life". Running backwards will generally be around ten times slower than running forwards in replay mode.
COMMANDS
When using the undodb-gdb enhanced UI (the default), the following gdb commands are reimplemented:
- reverse-continue
- Run backwards until a breakpoint or watchpoint is hit. A backwards equivalent of gdb's continue command.
- reverse-step
- Step backwards out of the current source line. A backwards equivalent of gdb's step command.
- reverse-next
- Step backwards out of the current source line, stepping over function calls. A backwards equivalent of gdb's next command.
- reverse-stepi
- Step backwards one instruction. A backwards equivalent of gdb's stepi command.
- reverse-nexti
- Step backwards out of the current instruction, stepping over function calls. A backwards equivalent of gdb's nexti command.
- reverse-finish
- Run backwards to the call-site of the current function. A backwards equivalent of gdb's finish command.
- reverse-until
- Step backwards out of current source line, stepping over function calls and local loops, but stopping if the program exits the current function. A backwards equivalent of gdb's until command. However, this is not exactly analogous to gdb's until It cannot be given arguments (use undodb-goto-n instead).
If there is no detailed debug line information available, the line-oriented commands reverse-next reverse-step and reverse-until will output a warning and behave like reverse-stepi
There are also some newly-provided commands, most of which are used to jump around in time arbitrarily:
- undodb-get-n
- Output the current time, in simulated nanoseconds.
- undodb-goto-n <number>
- Wind forwards or backwards to the specified time, in simulated nanoseconds. Unlike most UndoDB commands, the length of time this command takes to execute does not depend on how far in time the debuggee is to be moved. e.g. undodb-goto-n 1 is usually almost instant, even if done from record mode.
- undodb-goto-n +<number> | -<number>
- Wind forward/backward the specified number of simulated nanoseconds.
- undodb-get-time
- Print a precise indication of the current time. Every executed instruction will return a unique value.
- undodb-goto-time <t>
- Go to a time t output by an earlier call to undodb-get-time
- undodb-get-bookmark
- Returns a small integer which can be used as an easily-remembered bookmark for the debuggee's current point in its execution history.
- undodb-goto-bookmark <B>
- Restores the debuggee to the point in its execution history where the undodb-get-bookmark command returned bookmark B
- undodb-goto-record-mode
- Return the debuggee to the latest point in its recorded execution history - i.e. to record mode.
- undodb-enable-record
-
Switch from normal debugging to full reversible debugging. That is, begin recording execution history so that it may be subsequently replayed.
Breakpoints are not active when the above commands other than reverse-continue are executed. For example, using undodb-goto-n <big number> to move forwards will not hit a breakpoint where using continue would.
There are also some commands for controlling how UndoDB uses memory:
- undodb-set-max-event-log-size <size> [K|M]
- UndoDB's snapshot-and-replay technique means relatively little event log is required, but non-deterministic events must still be stored in the log. All of the program's input (e.g. from disk or network) must be stored in the log, as must all other non-deterministic events such as thread switches, asynchronous signals or shared memory accesses. Memory is allocated dynamically for the event log as required, but this option can be used to limit how big the event log will grow to. Note that depending on system resources, less than <size> may be available (it is not advised to allow UndoDB to consume all the system's memory, lest the Linux "Out Of Memory Killer" kick in). See also the --undodb-event-log-max command-line option.
- undodb-show-max-event-log-size
- Display the currently-configured maximum event log size.
- undodb-set-event-log-mode circular | straight
- If `circular' then a circular buffer is used to store events. This means that if the debuggee runs for a long time, it may not be possible to go back to the beginning of the program. The default is `straight'. See also the --undodb-set-event-log-mode command-line option.
- undodb-set-shared-mem-mode <0 | 0 | 1 | 2 | 3
- Control UndoDB's behavior with shared memory. See the --undodb-shared-mem-mode command-line option for details of what the modes mean.
LEGACY UI
UndoDB can also be used ``legacy UI mode'' in order to be used with older versions of gdb (versions before 7.0). In the legacy UI mode, there is no native gdb interface for reversible debugging. The command-set is different in legacy UI mode - rather than commands being prefixed with `undodb-' all commands are prefixed with `b'. Also, in legacy UI mode, the gdb commands info threads and thread N are unavailable; use binfo threads and bthread N respectively instead. In legacy UI mode the bset command must be used instead of set when changing debuggee state in record mode (in both legacy and enhanced UI modes it is possible to change program state in record mode only).
SYSTEM INTERACTION
Any side-effects a program has on the rest of the system do not occur when in replay mode. For example, if a program issues a printf, then when the printf is encountered in record mode, text is displayed on stdout. However, when the printf is replayed, no output is generated. As another example, if a file is unlinked, in record mode the file will be really unlinked from the file-system; when in replay mode, the program will have no interaction with the operating system. Instead, UndoDB will return in replay mode whatever result the unlink system-call returned to the debuggee when it executed in record mode.
UndoDB creates many extra processes, usually around thirty in normal operation, but many more in certain pathological situations. These will appear in the output of the ps command. (See the documentation of the --undodb-snapshots command-line option below for more on this.)
OPTIONS
undodb-gdb adds various command-line options to gdb:
- --undodb-ui enhanced | legacy | auto
- The default is enhanced, which gives a significantly improved user experience, but requires gdb version 7 or later; legacy mode can be used with gdb version 6.0 or greater. Auto mode will use the enhanced UI with a gdb that is capable of supporting it, or legacy UI mode otherwise.
- --undodb-defer-recording
- By default recording starts as soon as undodb-gdb starts executing the debuggee. This option changes that default, and recording is not started until the user enters the undodb-enable-record command.
- --undodb-event-log-max <size>[M|K]
- Maximum size of the event log UndoDB will use. The maximum may be modified at run-time using the undodb-set-event-log-size command (see that command's documentation above for more details). To find the default heap size, specify a negative number - the heap size will be displayed by UndoDB when your program is started. Append `M' or `K' to specify the heapsize in Megabytes or Kilobytes respectively.
- --undodb-event-log-mode straight | circular
- Controls what happens when the maximum event log is consumed or no more memory may be allocated from the system in order to grow the event log. If `circular' then a circular buffer is used to store events. This means that if the debuggee runs for a long time, it may not be possible to go back to the beginning. The default is `straight'. This may be toggled at run-time using the undodb-set-event-log-mode command. If the maximum event log size is reached, UndoDB will stop execution of the debuggee and display a message explaining that the event log is full. At that point the maximum event log size can be increased or the event log set to circular, and then execution of the debuggee can be continued.
- --undodb-autotrace <glob>
- The program specified (by --args or the last argument if there is no --args) is not debugged directly, but rather any subprocess of that program whose executable name matches <glob> will be debugged. This is useful for debugging a program that is wrapped by a series of scripts or other executables. e.g. undodb-gdb --undodb-autotrace "*firefox-bin" --args firefox www.google.com.
- --undodb-autotrace-terminal xterm|screen|none
- Starts the autotrace undodb-gdb session in the described terminal, or if <none>, undodb-gdb's output is appended to the file named undodb_autotrace_log.txt. The default is 'xterm'.
- --undodb-autorun
- When the debugger either attaches to or starts a debuggee that the debuggee is continued automatically. This is particularly useful in combination with --undodb-autotrace)
- --undodb-unknown-syscall-mode 0|1
- By default when the debuggee attempts to execute a system-call that is not known by UndoDB, then a special snapshot is taken (this is referred to as an unoptimized system call). If 1 is passed as this option, then on kernel kernel of 2.6.64 or later is used then UndoDB automatically detects the results of the system call. This can lead to significantly improved performance for applications that make large numbers of unknown system calls (including private ioctls).
- --undodb-gdb <gdb>
- Specifies the gdb executable that undodb-gdb should wrap. The default is simply `gdb'.
- --undodb-shared-mem-mode <value>
- Control what happens when debuggee attempts to map shared memory (i.e. use of mmap() with the MAP_SHARED flag or use of shmat()).
-
- <value> = 0
- Execution of the debuggee is halted. (The mode may then be adjusted.)
- <value> < 0
- Return error <value> from the system call.
- <value> = 1
- Use unshared memory in place of the shared memory. In practice this means the MAP_SHARED flag to mmap() is ignored and that shmat() is turned into an equivalent but unshared mmap(). Also, when attaching to a process any shared maps are remapped as unshared.
- <value> = 2
- Use the MMU to trap and record all shared-memory access. This can be quite slow if the debuggee makes very frequent accesses to shared memory.
- <value> = 3
- Use UndoDB's optimized binary translation based shared memory support. Even debuggee's which make very heavy use of shared memory should perform well with this mode.
The default is the highest value supported by your license. There is usually no reason to change this setting, although if your license does not support mode 3 then mode 1 may perform better than mode 2, but of course may affect the operation of your debuggee.
May be modified at run-time using the undodb-set-shared-mem-mode command.
- --undodb-snapshots <n>
- Rather than recording in the log everything the debuggee does, UndoDB uses a snapshot-and-replay technique. This option is a hint to UndoDB as to how many snapshots to preserve. Snapshots are implemented using "fork", meaning one process is used per snapshot. Too many snapshots leads to poor performance due to pressure on system resources, and too few can mean that backwards operations take a long time to complete. Generally UndoDB will attempt to keep no more than <n> snapshots, but more may be required in some situations. The default value is 35.
- --undodb-instr-heapsize <size>[M|K]
- UndoDB uses dynamic binary translation in order to instrument the running debuggee. This option controls the size of the translation cache. The default is 16MB, which will allow approximately 1.6MB of x86 native code to be stored. Programs with a very large working set of instructions may benefit from a larger value. There is no way to change this value at run-time.
- --undodb-instr-reclaim yes | no
- If `yes' then when the translation cache is full not recently used translations are ejected. If `no', execution of the debuggee is haulted if the translation cache becomes full. The default is `yes'. There is no way to change this value at run-time, but there is usually no need to change from the default.
- --undodb-keyfile <path>
- Not usually required. Specifies the path of the UndoDB keyfile. The default is a file named `key' in the undodb directory.
- --undodb-heapsize <size>[M|K]
- Size of UndoDB's fixed internal heap. Specifying a negative number will show the default heap size when your program is started. UndoDB is designed never to need more internal heap than the default, so there is usually no need to use this option.
- --undodb-x32
- When using the enhanced UI (the default) this option is redundant. If using the legacy UI, this option must be passed when debugging an i386 (i.e. 32-bit) executable on an x86_64 host.
- --undodb-checkupdates yes | auto | no | never | ask
- Controls whether undodb-gdb will check for a newer release at start-up. If `auto' or `never', the setting is used by default next time. The default is `auto', which checks once per day.
- --undodb-optimize-shlibs
- Speeds up programs that use large shared libraries. However, this optimization assumes that shared libraries the debuggee program uses do not change during the lifetime of the program. If the shared libraries are updated during the debugging session, the results are undefined.
- --undodb-remote-exe exe
- exe is the pathname of the gdb remote protocol server (i.e. gdbserver replacement) to be used by enhanced mode. If this option is not passed the server executable from the directory in which contains undodb-gdb itself will be used.
- --undodb-keyfile <path>
-
Gives a path to the UndoDB keyfile. By default UndoDB will search in the current working directory, in the directory in which it's installed and in the user's home directory for a file called `key'.
- --undodb-keyserver <host>:<port>
- UndoDB can be instructed to use a keyserver to provide `floating licenses'. This is usually encoded in the local keyfile, but the keyserver's hostname and port can be overridden using this option.
- --undodb-errorbacktrace
-
undodb-gdb itself is a Python program. If this option is passed, then on encountering a Python exception a back-trace of the exception will be displayed on stderr.
USE WITH GRAPHICAL FRONTENDS
undodb-gdb is a drop-in replacement for gdb, so can be used with most graphical frontends that use gdb (e.g. Eclipse, DDD, Emacs). e.g. to make ddd use undodb-gdb run ddd with `--debugger undodb-gdb'. undodb-gdb - specific commands must be entered manually in ddd's console window.
FILES
- ~/.undodb
- Used to store some preferences which are chosen by the user at run-time. Not human-readable.
- ~/.undodb-gdb.defaults
-
Default configuration settings can be overridden by placing them in this file. The options must be stored in the file separated by new-lines or white-space, exactly as passed on the command line. e.g. the file might contain:
--undodb-event-log-mode circular
--undodb-event-log-max 1024M
- in order to default to a 1 gigabyte circular event log. Command-line options take precedence over those in this file.
EXAMPLES
undodb-gdb myprogram
ddd --debugger undodb-gdb myprogram
SUPPORTED SYSTEMS
undodb-gdb is supported (i.e. tested) on up-to-date installations of the following systems:
- Red Hat Enterprise Linux 4, 5 and 6.
- SuSE Linux Enterprise Server 10 and 11.
- Fedora 8, 9, 10, 11, 12, 13, 14, 15, 16 and 17.
- OpenSuse 10 and 11.
- Ubuntu 6.06, 8.10, 9.04, 9.10, 10.04, 10.10, 11.04, 11.10 and 12.04
- Debian Etch, Lenny, Sid and Squeeze.
undodb-gdb will run on most other reasonably modern Linux distributions and versions.
STARTUP
Cm Checking for updates undodb-gdb will check whether a newer version is available on undo-software.com's server. This checking can be controlled with the --undodb-checkupdates option.
LIMITATIONS
- OS/CPU
- UndoDB works on Linux on x86 CPUs (32-bit and 64-bit). Programs which use the Intel AMD 3DNow! and other extended AMD instructions are not supported. (Programs that use SSE, SSE2, SSE3 and SSE4 are supported.)
- Old kernels
- UndoDB is not supported on 2.4 or older kernels.
- Exec
- UndoDB does not support the execve system call, as used by libc's execl() execlp() , execle() , execv() , execvp() and execve() functions. The debuggee will be stopped if it attempts to issue such a system call.
- Disk usage
- Depending on the debuggee, UndoDB can create large temporary files within /tmp
- Attaching to existing debuggees with --pid
- UndoDB requires ld and objcopy to be present when attaching to an existing debuggee; they are usually already installed on Linux development machines.
- SIGKILL
- UndoDB cannot continue if the debuggee is terminated by SIGKILL. Instead, the debugging session is closed immediately as with a conventional debugger.
- Use of gdb user defined command-hooks
- undodb-gdb uses `user defined commands' to hook most of gdb's standard commands, so these hooks are not available to the user.
- Pagination not supported in UndoDB commands
- Pagination on UndoDB commands is disabled due to the way gdb interfaces with UndoDB itself. Pagination still works with gdb commands, however.
Consult undodb-limits(1) for other, rather more obscure limitations of UndoDB
BUGS
- Use in a Midnight Commander terminal
- undodb-gdb has problems when run from Midnight Commander's terminal - it appears to go into the background.
- The first stepi after a system call returns may appear to do nothing.
- Subsequent stepi's will work as expected, however.
If you come across other problems, please email the details to support@undo-software.com Please include as much information as you can, for example the output from uname -a and as much of the output from undodb-gdb as possible.
SEE ALSO
gdb(1)
ddd(1)
COPYRIGHT
undodb-gdb and UndoDB are Copyright (c) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Undo Ltd.
Index
- NAME
- SYNOPSIS
- DESCRIPTION
- TIME AND UNDODB
- COMMANDS
- LEGACY UI
- SYSTEM INTERACTION
- OPTIONS
- USE WITH GRAPHICAL FRONTENDS
- FILES
- EXAMPLES
- SUPPORTED SYSTEMS
- STARTUP
- LIMITATIONS
- BUGS
- SEE ALSO
- COPYRIGHT
This document was created by man2html, using the manual pages.
Time: 13:32:14 GMT, May 30, 2012