| Index: gdb/doc/gdb.info-5
|
| diff --git a/gdb/doc/gdb.info-5 b/gdb/doc/gdb.info-5
|
| index bd337224a3899346bc33a9d2f6638bd09a530273..3d1b32cbd746a0dce26c44ea4b430dea05a794a3 100644
|
| --- a/gdb/doc/gdb.info-5
|
| +++ b/gdb/doc/gdb.info-5
|
| @@ -1,13 +1,12 @@
|
| -This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
|
| +This is gdb.info, produced by makeinfo version 4.13 from ./gdb.texinfo.
|
|
|
| INFO-DIR-SECTION Software development
|
| START-INFO-DIR-ENTRY
|
| * Gdb: (gdb). The GNU debugger.
|
| +* gdbserver: (gdb) Server. The GNU debugging server.
|
| END-INFO-DIR-ENTRY
|
|
|
| - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
| -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
| -2010 2011, 2012 Free Software Foundation, Inc.
|
| + Copyright (C) 1988-2013 Free Software Foundation, Inc.
|
|
|
| Permission is granted to copy, distribute and/or modify this document
|
| under the terms of the GNU Free Documentation License, Version 1.3 or
|
| @@ -23,11 +22,9 @@ developing GNU and promoting software freedom."
|
| This file documents the GNU debugger GDB.
|
|
|
| This is the Tenth Edition, of `Debugging with GDB: the GNU
|
| -Source-Level Debugger' for GDB (GDB) Version 7.5.1.
|
| +Source-Level Debugger' for GDB (GDB) Version 7.6.50.20131211-cvs.
|
|
|
| - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
| -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
|
| -2010 2011, 2012 Free Software Foundation, Inc.
|
| + Copyright (C) 1988-2013 Free Software Foundation, Inc.
|
|
|
| Permission is granted to copy, distribute and/or modify this document
|
| under the terms of the GNU Free Documentation License, Version 1.3 or
|
| @@ -41,7137 +38,8043 @@ this GNU Manual. Buying copies from GNU Press supports the FSF in
|
| developing GNU and promoting software freedom."
|
|
|
|
|
| -File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
|
| +File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Ada Exceptions Commands, Up: GDB/MI
|
|
|
| -C.2 Invoking the GDB `configure' Script
|
| -=======================================
|
| +27.23 Miscellaneous GDB/MI Commands
|
| +===================================
|
|
|
| -GDB comes with a `configure' script that automates the process of
|
| -preparing GDB for installation; you can then use `make' to build the
|
| -`gdb' program.
|
| +The `-gdb-exit' Command
|
| +-----------------------
|
|
|
| - The GDB distribution includes all the source code you need for GDB
|
| -in a single directory, whose name is usually composed by appending the
|
| -version number to `gdb'.
|
| +Synopsis
|
| +........
|
|
|
| - For example, the GDB version 7.5.1 distribution is in the
|
| -`gdb-7.5.1' directory. That directory contains:
|
| + -gdb-exit
|
|
|
| -`gdb-7.5.1/configure (and supporting files)'
|
| - script for configuring GDB and all its supporting libraries
|
| + Exit GDB immediately.
|
|
|
| -`gdb-7.5.1/gdb'
|
| - the source specific to GDB itself
|
| +GDB Command
|
| +...........
|
|
|
| -`gdb-7.5.1/bfd'
|
| - source for the Binary File Descriptor library
|
| +Approximately corresponds to `quit'.
|
|
|
| -`gdb-7.5.1/include'
|
| - GNU include files
|
| +Example
|
| +.......
|
|
|
| -`gdb-7.5.1/libiberty'
|
| - source for the `-liberty' free software library
|
| + (gdb)
|
| + -gdb-exit
|
| + ^exit
|
|
|
| -`gdb-7.5.1/opcodes'
|
| - source for the library of opcode tables and disassemblers
|
| +The `-gdb-set' Command
|
| +----------------------
|
|
|
| -`gdb-7.5.1/readline'
|
| - source for the GNU command-line interface
|
| +Synopsis
|
| +........
|
|
|
| -`gdb-7.5.1/glob'
|
| - source for the GNU filename pattern-matching subroutine
|
| + -gdb-set
|
|
|
| -`gdb-7.5.1/mmalloc'
|
| - source for the GNU memory-mapped malloc package
|
| + Set an internal GDB variable.
|
|
|
| - The simplest way to configure and build GDB is to run `configure'
|
| -from the `gdb-VERSION-NUMBER' source directory, which in this example
|
| -is the `gdb-7.5.1' directory.
|
| +GDB Command
|
| +...........
|
|
|
| - First switch to the `gdb-VERSION-NUMBER' source directory if you are
|
| -not already in it; then run `configure'. Pass the identifier for the
|
| -platform on which GDB will run as an argument.
|
| +The corresponding GDB command is `set'.
|
|
|
| - For example:
|
| +Example
|
| +.......
|
|
|
| - cd gdb-7.5.1
|
| - ./configure HOST
|
| - make
|
| + (gdb)
|
| + -gdb-set $foo=3
|
| + ^done
|
| + (gdb)
|
|
|
| -where HOST is an identifier such as `sun4' or `decstation', that
|
| -identifies the platform where GDB will run. (You can often leave off
|
| -HOST; `configure' tries to guess the correct value by examining your
|
| -system.)
|
| +The `-gdb-show' Command
|
| +-----------------------
|
|
|
| - Running `configure HOST' and then running `make' builds the `bfd',
|
| -`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
|
| -The configured source files, and the binaries, are left in the
|
| -corresponding source directories.
|
| +Synopsis
|
| +........
|
|
|
| - `configure' is a Bourne-shell (`/bin/sh') script; if your system
|
| -does not recognize this automatically when you run a different shell,
|
| -you may need to run `sh' on it explicitly:
|
| + -gdb-show
|
|
|
| - sh configure HOST
|
| + Show the current value of a GDB variable.
|
|
|
| - If you run `configure' from a directory that contains source
|
| -directories for multiple libraries or programs, such as the `gdb-7.5.1'
|
| -source directory for version 7.5.1, `configure' creates configuration
|
| -files for every directory level underneath (unless you tell it not to,
|
| -with the `--norecursion' option).
|
| +GDB Command
|
| +...........
|
|
|
| - You should run the `configure' script from the top directory in the
|
| -source tree, the `gdb-VERSION-NUMBER' directory. If you run
|
| -`configure' from one of the subdirectories, you will configure only
|
| -that subdirectory. That is usually not what you want. In particular,
|
| -if you run the first `configure' from the `gdb' subdirectory of the
|
| -`gdb-VERSION-NUMBER' directory, you will omit the configuration of
|
| -`bfd', `readline', and other sibling directories of the `gdb'
|
| -subdirectory. This leads to build errors about missing include files
|
| -such as `bfd/bfd.h'.
|
| +The corresponding GDB command is `show'.
|
|
|
| - You can install `gdb' anywhere; it has no hardwired paths. However,
|
| -you should make sure that the shell on your path (named by the `SHELL'
|
| -environment variable) is publicly readable. Remember that GDB uses the
|
| -shell to start your program--some systems refuse to let GDB debug child
|
| -processes whose programs are not readable.
|
| +Example
|
| +.......
|
|
|
| -
|
| -File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
|
| + (gdb)
|
| + -gdb-show annotate
|
| + ^done,value="0"
|
| + (gdb)
|
|
|
| -C.3 Compiling GDB in Another Directory
|
| -======================================
|
| +The `-gdb-version' Command
|
| +--------------------------
|
|
|
| -If you want to run GDB versions for several host or target machines,
|
| -you need a different `gdb' compiled for each combination of host and
|
| -target. `configure' is designed to make this easy by allowing you to
|
| -generate each configuration in a separate subdirectory, rather than in
|
| -the source directory. If your `make' program handles the `VPATH'
|
| -feature (GNU `make' does), running `make' in each of these directories
|
| -builds the `gdb' program specified there.
|
| +Synopsis
|
| +........
|
|
|
| - To build `gdb' in a separate directory, run `configure' with the
|
| -`--srcdir' option to specify where to find the source. (You also need
|
| -to specify a path to find `configure' itself from your working
|
| -directory. If the path to `configure' would be the same as the
|
| -argument to `--srcdir', you can leave out the `--srcdir' option; it is
|
| -assumed.)
|
| + -gdb-version
|
|
|
| - For example, with version 7.5.1, you can build GDB in a separate
|
| -directory for a Sun 4 like this:
|
| + Show version information for GDB. Used mostly in testing.
|
|
|
| - cd gdb-7.5.1
|
| - mkdir ../gdb-sun4
|
| - cd ../gdb-sun4
|
| - ../gdb-7.5.1/configure sun4
|
| - make
|
| +GDB Command
|
| +...........
|
|
|
| - When `configure' builds a configuration using a remote source
|
| -directory, it creates a tree for the binaries with the same structure
|
| -(and using the same names) as the tree under the source directory. In
|
| -the example, you'd find the Sun 4 library `libiberty.a' in the
|
| -directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
|
| +The GDB equivalent is `show version'. GDB by default shows this
|
| +information when you start an interactive session.
|
|
|
| - Make sure that your path to the `configure' script has just one
|
| -instance of `gdb' in it. If your path to `configure' looks like
|
| -`../gdb-7.5.1/gdb/configure', you are configuring only one subdirectory
|
| -of GDB, not the whole package. This leads to build errors about
|
| -missing include files such as `bfd/bfd.h'.
|
| +Example
|
| +.......
|
|
|
| - One popular reason to build several GDB configurations in separate
|
| -directories is to configure GDB for cross-compiling (where GDB runs on
|
| -one machine--the "host"--while debugging programs that run on another
|
| -machine--the "target"). You specify a cross-debugging target by giving
|
| -the `--target=TARGET' option to `configure'.
|
| + (gdb)
|
| + -gdb-version
|
| + ~GNU gdb 5.2.1
|
| + ~Copyright 2000 Free Software Foundation, Inc.
|
| + ~GDB is free software, covered by the GNU General Public License, and
|
| + ~you are welcome to change it and/or distribute copies of it under
|
| + ~ certain conditions.
|
| + ~Type "show copying" to see the conditions.
|
| + ~There is absolutely no warranty for GDB. Type "show warranty" for
|
| + ~ details.
|
| + ~This GDB was configured as
|
| + "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
|
| + ^done
|
| + (gdb)
|
|
|
| - When you run `make' to build a program or library, you must run it
|
| -in a configured directory--whatever directory you were in when you
|
| -called `configure' (or one of its subdirectories).
|
| +The `-info-gdb-mi-command' Command
|
| +----------------------------------
|
|
|
| - The `Makefile' that `configure' generates in each source directory
|
| -also runs recursively. If you type `make' in a source directory such
|
| -as `gdb-7.5.1' (or in a separate configured directory configured with
|
| -`--srcdir=DIRNAME/gdb-7.5.1'), you will build all the required
|
| -libraries, and then build GDB.
|
| +Synopsis
|
| +........
|
|
|
| - When you have multiple hosts or targets configured in separate
|
| -directories, you can run `make' on them in parallel (for example, if
|
| -they are NFS-mounted on each of the hosts); they will not interfere
|
| -with each other.
|
| + -info-gdb-mi-command CMD_NAME
|
|
|
| -
|
| -File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
|
| + Query support for the GDB/MI command named CMD_NAME.
|
|
|
| -C.4 Specifying Names for Hosts and Targets
|
| -==========================================
|
| + Note that the dash (`-') starting all GDB/MI commands is technically
|
| +not part of the command name (*note GDB/MI Input Syntax::), and thus
|
| +should be omitted in CMD_NAME. However, for ease of use, this command
|
| +also accepts the form with the leading dash.
|
|
|
| -The specifications used for hosts and targets in the `configure' script
|
| -are based on a three-part naming scheme, but some short predefined
|
| -aliases are also supported. The full naming scheme encodes three pieces
|
| -of information in the following pattern:
|
| +GDB Command
|
| +...........
|
|
|
| - ARCHITECTURE-VENDOR-OS
|
| +There is no corresponding GDB command.
|
|
|
| - For example, you can use the alias `sun4' as a HOST argument, or as
|
| -the value for TARGET in a `--target=TARGET' option. The equivalent
|
| -full name is `sparc-sun-sunos4'.
|
| +Result
|
| +......
|
|
|
| - The `configure' script accompanying GDB does not provide any query
|
| -facility to list all supported host and target names or aliases.
|
| -`configure' calls the Bourne shell script `config.sub' to map
|
| -abbreviations to full names; you can read the script, if you wish, or
|
| -you can use it to test your guesses on abbreviations--for example:
|
| +The result is a tuple. There is currently only one field:
|
|
|
| - % sh config.sub i386-linux
|
| - i386-pc-linux-gnu
|
| - % sh config.sub alpha-linux
|
| - alpha-unknown-linux-gnu
|
| - % sh config.sub hp9k700
|
| - hppa1.1-hp-hpux
|
| - % sh config.sub sun4
|
| - sparc-sun-sunos4.1.1
|
| - % sh config.sub sun3
|
| - m68k-sun-sunos4.1.1
|
| - % sh config.sub i986v
|
| - Invalid configuration `i986v': machine `i986v' not recognized
|
| +`exists'
|
| + This field is equal to `"true"' if the GDB/MI command exists,
|
| + `"false"' otherwise.
|
|
|
| -`config.sub' is also distributed in the GDB source directory
|
| -(`gdb-7.5.1', for version 7.5.1).
|
|
|
| -
|
| -File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
|
| +Example
|
| +.......
|
|
|
| -C.5 `configure' Options
|
| -=======================
|
| +Here is an example where the GDB/MI command does not exist:
|
|
|
| -Here is a summary of the `configure' options and arguments that are
|
| -most often useful for building GDB. `configure' also has several other
|
| -options not listed here. *note (configure.info)What Configure Does::,
|
| -for a full explanation of `configure'.
|
| + -info-gdb-mi-command unsupported-command
|
| + ^done,command={exists="false"}
|
|
|
| - configure [--help]
|
| - [--prefix=DIR]
|
| - [--exec-prefix=DIR]
|
| - [--srcdir=DIRNAME]
|
| - [--norecursion] [--rm]
|
| - [--target=TARGET]
|
| - HOST
|
| +And here is an example where the GDB/MI command is known to the
|
| +debugger:
|
|
|
| -You may introduce options with a single `-' rather than `--' if you
|
| -prefer; but you may abbreviate option names if you use `--'.
|
| + -info-gdb-mi-command symbol-list-lines
|
| + ^done,command={exists="true"}
|
|
|
| -`--help'
|
| - Display a quick summary of how to invoke `configure'.
|
| +The `-list-features' Command
|
| +----------------------------
|
|
|
| -`--prefix=DIR'
|
| - Configure the source to install programs and files under directory
|
| - `DIR'.
|
| +Returns a list of particular features of the MI protocol that this
|
| +version of gdb implements. A feature can be a command, or a new field
|
| +in an output of some command, or even an important bugfix. While a
|
| +frontend can sometimes detect presence of a feature at runtime, it is
|
| +easier to perform detection at debugger startup.
|
|
|
| -`--exec-prefix=DIR'
|
| - Configure the source to install programs under directory `DIR'.
|
| + The command returns a list of strings, with each string naming an
|
| +available feature. Each returned string is just a name, it does not
|
| +have any internal structure. The list of possible feature names is
|
| +given below.
|
|
|
| -`--srcdir=DIRNAME'
|
| - *Warning: using this option requires GNU `make', or another `make'
|
| - that implements the `VPATH' feature.*
|
| - Use this option to make configurations in directories separate
|
| - from the GDB source directories. Among other things, you can use
|
| - this to build (or maintain) several configurations simultaneously,
|
| - in separate directories. `configure' writes
|
| - configuration-specific files in the current directory, but
|
| - arranges for them to use the source in the directory DIRNAME.
|
| - `configure' creates directories under the working directory in
|
| - parallel to the source directories below DIRNAME.
|
| + Example output:
|
|
|
| -`--norecursion'
|
| - Configure only the directory level where `configure' is executed;
|
| - do not propagate configuration to subdirectories.
|
| + (gdb) -list-features
|
| + ^done,result=["feature1","feature2"]
|
|
|
| -`--target=TARGET'
|
| - Configure GDB for cross-debugging programs running on the specified
|
| - TARGET. Without this option, GDB is configured to debug programs
|
| - that run on the same machine (HOST) as GDB itself.
|
| + The current list of features is:
|
|
|
| - There is no convenient way to generate a list of all available
|
| - targets.
|
| +`frozen-varobjs'
|
| + Indicates support for the `-var-set-frozen' command, as well as
|
| + possible presense of the `frozen' field in the output of
|
| + `-varobj-create'.
|
|
|
| -`HOST ...'
|
| - Configure GDB to run on the specified HOST.
|
| +`pending-breakpoints'
|
| + Indicates support for the `-f' option to the `-break-insert'
|
| + command.
|
|
|
| - There is no convenient way to generate a list of all available
|
| - hosts.
|
| +`python'
|
| + Indicates Python scripting support, Python-based pretty-printing
|
| + commands, and possible presence of the `display_hint' field in the
|
| + output of `-var-list-children'
|
|
|
| - There are many other options available as well, but they are
|
| -generally needed for special purposes only.
|
| +`thread-info'
|
| + Indicates support for the `-thread-info' command.
|
|
|
| -
|
| -File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
|
| +`data-read-memory-bytes'
|
| + Indicates support for the `-data-read-memory-bytes' and the
|
| + `-data-write-memory-bytes' commands.
|
|
|
| -C.6 System-wide configuration and settings
|
| -==========================================
|
| +`breakpoint-notifications'
|
| + Indicates that changes to breakpoints and breakpoints created via
|
| + the CLI will be announced via async records.
|
|
|
| -GDB can be configured to have a system-wide init file; this file will
|
| -be read and executed at startup (*note What GDB does during startup:
|
| -Startup.).
|
| +`ada-task-info'
|
| + Indicates support for the `-ada-task-info' command.
|
|
|
| - Here is the corresponding configure option:
|
| +`language-option'
|
| + Indicates that all GDB/MI commands accept the `--language' option
|
| + (*note Context management::).
|
|
|
| -`--with-system-gdbinit=FILE'
|
| - Specify that the default location of the system-wide init file is
|
| - FILE.
|
| +`info-gdb-mi-command'
|
| + Indicates support for the `-info-gdb-mi-command' command.
|
|
|
| - If GDB has been configured with the option `--prefix=$prefix', it
|
| -may be subject to relocation. Two possible cases:
|
| +`undefined-command-error-code'
|
| + Indicates support for the "undefined-command" error code in error
|
| + result records, produced when trying to execute an undefined
|
| + GDB/MI command (*note GDB/MI Result Records::).
|
|
|
| - * If the default location of this init file contains `$prefix', it
|
| - will be subject to relocation. Suppose that the configure options
|
| - are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
|
| - if GDB is moved from `$prefix' to `$install', the system init file
|
| - is looked for as `$install/etc/gdbinit' instead of
|
| - `$prefix/etc/gdbinit'.
|
| +`exec-run-start-option'
|
| + Indicates that the `-exec-run' command supports the `--start'
|
| + option (*note GDB/MI Program Execution::).
|
|
|
| - * By contrast, if the default location does not contain the prefix,
|
| - it will not be relocated. E.g. if GDB has been configured with
|
| - `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
|
| - then GDB will always look for `/usr/share/gdb/gdbinit', wherever
|
| - GDB is installed.
|
| +The `-list-target-features' Command
|
| +-----------------------------------
|
|
|
| -
|
| -File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
|
| +Returns a list of particular features that are supported by the target.
|
| +Those features affect the permitted MI commands, but unlike the
|
| +features reported by the `-list-features' command, the features depend
|
| +on which target GDB is using at the moment. Whenever a target can
|
| +change, due to commands such as `-target-select', `-target-attach' or
|
| +`-exec-run', the list of target features may change, and the frontend
|
| +should obtain it again. Example output:
|
|
|
| -Appendix D Maintenance Commands
|
| -*******************************
|
| + (gdb) -list-target-features
|
| + ^done,result=["async"]
|
|
|
| -In addition to commands intended for GDB users, GDB includes a number
|
| -of commands intended for GDB developers, that are not documented
|
| -elsewhere in this manual. These commands are provided here for
|
| -reference. (For commands that turn on debugging messages, see *Note
|
| -Debugging Output::.)
|
| + The current list of features is:
|
|
|
| -`maint agent [-at LOCATION,] EXPRESSION'
|
| -`maint agent-eval [-at LOCATION,] EXPRESSION'
|
| - Translate the given EXPRESSION into remote agent bytecodes. This
|
| - command is useful for debugging the Agent Expression mechanism
|
| - (*note Agent Expressions::). The `agent' version produces an
|
| - expression useful for data collection, such as by tracepoints,
|
| - while `maint agent-eval' produces an expression that evaluates
|
| - directly to a result. For instance, a collection expression for
|
| - `globa + globb' will include bytecodes to record four bytes of
|
| - memory at each of the addresses of `globa' and `globb', while
|
| - discarding the result of the addition, while an evaluation
|
| - expression will do the addition and return the sum. If `-at' is
|
| - given, generate remote agent bytecode for LOCATION. If not,
|
| - generate remote agent bytecode for current frame PC address.
|
| +`async'
|
| + Indicates that the target is capable of asynchronous command
|
| + execution, which means that GDB will accept further commands while
|
| + the target is running.
|
|
|
| -`maint agent-printf FORMAT,EXPR,...'
|
| - Translate the given format string and list of argument expressions
|
| - into remote agent bytecodes and display them as a disassembled
|
| - list. This command is useful for debugging the agent version of
|
| - dynamic printf (*note Dynamic Printf::.
|
| +`reverse'
|
| + Indicates that the target is capable of reverse execution. *Note
|
| + Reverse Execution::, for more information.
|
|
|
| -`maint info breakpoints'
|
| - Using the same format as `info breakpoints', display both the
|
| - breakpoints you've set explicitly, and those GDB is using for
|
| - internal purposes. Internal breakpoints are shown with negative
|
| - breakpoint numbers. The type column identifies what kind of
|
| - breakpoint is shown:
|
|
|
| - `breakpoint'
|
| - Normal, explicitly set breakpoint.
|
| +The `-list-thread-groups' Command
|
| +---------------------------------
|
|
|
| - `watchpoint'
|
| - Normal, explicitly set watchpoint.
|
| +Synopsis
|
| +--------
|
|
|
| - `longjmp'
|
| - Internal breakpoint, used to handle correctly stepping through
|
| - `longjmp' calls.
|
| + -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ]
|
|
|
| - `longjmp resume'
|
| - Internal breakpoint at the target of a `longjmp'.
|
| + Lists thread groups (*note Thread groups::). When a single thread
|
| +group is passed as the argument, lists the children of that group.
|
| +When several thread group are passed, lists information about those
|
| +thread groups. Without any parameters, lists information about all
|
| +top-level thread groups.
|
|
|
| - `until'
|
| - Temporary internal breakpoint used by the GDB `until' command.
|
| + Normally, thread groups that are being debugged are reported. With
|
| +the `--available' option, GDB reports thread groups available on the
|
| +target.
|
|
|
| - `finish'
|
| - Temporary internal breakpoint used by the GDB `finish'
|
| - command.
|
| + The output of this command may have either a `threads' result or a
|
| +`groups' result. The `thread' result has a list of tuples as value,
|
| +with each tuple describing a thread (*note GDB/MI Thread
|
| +Information::). The `groups' result has a list of tuples as value,
|
| +each tuple describing a thread group. If top-level groups are
|
| +requested (that is, no parameter is passed), or when several groups are
|
| +passed, the output always has a `groups' result. The format of the
|
| +`group' result is described below.
|
| +
|
| + To reduce the number of roundtrips it's possible to list thread
|
| +groups together with their children, by passing the `--recurse' option
|
| +and the recursion depth. Presently, only recursion depth of 1 is
|
| +permitted. If this option is present, then every reported thread group
|
| +will also include its children, either as `group' or `threads' field.
|
| +
|
| + In general, any combination of option and parameters is permitted,
|
| +with the following caveats:
|
| +
|
| + * When a single thread group is passed, the output will typically be
|
| + the `threads' result. Because threads may not contain anything,
|
| + the `recurse' option will be ignored.
|
| +
|
| + * When the `--available' option is passed, limited information may
|
| + be available. In particular, the list of threads of a process
|
| + might be inaccessible. Further, specifying specific thread groups
|
| + might not give any performance advantage over listing all thread
|
| + groups. The frontend should assume that `-list-thread-groups
|
| + --available' is always an expensive operation and cache the
|
| + results.
|
| +
|
| +
|
| + The `groups' result is a list of tuples, where each tuple may have
|
| +the following fields:
|
| +
|
| +`id'
|
| + Identifier of the thread group. This field is always present.
|
| + The identifier is an opaque string; frontends should not try to
|
| + convert it to an integer, even though it might look like one.
|
| +
|
| +`type'
|
| + The type of the thread group. At present, only `process' is a
|
| + valid type.
|
| +
|
| +`pid'
|
| + The target-specific process identifier. This field is only present
|
| + for thread groups of type `process' and only if the process exists.
|
| +
|
| +`num_children'
|
| + The number of children this thread group has. This field may be
|
| + absent for an available thread group.
|
| +
|
| +`threads'
|
| + This field has a list of tuples as value, each tuple describing a
|
| + thread. It may be present if the `--recurse' option is specified,
|
| + and it's actually possible to obtain the threads.
|
| +
|
| +`cores'
|
| + This field is a list of integers, each identifying a core that one
|
| + thread of the group is running on. This field may be absent if
|
| + such information is not available.
|
| +
|
| +`executable'
|
| + The name of the executable file that corresponds to this thread
|
| + group. The field is only present for thread groups of type
|
| + `process', and only if there is a corresponding executable file.
|
| +
|
| +
|
| +Example
|
| +-------
|
| +
|
| + gdb
|
| + -list-thread-groups
|
| + ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}]
|
| + -list-thread-groups 17
|
| + ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
|
| + frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"},
|
| + {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
|
| + frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}],
|
| + file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]]
|
| + -list-thread-groups --available
|
| + ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}]
|
| + -list-thread-groups --available --recurse 1
|
| + ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
|
| + threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
|
| + {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..]
|
| + -list-thread-groups --available --recurse 1 17 18
|
| + ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
|
| + threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]},
|
| + {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...]
|
| +
|
| +The `-info-os' Command
|
| +----------------------
|
|
|
| - `shlib events'
|
| - Shared library events.
|
| +Synopsis
|
| +........
|
|
|
| + -info-os [ TYPE ]
|
|
|
| -`set displaced-stepping'
|
| -`show displaced-stepping'
|
| - Control whether or not GDB will do "displaced stepping" if the
|
| - target supports it. Displaced stepping is a way to single-step
|
| - over breakpoints without removing them from the inferior, by
|
| - executing an out-of-line copy of the instruction that was
|
| - originally at the breakpoint location. It is also known as
|
| - out-of-line single-stepping.
|
| + If no argument is supplied, the command returns a table of available
|
| +operating-system-specific information types. If one of these types is
|
| +supplied as an argument TYPE, then the command returns a table of data
|
| +of that type.
|
|
|
| - `set displaced-stepping on'
|
| - If the target architecture supports it, GDB will use
|
| - displaced stepping to step over breakpoints.
|
| + The types of information available depend on the target operating
|
| +system.
|
|
|
| - `set displaced-stepping off'
|
| - GDB will not use displaced stepping to step over breakpoints,
|
| - even if such is supported by the target architecture.
|
| +GDB Command
|
| +...........
|
|
|
| - `set displaced-stepping auto'
|
| - This is the default mode. GDB will use displaced stepping
|
| - only if non-stop mode is active (*note Non-Stop Mode::) and
|
| - the target architecture supports displaced stepping.
|
| +The corresponding GDB command is `info os'.
|
| +
|
| +Example
|
| +.......
|
| +
|
| +When run on a GNU/Linux system, the output will look something like
|
| +this:
|
| +
|
| + gdb
|
| + -info-os
|
| + ^done,OSDataTable={nr_rows="9",nr_cols="3",
|
| + hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"},
|
| + {width="10",alignment="-1",col_name="col1",colhdr="Description"},
|
| + {width="10",alignment="-1",col_name="col2",colhdr="Title"}],
|
| + body=[item={col0="processes",col1="Listing of all processes",
|
| + col2="Processes"},
|
| + item={col0="procgroups",col1="Listing of all process groups",
|
| + col2="Process groups"},
|
| + item={col0="threads",col1="Listing of all threads",
|
| + col2="Threads"},
|
| + item={col0="files",col1="Listing of all file descriptors",
|
| + col2="File descriptors"},
|
| + item={col0="sockets",col1="Listing of all internet-domain sockets",
|
| + col2="Sockets"},
|
| + item={col0="shm",col1="Listing of all shared-memory regions",
|
| + col2="Shared-memory regions"},
|
| + item={col0="semaphores",col1="Listing of all semaphores",
|
| + col2="Semaphores"},
|
| + item={col0="msg",col1="Listing of all message queues",
|
| + col2="Message queues"},
|
| + item={col0="modules",col1="Listing of all loaded kernel modules",
|
| + col2="Kernel modules"}]}
|
| + gdb
|
| + -info-os processes
|
| + ^done,OSDataTable={nr_rows="190",nr_cols="4",
|
| + hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"},
|
| + {width="10",alignment="-1",col_name="col1",colhdr="user"},
|
| + {width="10",alignment="-1",col_name="col2",colhdr="command"},
|
| + {width="10",alignment="-1",col_name="col3",colhdr="cores"}],
|
| + body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"},
|
| + item={col0="2",col1="root",col2="[kthreadd]",col3="1"},
|
| + item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"},
|
| + ...
|
| + item={col0="26446",col1="stan",col2="bash",col3="0"},
|
| + item={col0="28152",col1="stan",col2="bash",col3="1"}]}
|
| + (gdb)
|
| +
|
| + (Note that the MI output here includes a `"Title"' column that does
|
| +not appear in command-line `info os'; this column is useful for MI
|
| +clients that want to enumerate the types of data, such as in a popup
|
| +menu, but is needless clutter on the command line, and `info os' omits
|
| +it.)
|
| +
|
| +The `-add-inferior' Command
|
| +---------------------------
|
|
|
| -`maint check-symtabs'
|
| - Check the consistency of psymtabs and symtabs.
|
| +Synopsis
|
| +--------
|
|
|
| -`maint cplus first_component NAME'
|
| - Print the first C++ class/namespace component of NAME.
|
| + -add-inferior
|
|
|
| -`maint cplus namespace'
|
| - Print the list of possible C++ namespaces.
|
| + Creates a new inferior (*note Inferiors and Programs::). The created
|
| +inferior is not associated with any executable. Such association may
|
| +be established with the `-file-exec-and-symbols' command (*note GDB/MI
|
| +File Commands::). The command response has a single field, `inferior',
|
| +whose value is the identifier of the thread group corresponding to the
|
| +new inferior.
|
|
|
| -`maint demangle NAME'
|
| - Demangle a C++ or Objective-C mangled NAME.
|
| +Example
|
| +-------
|
|
|
| -`maint deprecate COMMAND [REPLACEMENT]'
|
| -`maint undeprecate COMMAND'
|
| - Deprecate or undeprecate the named COMMAND. Deprecated commands
|
| - cause GDB to issue a warning when you use them. The optional
|
| - argument REPLACEMENT says which newer command should be used in
|
| - favor of the deprecated one; if it is given, GDB will mention the
|
| - replacement as part of the warning.
|
| + gdb
|
| + -add-inferior
|
| + ^done,inferior="i3"
|
|
|
| -`maint dump-me'
|
| - Cause a fatal signal in the debugger and force it to dump its core.
|
| - This is supported only on systems which support aborting a program
|
| - with the `SIGQUIT' signal.
|
| +The `-interpreter-exec' Command
|
| +-------------------------------
|
|
|
| -`maint internal-error [MESSAGE-TEXT]'
|
| -`maint internal-warning [MESSAGE-TEXT]'
|
| - Cause GDB to call the internal function `internal_error' or
|
| - `internal_warning' and hence behave as though an internal error or
|
| - internal warning has been detected. In addition to reporting the
|
| - internal problem, these functions give the user the opportunity to
|
| - either quit GDB or create a core file of the current GDB session.
|
| +Synopsis
|
| +--------
|
|
|
| - These commands take an optional parameter MESSAGE-TEXT that is
|
| - used as the text of the error or warning message.
|
| + -interpreter-exec INTERPRETER COMMAND
|
| +Execute the specified COMMAND in the given INTERPRETER.
|
|
|
| - Here's an example of using `internal-error':
|
| +GDB Command
|
| +-----------
|
|
|
| - (gdb) maint internal-error testing, 1, 2
|
| - .../maint.c:121: internal-error: testing, 1, 2
|
| - A problem internal to GDB has been detected. Further
|
| - debugging may prove unreliable.
|
| - Quit this debugging session? (y or n) n
|
| - Create a core file? (y or n) n
|
| - (gdb)
|
| +The corresponding GDB command is `interpreter-exec'.
|
|
|
| -`maint set internal-error ACTION [ask|yes|no]'
|
| -`maint show internal-error ACTION'
|
| -`maint set internal-warning ACTION [ask|yes|no]'
|
| -`maint show internal-warning ACTION'
|
| - When GDB reports an internal problem (error or warning) it gives
|
| - the user the opportunity to both quit GDB and create a core file
|
| - of the current GDB session. These commands let you override the
|
| - default behaviour for each particular ACTION, described in the
|
| - table below.
|
| +Example
|
| +-------
|
|
|
| - `quit'
|
| - You can specify that GDB should always (yes) or never (no)
|
| - quit. The default is to ask the user what to do.
|
| + (gdb)
|
| + -interpreter-exec console "break main"
|
| + &"During symbol reading, couldn't parse type; debugger out of date?.\n"
|
| + &"During symbol reading, bad structure-type format.\n"
|
| + ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
|
| + ^done
|
| + (gdb)
|
|
|
| - `corefile'
|
| - You can specify that GDB should always (yes) or never (no)
|
| - create a core file. The default is to ask the user what to
|
| - do.
|
| +The `-inferior-tty-set' Command
|
| +-------------------------------
|
|
|
| -`maint packet TEXT'
|
| - If GDB is talking to an inferior via the serial protocol, then
|
| - this command sends the string TEXT to the inferior, and displays
|
| - the response packet. GDB supplies the initial `$' character, the
|
| - terminating `#' character, and the checksum.
|
| +Synopsis
|
| +--------
|
|
|
| -`maint print architecture [FILE]'
|
| - Print the entire architecture configuration. The optional argument
|
| - FILE names the file where the output goes.
|
| + -inferior-tty-set /dev/pts/1
|
|
|
| -`maint print c-tdesc'
|
| - Print the current target description (*note Target Descriptions::)
|
| - as a C source file. The created source file can be used in GDB
|
| - when an XML parser is not available to parse the description.
|
| + Set terminal for future runs of the program being debugged.
|
|
|
| -`maint print dummy-frames'
|
| - Prints the contents of GDB's internal dummy-frame stack.
|
| +GDB Command
|
| +-----------
|
|
|
| - (gdb) b add
|
| - ...
|
| - (gdb) print add(2,3)
|
| - Breakpoint 2, add (a=2, b=3) at ...
|
| - 58 return (a + b);
|
| - The program being debugged stopped while in a function called from GDB.
|
| - ...
|
| - (gdb) maint print dummy-frames
|
| - 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
|
| - top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
|
| - call_lo=0x01014000 call_hi=0x01014001
|
| - (gdb)
|
| +The corresponding GDB command is `set inferior-tty' /dev/pts/1.
|
|
|
| - Takes an optional file parameter.
|
| +Example
|
| +-------
|
|
|
| -`maint print registers [FILE]'
|
| -`maint print raw-registers [FILE]'
|
| -`maint print cooked-registers [FILE]'
|
| -`maint print register-groups [FILE]'
|
| -`maint print remote-registers [FILE]'
|
| - Print GDB's internal register data structures.
|
| + (gdb)
|
| + -inferior-tty-set /dev/pts/1
|
| + ^done
|
| + (gdb)
|
|
|
| - The command `maint print raw-registers' includes the contents of
|
| - the raw register cache; the command `maint print cooked-registers'
|
| - includes the (cooked) value of all registers, including registers
|
| - which aren't available on the target nor visible to user; the
|
| - command `maint print register-groups' includes the groups that
|
| - each register is a member of; and the command `maint print
|
| - remote-registers' includes the remote target's register numbers
|
| - and offsets in the `G' packets. *Note Registers:
|
| - (gdbint)Registers.
|
| +The `-inferior-tty-show' Command
|
| +--------------------------------
|
|
|
| - These commands take an optional parameter, a file name to which to
|
| - write the information.
|
| +Synopsis
|
| +--------
|
|
|
| -`maint print reggroups [FILE]'
|
| - Print GDB's internal register group data structures. The optional
|
| - argument FILE tells to what file to write the information.
|
| + -inferior-tty-show
|
|
|
| - The register groups info looks like this:
|
| + Show terminal for future runs of program being debugged.
|
|
|
| - (gdb) maint print reggroups
|
| - Group Type
|
| - general user
|
| - float user
|
| - all user
|
| - vector user
|
| - system user
|
| - save internal
|
| - restore internal
|
| +GDB Command
|
| +-----------
|
|
|
| -`flushregs'
|
| - This command forces GDB to flush its internal register cache.
|
| +The corresponding GDB command is `show inferior-tty'.
|
|
|
| -`maint print objfiles'
|
| - Print a dump of all known object files. For each object file, this
|
| - command prints its name, address in memory, and all of its psymtabs
|
| - and symtabs.
|
| +Example
|
| +-------
|
|
|
| -`maint print section-scripts [REGEXP]'
|
| - Print a dump of scripts specified in the `.debug_gdb_section'
|
| - section. If REGEXP is specified, only print scripts loaded by
|
| - object files matching REGEXP. For each script, this command
|
| - prints its name as specified in the objfile, and the full path if
|
| - known. *Note dotdebug_gdb_scripts section::.
|
| + (gdb)
|
| + -inferior-tty-set /dev/pts/1
|
| + ^done
|
| + (gdb)
|
| + -inferior-tty-show
|
| + ^done,inferior_tty_terminal="/dev/pts/1"
|
| + (gdb)
|
|
|
| -`maint print statistics'
|
| - This command prints, for each object file in the program, various
|
| - data about that object file followed by the byte cache ("bcache")
|
| - statistics for the object file. The objfile data includes the
|
| - number of minimal, partial, full, and stabs symbols, the number of
|
| - types defined by the objfile, the number of as yet unexpanded psym
|
| - tables, the number of line tables and string tables, and the
|
| - amount of memory used by the various tables. The bcache
|
| - statistics include the counts, sizes, and counts of duplicates of
|
| - all and unique objects, max, average, and median entry size, total
|
| - memory used and its overhead and savings, and various measures of
|
| - the hash table size and chain lengths.
|
| +The `-enable-timings' Command
|
| +-----------------------------
|
|
|
| -`maint print target-stack'
|
| - A "target" is an interface between the debugger and a particular
|
| - kind of file or process. Targets can be stacked in "strata", so
|
| - that more than one target can potentially respond to a request.
|
| - In particular, memory accesses will walk down the stack of targets
|
| - until they find a target that is interested in handling that
|
| - particular address.
|
| +Synopsis
|
| +--------
|
|
|
| - This command prints a short description of each layer that was
|
| - pushed on the "target stack", starting from the top layer down to
|
| - the bottom one.
|
| + -enable-timings [yes | no]
|
|
|
| -`maint print type EXPR'
|
| - Print the type chain for a type specified by EXPR. The argument
|
| - can be either a type name or a symbol. If it is a symbol, the
|
| - type of that symbol is described. The type chain produced by this
|
| - command is a recursive definition of the data type as stored in
|
| - GDB's data structures, including its flags and contained types.
|
| + Toggle the printing of the wallclock, user and system times for an MI
|
| +command as a field in its output. This command is to help frontend
|
| +developers optimize the performance of their code. No argument is
|
| +equivalent to `yes'.
|
|
|
| -`maint set dwarf2 always-disassemble'
|
| +GDB Command
|
| +-----------
|
|
|
| -`maint show dwarf2 always-disassemble'
|
| - Control the behavior of `info address' when using DWARF debugging
|
| - information.
|
| +No equivalent.
|
| +
|
| +Example
|
| +-------
|
| +
|
| + (gdb)
|
| + -enable-timings
|
| + ^done
|
| + (gdb)
|
| + -break-insert main
|
| + ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y",
|
| + addr="0x080484ed",func="main",file="myprog.c",
|
| + fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"],
|
| + times="0"},
|
| + time={wallclock="0.05185",user="0.00800",system="0.00000"}
|
| + (gdb)
|
| + -enable-timings no
|
| + ^done
|
| + (gdb)
|
| + -exec-run
|
| + ^running
|
| + (gdb)
|
| + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
|
| + frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"},
|
| + {name="argv",value="0xbfb60364"}],file="myprog.c",
|
| + fullname="/home/nickrob/myprog.c",line="73"}
|
| + (gdb)
|
|
|
| - The default is `off', which means that GDB should try to describe
|
| - a variable's location in an easily readable format. When `on',
|
| - GDB will instead display the DWARF location expression in an
|
| - assembly-like format. Note that some locations are too complex
|
| - for GDB to describe simply; in this case you will always see the
|
| - disassembly form.
|
| +
|
| +File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top
|
|
|
| - Here is an example of the resulting disassembly:
|
| +28 GDB Annotations
|
| +******************
|
|
|
| - (gdb) info addr argc
|
| - Symbol "argc" is a complex DWARF expression:
|
| - 1: DW_OP_fbreg 0
|
| +This chapter describes annotations in GDB. Annotations were designed
|
| +to interface GDB to graphical user interfaces or other similar programs
|
| +which want to interact with GDB at a relatively high level.
|
|
|
| - For more information on these expressions, see the DWARF standard
|
| - (http://www.dwarfstd.org/).
|
| + The annotation mechanism has largely been superseded by GDB/MI
|
| +(*note GDB/MI::).
|
|
|
| -`maint set dwarf2 max-cache-age'
|
| -`maint show dwarf2 max-cache-age'
|
| - Control the DWARF 2 compilation unit cache.
|
| +* Menu:
|
|
|
| - In object files with inter-compilation-unit references, such as
|
| - those produced by the GCC option `-feliminate-dwarf2-dups', the
|
| - DWARF 2 reader needs to frequently refer to previously read
|
| - compilation units. This setting controls how long a compilation
|
| - unit will remain in the cache if it is not referenced. A higher
|
| - limit means that cached compilation units will be stored in memory
|
| - longer, and more total memory will be used. Setting it to zero
|
| - disables caching, which will slow down GDB startup, but reduce
|
| - memory consumption.
|
| +* Annotations Overview:: What annotations are; the general syntax.
|
| +* Server Prefix:: Issuing a command without affecting user state.
|
| +* Prompting:: Annotations marking GDB's need for input.
|
| +* Errors:: Annotations for error messages.
|
| +* Invalidation:: Some annotations describe things now invalid.
|
| +* Annotations for Running::
|
| + Whether the program is running, how it stopped, etc.
|
| +* Source Annotations:: Annotations describing source code.
|
|
|
| -`maint set profile'
|
| -`maint show profile'
|
| - Control profiling of GDB.
|
| +
|
| +File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations
|
|
|
| - Profiling will be disabled until you use the `maint set profile'
|
| - command to enable it. When you enable profiling, the system will
|
| - begin collecting timing and execution count data; when you disable
|
| - profiling or exit GDB, the results will be written to a log file.
|
| - Remember that if you use profiling, GDB will overwrite the
|
| - profiling log file (often called `gmon.out'). If you have a
|
| - record of important profiling data in a `gmon.out' file, be sure
|
| - to move it to a safe location.
|
| +28.1 What is an Annotation?
|
| +===========================
|
|
|
| - Configuring with `--enable-profiling' arranges for GDB to be
|
| - compiled with the `-pg' compiler option.
|
| +Annotations start with a newline character, two `control-z' characters,
|
| +and the name of the annotation. If there is no additional information
|
| +associated with this annotation, the name of the annotation is followed
|
| +immediately by a newline. If there is additional information, the name
|
| +of the annotation is followed by a space, the additional information,
|
| +and a newline. The additional information cannot contain newline
|
| +characters.
|
| +
|
| + Any output not beginning with a newline and two `control-z'
|
| +characters denotes literal output from GDB. Currently there is no need
|
| +for GDB to output a newline followed by two `control-z' characters, but
|
| +if there was such a need, the annotations could be extended with an
|
| +`escape' annotation which means those three characters as output.
|
| +
|
| + The annotation LEVEL, which is specified using the `--annotate'
|
| +command line option (*note Mode Options::), controls how much
|
| +information GDB prints together with its prompt, values of expressions,
|
| +source lines, and other types of output. Level 0 is for no
|
| +annotations, level 1 is for use when GDB is run as a subprocess of GNU
|
| +Emacs, level 3 is the maximum annotation suitable for programs that
|
| +control GDB, and level 2 annotations have been made obsolete (*note
|
| +Limitations of the Annotation Interface: (annotate)Limitations.).
|
| +
|
| +`set annotate LEVEL'
|
| + The GDB command `set annotate' sets the level of annotations to
|
| + the specified LEVEL.
|
| +
|
| +`show annotate'
|
| + Show the current annotation level.
|
| +
|
| + This chapter describes level 3 annotations.
|
| +
|
| + A simple example of starting up GDB with annotations is:
|
| +
|
| + $ gdb --annotate=3
|
| + GNU gdb 6.0
|
| + Copyright 2003 Free Software Foundation, Inc.
|
| + GDB is free software, covered by the GNU General Public License,
|
| + and you are welcome to change it and/or distribute copies of it
|
| + under certain conditions.
|
| + Type "show copying" to see the conditions.
|
| + There is absolutely no warranty for GDB. Type "show warranty"
|
| + for details.
|
| + This GDB was configured as "i386-pc-linux-gnu"
|
| +
|
| + ^Z^Zpre-prompt
|
| + (gdb)
|
| + ^Z^Zprompt
|
| + quit
|
| +
|
| + ^Z^Zpost-prompt
|
| + $
|
| +
|
| + Here `quit' is input to GDB; the rest is output from GDB. The three
|
| +lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are
|
| +annotations; the rest is output from GDB.
|
|
|
| -`maint set show-debug-regs'
|
| -`maint show show-debug-regs'
|
| - Control whether to show variables that mirror the hardware debug
|
| - registers. Use `ON' to enable, `OFF' to disable. If enabled, the
|
| - debug registers values are shown when GDB inserts or removes a
|
| - hardware breakpoint or watchpoint, and when the inferior triggers
|
| - a hardware-assisted breakpoint or watchpoint.
|
| +
|
| +File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations
|
|
|
| -`maint set show-all-tib'
|
| -`maint show show-all-tib'
|
| - Control whether to show all non zero areas within a 1k block
|
| - starting at thread local base, when using the `info w32
|
| - thread-information-block' command.
|
| +28.2 The Server Prefix
|
| +======================
|
|
|
| -`maint space'
|
| - Control whether to display memory usage for each command. If set
|
| - to a nonzero value, GDB will display how much memory each command
|
| - took, following the command's own output. This can also be
|
| - requested by invoking GDB with the `--statistics' command-line
|
| - switch (*note Mode Options::).
|
| -
|
| -`maint time'
|
| - Control whether to display the execution time of GDB for each
|
| - command. If set to a nonzero value, GDB will display how much
|
| - time it took to execute each command, following the command's own
|
| - output. Both CPU time and wallclock time are printed. Printing
|
| - both is useful when trying to determine whether the cost is CPU
|
| - or, e.g., disk/network, latency. Note that the CPU time printed
|
| - is for GDB only, it does not include the execution time of the
|
| - inferior because there's no mechanism currently to compute how
|
| - much time was spent by GDB and how much time was spent by the
|
| - program been debugged. This can also be requested by invoking GDB
|
| - with the `--statistics' command-line switch (*note Mode Options::).
|
| +If you prefix a command with `server ' then it will not affect the
|
| +command history, nor will it affect GDB's notion of which command to
|
| +repeat if <RET> is pressed on a line by itself. This means that
|
| +commands can be run behind a user's back by a front-end in a
|
| +transparent manner.
|
|
|
| -`maint translate-address [SECTION] ADDR'
|
| - Find the symbol stored at the location specified by the address
|
| - ADDR and an optional section name SECTION. If found, GDB prints
|
| - the name of the closest symbol and an offset from the symbol's
|
| - location to the specified address. This is similar to the `info
|
| - address' command (*note Symbols::), except that this command also
|
| - allows to find symbols in other sections.
|
| + The `server ' prefix does not affect the recording of values into
|
| +the value history; to print a value without recording it into the value
|
| +history, use the `output' command instead of the `print' command.
|
|
|
| - If section was not specified, the section in which the symbol was
|
| - found is also printed. For dynamically linked executables, the
|
| - name of executable or shared library containing the symbol is
|
| - printed as well.
|
| + Using this prefix also disables confirmation requests (*note
|
| +confirmation requests::).
|
|
|
| +
|
| +File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations
|
|
|
| - The following command is useful for non-interactive invocations of
|
| -GDB, such as in the test suite.
|
| +28.3 Annotation for GDB Input
|
| +=============================
|
|
|
| -`set watchdog NSEC'
|
| - Set the maximum number of seconds GDB will wait for the target
|
| - operation to finish. If this time expires, GDB reports and error
|
| - and the command is aborted.
|
| +When GDB prompts for input, it annotates this fact so it is possible to
|
| +know when to send output, when the output from a given command is over,
|
| +etc.
|
|
|
| -`show watchdog'
|
| - Show the current setting of the target wait timeout.
|
| + Different kinds of input each have a different "input type". Each
|
| +input type has three annotations: a `pre-' annotation, which denotes
|
| +the beginning of any prompt which is being output, a plain annotation,
|
| +which denotes the end of the prompt, and then a `post-' annotation
|
| +which denotes the end of any echo which may (or may not) be associated
|
| +with the input. For example, the `prompt' input type features the
|
| +following annotations:
|
|
|
| -
|
| -File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
|
| + ^Z^Zpre-prompt
|
| + ^Z^Zprompt
|
| + ^Z^Zpost-prompt
|
|
|
| -Appendix E GDB Remote Serial Protocol
|
| -*************************************
|
| + The input types are
|
|
|
| -* Menu:
|
| +`prompt'
|
| + When GDB is prompting for a command (the main GDB prompt).
|
|
|
| -* Overview::
|
| -* Packets::
|
| -* Stop Reply Packets::
|
| -* General Query Packets::
|
| -* Architecture-Specific Protocol Details::
|
| -* Tracepoint Packets::
|
| -* Host I/O Packets::
|
| -* Interrupts::
|
| -* Notification Packets::
|
| -* Remote Non-Stop::
|
| -* Packet Acknowledgment::
|
| -* Examples::
|
| -* File-I/O Remote Protocol Extension::
|
| -* Library List Format::
|
| -* Library List Format for SVR4 Targets::
|
| -* Memory Map Format::
|
| -* Thread List Format::
|
| -* Traceframe Info Format::
|
| +`commands'
|
| + When GDB prompts for a set of commands, like in the `commands'
|
| + command. The annotations are repeated for each command which is
|
| + input.
|
|
|
| -
|
| -File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
|
| +`overload-choice'
|
| + When GDB wants the user to select between various overloaded
|
| + functions.
|
|
|
| -E.1 Overview
|
| -============
|
| +`query'
|
| + When GDB wants the user to confirm a potentially dangerous
|
| + operation.
|
|
|
| -There may be occasions when you need to know something about the
|
| -protocol--for example, if there is only one serial port to your target
|
| -machine, you might want your program to do something special if it
|
| -recognizes a packet meant for GDB.
|
| +`prompt-for-continue'
|
| + When GDB is asking the user to press return to continue. Note:
|
| + Don't expect this to work well; instead use `set height 0' to
|
| + disable prompting. This is because the counting of lines is buggy
|
| + in the presence of annotations.
|
|
|
| - In the examples below, `->' and `<-' are used to indicate
|
| -transmitted and received data, respectively.
|
| +
|
| +File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations
|
|
|
| - All GDB commands and responses (other than acknowledgments and
|
| -notifications, see *Note Notification Packets::) are sent as a PACKET.
|
| -A PACKET is introduced with the character `$', the actual PACKET-DATA,
|
| -and the terminating character `#' followed by a two-digit CHECKSUM:
|
| +28.4 Errors
|
| +===========
|
|
|
| - `$'PACKET-DATA`#'CHECKSUM
|
| - The two-digit CHECKSUM is computed as the modulo 256 sum of all
|
| -characters between the leading `$' and the trailing `#' (an eight bit
|
| -unsigned checksum).
|
| + ^Z^Zquit
|
|
|
| - Implementors should note that prior to GDB 5.0 the protocol
|
| -specification also included an optional two-digit SEQUENCE-ID:
|
| + This annotation occurs right before GDB responds to an interrupt.
|
|
|
| - `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
|
| + ^Z^Zerror
|
|
|
| -That SEQUENCE-ID was appended to the acknowledgment. GDB has never
|
| -output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0
|
| -must not accept SEQUENCE-ID.
|
| + This annotation occurs right before GDB responds to an error.
|
|
|
| - When either the host or the target machine receives a packet, the
|
| -first response expected is an acknowledgment: either `+' (to indicate
|
| -the package was received correctly) or `-' (to request retransmission):
|
| + Quit and error annotations indicate that any annotations which GDB
|
| +was in the middle of may end abruptly. For example, if a
|
| +`value-history-begin' annotation is followed by a `error', one cannot
|
| +expect to receive the matching `value-history-end'. One cannot expect
|
| +not to receive it either, however; an error annotation does not
|
| +necessarily mean that GDB is immediately returning all the way to the
|
| +top level.
|
|
|
| - -> `$'PACKET-DATA`#'CHECKSUM
|
| - <- `+'
|
| - The `+'/`-' acknowledgments can be disabled once a connection is
|
| -established. *Note Packet Acknowledgment::, for details.
|
| + A quit or error annotation may be preceded by
|
|
|
| - The host (GDB) sends COMMANDs, and the target (the debugging stub
|
| -incorporated in your program) sends a RESPONSE. In the case of step
|
| -and continue COMMANDs, the response is only sent when the operation has
|
| -completed, and the target has again stopped all threads in all attached
|
| -processes. This is the default all-stop mode behavior, but the remote
|
| -protocol also supports GDB's non-stop execution mode; see *Note Remote
|
| -Non-Stop::, for details.
|
| + ^Z^Zerror-begin
|
|
|
| - PACKET-DATA consists of a sequence of characters with the exception
|
| -of `#' and `$' (see `X' packet for additional exceptions).
|
| + Any output between that and the quit or error annotation is the error
|
| +message.
|
|
|
| - Fields within the packet should be separated using `,' `;' or `:'.
|
| -Except where otherwise noted all numbers are represented in HEX with
|
| -leading zeros suppressed.
|
| + Warning messages are not yet annotated.
|
|
|
| - Implementors should note that prior to GDB 5.0, the character `:'
|
| -could not appear as the third character in a packet (as it would
|
| -potentially conflict with the SEQUENCE-ID).
|
| +
|
| +File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations
|
|
|
| - Binary data in most packets is encoded either as two hexadecimal
|
| -digits per byte of binary data. This allowed the traditional remote
|
| -protocol to work over connections which were only seven-bit clean.
|
| -Some packets designed more recently assume an eight-bit clean
|
| -connection, and use a more efficient encoding to send and receive
|
| -binary data.
|
| +28.5 Invalidation Notices
|
| +=========================
|
|
|
| - The binary data representation uses `7d' (ASCII `}') as an escape
|
| -character. Any escaped byte is transmitted as the escape character
|
| -followed by the original character XORed with `0x20'. For example, the
|
| -byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The
|
| -bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
|
| -must always be escaped. Responses sent by the stub must also escape
|
| -`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
|
| -run-length encoded sequence (described next).
|
| +The following annotations say that certain pieces of state may have
|
| +changed.
|
|
|
| - Response DATA can be run-length encoded to save space. Run-length
|
| -encoding replaces runs of identical characters with one instance of the
|
| -repeated character, followed by a `*' and a repeat count. The repeat
|
| -count is itself sent encoded, to avoid binary characters in DATA: a
|
| -value of N is sent as `N+29'. For a repeat count greater or equal to
|
| -3, this produces a printable ASCII character, e.g. a space (ASCII code
|
| -32) for a repeat count of 3. (This is because run-length encoding
|
| -starts to win for counts 3 or more.) Thus, for example, `0* ' is a
|
| -run-length encoding of "0000": the space character after `*' means
|
| -repeat the leading `0' `32 - 29 = 3' more times.
|
| +`^Z^Zframes-invalid'
|
| + The frames (for example, output from the `backtrace' command) may
|
| + have changed.
|
|
|
| - The printable characters `#' and `$' or with a numeric value greater
|
| -than 126 must not be used. Runs of six repeats (`#') or seven repeats
|
| -(`$') can be expanded using a repeat count of only five (`"'). For
|
| -example, `00000000' can be encoded as `0*"00'.
|
| +`^Z^Zbreakpoints-invalid'
|
| + The breakpoints may have changed. For example, the user just
|
| + added or deleted a breakpoint.
|
|
|
| - The error response returned for some packets includes a two character
|
| -error number. That number is not well defined.
|
| +
|
| +File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations
|
|
|
| - For any COMMAND not supported by the stub, an empty response
|
| -(`$#00') should be returned. That way it is possible to extend the
|
| -protocol. A newer GDB can tell if a packet is supported based on that
|
| -response.
|
| +28.6 Running the Program
|
| +========================
|
|
|
| - At a minimum, a stub is required to support the `g' and `G' commands
|
| -for register access, and the `m' and `M' commands for memory access.
|
| -Stubs that only control single-threaded targets can implement run
|
| -control with the `c' (continue), and `s' (step) commands. Stubs that
|
| -support multi-threading targets should support the `vCont' command.
|
| -All other commands are optional.
|
| +When the program starts executing due to a GDB command such as `step'
|
| +or `continue',
|
|
|
| -
|
| -File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
|
| + ^Z^Zstarting
|
|
|
| -E.2 Packets
|
| -===========
|
| + is output. When the program stops,
|
|
|
| -The following table provides a complete list of all currently defined
|
| -COMMANDs and their corresponding response DATA. *Note File-I/O Remote
|
| -Protocol Extension::, for details about the File I/O extension of the
|
| -remote protocol.
|
| + ^Z^Zstopped
|
|
|
| - Each packet's description has a template showing the packet's overall
|
| -syntax, followed by an explanation of the packet's meaning. We include
|
| -spaces in some of the templates for clarity; these are not part of the
|
| -packet's syntax. No GDB packet uses spaces to separate its components.
|
| -For example, a template like `foo BAR BAZ' describes a packet
|
| -beginning with the three ASCII bytes `foo', followed by a BAR, followed
|
| -directly by a BAZ. GDB does not transmit a space character between the
|
| -`foo' and the BAR, or between the BAR and the BAZ.
|
| + is output. Before the `stopped' annotation, a variety of
|
| +annotations describe how the program stopped.
|
|
|
| - Several packets and replies include a THREAD-ID field to identify a
|
| -thread. Normally these are positive numbers with a target-specific
|
| -interpretation, formatted as big-endian hex strings. A THREAD-ID can
|
| -also be a literal `-1' to indicate all threads, or `0' to pick any
|
| -thread.
|
| +`^Z^Zexited EXIT-STATUS'
|
| + The program exited, and EXIT-STATUS is the exit status (zero for
|
| + successful exit, otherwise nonzero).
|
|
|
| - In addition, the remote protocol supports a multiprocess feature in
|
| -which the THREAD-ID syntax is extended to optionally include both
|
| -process and thread ID fields, as `pPID.TID'. The PID (process) and TID
|
| -(thread) components each have the format described above: a positive
|
| -number with target-specific interpretation formatted as a big-endian
|
| -hex string, literal `-1' to indicate all processes or threads
|
| -(respectively), or `0' to indicate an arbitrary process or thread.
|
| -Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It
|
| -is an error to specify all processes but a specific thread, such as
|
| -`p-1.TID'. Note that the `p' prefix is _not_ used for those packets
|
| -and replies explicitly documented to include a process ID, rather than
|
| -a THREAD-ID.
|
| +`^Z^Zsignalled'
|
| + The program exited with a signal. After the `^Z^Zsignalled', the
|
| + annotation continues:
|
|
|
| - The multiprocess THREAD-ID syntax extensions are only used if both
|
| -GDB and the stub report support for the `multiprocess' feature using
|
| -`qSupported'. *Note multiprocess extensions::, for more information.
|
| + INTRO-TEXT
|
| + ^Z^Zsignal-name
|
| + NAME
|
| + ^Z^Zsignal-name-end
|
| + MIDDLE-TEXT
|
| + ^Z^Zsignal-string
|
| + STRING
|
| + ^Z^Zsignal-string-end
|
| + END-TEXT
|
|
|
| - Note that all packet forms beginning with an upper- or lower-case
|
| -letter, other than those described here, are reserved for future use.
|
| + where NAME is the name of the signal, such as `SIGILL' or
|
| + `SIGSEGV', and STRING is the explanation of the signal, such as
|
| + `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT,
|
| + MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no
|
| + particular format.
|
|
|
| - Here are the packet descriptions.
|
| +`^Z^Zsignal'
|
| + The syntax of this annotation is just like `signalled', but GDB is
|
| + just saying that the program received the signal, not that it was
|
| + terminated with it.
|
|
|
| -`!'
|
| - Enable extended mode. In extended mode, the remote server is made
|
| - persistent. The `R' packet is used to restart the program being
|
| - debugged.
|
| +`^Z^Zbreakpoint NUMBER'
|
| + The program hit breakpoint number NUMBER.
|
|
|
| - Reply:
|
| - `OK'
|
| - The remote target both supports and has enabled extended mode.
|
| +`^Z^Zwatchpoint NUMBER'
|
| + The program hit watchpoint number NUMBER.
|
|
|
| -`?'
|
| - Indicate the reason the target halted. The reply is the same as
|
| - for step and continue. This packet has a special interpretation
|
| - when the target is in non-stop mode; see *Note Remote Non-Stop::.
|
| +
|
| +File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations
|
|
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +28.7 Displaying Source
|
| +======================
|
|
|
| -`A ARGLEN,ARGNUM,ARG,...'
|
| - Initialized `argv[]' array passed into program. ARGLEN specifies
|
| - the number of bytes in the hex encoded byte stream ARG. See
|
| - `gdbserver' for more details.
|
| +The following annotation is used instead of displaying source code:
|
|
|
| - Reply:
|
| - `OK'
|
| - The arguments were set.
|
| + ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR
|
|
|
| - `E NN'
|
| - An error occurred.
|
| + where FILENAME is an absolute file name indicating which source
|
| +file, LINE is the line number within that file (where 1 is the first
|
| +line in the file), CHARACTER is the character position within the file
|
| +(where 0 is the first character in the file) (for most debug formats
|
| +this will necessarily point to the beginning of a line), MIDDLE is
|
| +`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at
|
| +the beginning of the line, and ADDR is the address in the target
|
| +program associated with the source which is being displayed. ADDR is
|
| +in the form `0x' followed by one or more lowercase hex digits (note
|
| +that this does not depend on the language).
|
|
|
| -`b BAUD'
|
| - (Don't use this packet; its behavior is not well-defined.) Change
|
| - the serial line speed to BAUD.
|
| +
|
| +File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Annotations, Up: Top
|
|
|
| - JTC: _When does the transport layer state change? When it's
|
| - received, or after the ACK is transmitted. In either case, there
|
| - are problems if the command or the acknowledgment packet is
|
| - dropped._
|
| +29 JIT Compilation Interface
|
| +****************************
|
|
|
| - Stan: _If people really wanted to add something like this, and get
|
| - it working for the first time, they ought to modify ser-unix.c to
|
| - send some kind of out-of-band message to a specially-setup stub
|
| - and have the switch happen "in between" packets, so that from
|
| - remote protocol's point of view, nothing actually happened._
|
| +This chapter documents GDB's "just-in-time" (JIT) compilation
|
| +interface. A JIT compiler is a program or library that generates native
|
| +executable code at runtime and executes it, usually in order to achieve
|
| +good performance while maintaining platform independence.
|
| +
|
| + Programs that use JIT compilation are normally difficult to debug
|
| +because portions of their code are generated at runtime, instead of
|
| +being loaded from object files, which is where GDB normally finds the
|
| +program's symbols and debug information. In order to debug programs
|
| +that use JIT compilation, GDB has an interface that allows the program
|
| +to register in-memory symbol files with GDB at runtime.
|
| +
|
| + If you are using GDB to debug a program that uses this interface,
|
| +then it should work transparently so long as you have not stripped the
|
| +binary. If you are developing a JIT compiler, then the interface is
|
| +documented in the rest of this chapter. At this time, the only known
|
| +client of this interface is the LLVM JIT.
|
| +
|
| + Broadly speaking, the JIT interface mirrors the dynamic loader
|
| +interface. The JIT compiler communicates with GDB by writing data into
|
| +a global variable and calling a fuction at a well-known symbol. When
|
| +GDB attaches, it reads a linked list of symbol files from the global
|
| +variable to find existing code, and puts a breakpoint in the function
|
| +so that it can find out about additional code.
|
|
|
| -`B ADDR,MODE'
|
| - Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
|
| +* Menu:
|
|
|
| - Don't use this packet. Use the `Z' and `z' packets instead (*note
|
| - insert breakpoint or watchpoint packet::).
|
| +* Declarations:: Relevant C struct declarations
|
| +* Registering Code:: Steps to register code
|
| +* Unregistering Code:: Steps to unregister code
|
| +* Custom Debug Info:: Emit debug information in a custom format
|
|
|
| -`bc'
|
| - Backward continue. Execute the target system in reverse. No
|
| - parameter. *Note Reverse Execution::, for more information.
|
| +
|
| +File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface
|
| +
|
| +29.1 JIT Declarations
|
| +=====================
|
| +
|
| +These are the relevant struct declarations that a C program should
|
| +include to implement the interface:
|
| +
|
| + typedef enum
|
| + {
|
| + JIT_NOACTION = 0,
|
| + JIT_REGISTER_FN,
|
| + JIT_UNREGISTER_FN
|
| + } jit_actions_t;
|
| +
|
| + struct jit_code_entry
|
| + {
|
| + struct jit_code_entry *next_entry;
|
| + struct jit_code_entry *prev_entry;
|
| + const char *symfile_addr;
|
| + uint64_t symfile_size;
|
| + };
|
|
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| + struct jit_descriptor
|
| + {
|
| + uint32_t version;
|
| + /* This type should be jit_actions_t, but we use uint32_t
|
| + to be explicit about the bitwidth. */
|
| + uint32_t action_flag;
|
| + struct jit_code_entry *relevant_entry;
|
| + struct jit_code_entry *first_entry;
|
| + };
|
|
|
| -`bs'
|
| - Backward single step. Execute one instruction in reverse. No
|
| - parameter. *Note Reverse Execution::, for more information.
|
| + /* GDB puts a breakpoint in this function. */
|
| + void __attribute__((noinline)) __jit_debug_register_code() { };
|
|
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| + /* Make sure to specify the version statically, because the
|
| + debugger may check the version before we can set it. */
|
| + struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 };
|
|
|
| -`c [ADDR]'
|
| - Continue. ADDR is address to resume. If ADDR is omitted, resume
|
| - at current address.
|
| + If the JIT is multi-threaded, then it is important that the JIT
|
| +synchronize any modifications to this global data properly, which can
|
| +easily be done by putting a global mutex around modifications to these
|
| +structures.
|
|
|
| - This packet is deprecated for multi-threading support. *Note
|
| - vCont packet::.
|
| +
|
| +File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface
|
|
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +29.2 Registering Code
|
| +=====================
|
|
|
| -`C SIG[;ADDR]'
|
| - Continue with signal SIG (hex signal number). If `;ADDR' is
|
| - omitted, resume at same address.
|
| +To register code with GDB, the JIT should follow this protocol:
|
|
|
| - This packet is deprecated for multi-threading support. *Note
|
| - vCont packet::.
|
| + * Generate an object file in memory with symbols and other desired
|
| + debug information. The file must include the virtual addresses of
|
| + the sections.
|
|
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| + * Create a code entry for the file, which gives the start and size
|
| + of the symbol file.
|
|
|
| -`d'
|
| - Toggle debug flag.
|
| + * Add it to the linked list in the JIT descriptor.
|
|
|
| - Don't use this packet; instead, define a general set packet (*note
|
| - General Query Packets::).
|
| + * Point the relevant_entry field of the descriptor at the entry.
|
|
|
| -`D'
|
| -`D;PID'
|
| - The first form of the packet is used to detach GDB from the remote
|
| - system. It is sent to the remote target before GDB disconnects
|
| - via the `detach' command.
|
| + * Set `action_flag' to `JIT_REGISTER' and call
|
| + `__jit_debug_register_code'.
|
|
|
| - The second form, including a process ID, is used when multiprocess
|
| - protocol extensions are enabled (*note multiprocess extensions::),
|
| - to detach only a specific process. The PID is specified as a
|
| - big-endian hex string.
|
| + When GDB is attached and the breakpoint fires, GDB uses the
|
| +`relevant_entry' pointer so it doesn't have to walk the list looking for
|
| +new code. However, the linked list must still be maintained in order
|
| +to allow GDB to attach to a running process and still find the symbol
|
| +files.
|
|
|
| - Reply:
|
| - `OK'
|
| - for success
|
| +
|
| +File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface
|
|
|
| - `E NN'
|
| - for an error
|
| +29.3 Unregistering Code
|
| +=======================
|
|
|
| -`F RC,EE,CF;XX'
|
| - A reply from GDB to an `F' packet sent by the target. This is
|
| - part of the File-I/O protocol extension. *Note File-I/O Remote
|
| - Protocol Extension::, for the specification.
|
| +If code is freed, then the JIT should use the following protocol:
|
|
|
| -`g'
|
| - Read general registers.
|
| + * Remove the code entry corresponding to the code from the linked
|
| + list.
|
|
|
| - Reply:
|
| - `XX...'
|
| - Each byte of register data is described by two hex digits.
|
| - The bytes with the register are transmitted in target byte
|
| - order. The size of each register and their position within
|
| - the `g' packet are determined by the GDB internal gdbarch
|
| - functions `DEPRECATED_REGISTER_RAW_SIZE' and
|
| - `gdbarch_register_name'. The specification of several
|
| - standard `g' packets is specified below.
|
| + * Point the `relevant_entry' field of the descriptor at the code
|
| + entry.
|
|
|
| - When reading registers from a trace frame (*note Using the
|
| - Collected Data: Analyze Collected Data.), the stub may also
|
| - return a string of literal `x''s in place of the register
|
| - data digits, to indicate that the corresponding register has
|
| - not been collected, thus its value is unavailable. For
|
| - example, for an architecture with 4 registers of 4 bytes
|
| - each, the following reply indicates to GDB that registers 0
|
| - and 2 have not been collected, while registers 1 and 3 have
|
| - been collected, and both have zero value:
|
| + * Set `action_flag' to `JIT_UNREGISTER' and call
|
| + `__jit_debug_register_code'.
|
|
|
| - -> `g'
|
| - <- `xxxxxxxx00000000xxxxxxxx00000000'
|
| + If the JIT frees or recompiles code without unregistering it, then
|
| +GDB and the JIT will leak the memory used for the associated symbol
|
| +files.
|
|
|
| - `E NN'
|
| - for an error.
|
| +
|
| +File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface
|
|
|
| -`G XX...'
|
| - Write general registers. *Note read registers packet::, for a
|
| - description of the XX... data.
|
| +29.4 Custom Debug Info
|
| +======================
|
|
|
| - Reply:
|
| - `OK'
|
| - for success
|
| +Generating debug information in platform-native file formats (like ELF
|
| +or COFF) may be an overkill for JIT compilers; especially if all the
|
| +debug info is used for is displaying a meaningful backtrace. The issue
|
| +can be resolved by having the JIT writers decide on a debug info format
|
| +and also provide a reader that parses the debug info generated by the
|
| +JIT compiler. This section gives a brief overview on writing such a
|
| +parser. More specific details can be found in the source file
|
| +`gdb/jit-reader.in', which is also installed as a header at
|
| +`INCLUDEDIR/gdb/jit-reader.h' for easy inclusion.
|
| +
|
| + The reader is implemented as a shared object (so this functionality
|
| +is not available on platforms which don't allow loading shared objects
|
| +at runtime). Two GDB commands, `jit-reader-load' and
|
| +`jit-reader-unload' are provided, to be used to load and unload the
|
| +readers from a preconfigured directory. Once loaded, the shared object
|
| +is used the parse the debug information emitted by the JIT compiler.
|
|
|
| - `E NN'
|
| - for an error
|
| +* Menu:
|
|
|
| -`H OP THREAD-ID'
|
| - Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
|
| - OP depends on the operation to be performed: it should be `c' for
|
| - step and continue operations (note that this is deprecated,
|
| - supporting the `vCont' command is a better option), `g' for other
|
| - operations. The thread designator THREAD-ID has the format and
|
| - interpretation described in *Note thread-id syntax::.
|
| +* Using JIT Debug Info Readers:: How to use supplied readers correctly
|
| +* Writing JIT Debug Info Readers:: Creating a debug-info reader
|
|
|
| - Reply:
|
| - `OK'
|
| - for success
|
| +
|
| +File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info
|
|
|
| - `E NN'
|
| - for an error
|
| +29.4.1 Using JIT Debug Info Readers
|
| +-----------------------------------
|
|
|
| -`i [ADDR[,NNN]]'
|
| - Step the remote target by a single clock cycle. If `,NNN' is
|
| - present, cycle step NNN cycles. If ADDR is present, cycle step
|
| - starting at that address.
|
| +Readers can be loaded and unloaded using the `jit-reader-load' and
|
| +`jit-reader-unload' commands.
|
|
|
| -`I'
|
| - Signal, then cycle step. *Note step with signal packet::. *Note
|
| - cycle step packet::.
|
| +`jit-reader-load READER'
|
| + Load the JIT reader named READER. READER is a shared object
|
| + specified as either an absolute or a relative file name. In the
|
| + latter case, GDB will try to load the reader from a pre-configured
|
| + directory, usually `LIBDIR/gdb/' on a UNIX system (here LIBDIR is
|
| + the system library directory, often `/usr/local/lib').
|
|
|
| -`k'
|
| - Kill request.
|
| + Only one reader can be active at a time; trying to load a second
|
| + reader when one is already loaded will result in GDB reporting an
|
| + error. A new JIT reader can be loaded by first unloading the
|
| + current one using `jit-reader-unload' and then invoking
|
| + `jit-reader-load'.
|
|
|
| - FIXME: _There is no description of how to operate when a specific
|
| - thread context has been selected (i.e. does 'k' kill only that
|
| - thread?)_.
|
| +`jit-reader-unload'
|
| + Unload the currently loaded JIT reader.
|
|
|
| -`m ADDR,LENGTH'
|
| - Read LENGTH bytes of memory starting at address ADDR. Note that
|
| - ADDR may not be aligned to any particular boundary.
|
|
|
| - The stub need not use any particular size or alignment when
|
| - gathering data from memory for the response; even if ADDR is
|
| - word-aligned and LENGTH is a multiple of the word size, the stub
|
| - is free to use byte accesses, or not. For this reason, this
|
| - packet may not be suitable for accessing memory-mapped I/O devices.
|
| +
|
| +File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info
|
|
|
| - Reply:
|
| - `XX...'
|
| - Memory contents; each byte is transmitted as a two-digit
|
| - hexadecimal number. The reply may contain fewer bytes than
|
| - requested if the server was able to read only part of the
|
| - region of memory.
|
| +29.4.2 Writing JIT Debug Info Readers
|
| +-------------------------------------
|
|
|
| - `E NN'
|
| - NN is errno
|
| +As mentioned, a reader is essentially a shared object conforming to a
|
| +certain ABI. This ABI is described in `jit-reader.h'.
|
|
|
| -`M ADDR,LENGTH:XX...'
|
| - Write LENGTH bytes of memory starting at address ADDR. XX... is
|
| - the data; each byte is transmitted as a two-digit hexadecimal
|
| - number.
|
| + `jit-reader.h' defines the structures, macros and functions required
|
| +to write a reader. It is installed (along with GDB), in
|
| +`INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory.
|
|
|
| - Reply:
|
| - `OK'
|
| - for success
|
| + Readers need to be released under a GPL compatible license. A reader
|
| +can be declared as released under such a license by placing the macro
|
| +`GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file.
|
|
|
| - `E NN'
|
| - for an error (this includes the case where only part of the
|
| - data was written).
|
| + The entry point for readers is the symbol `gdb_init_reader', which
|
| +is expected to be a function with the prototype
|
|
|
| -`p N'
|
| - Read the value of register N; N is in hex. *Note read registers
|
| - packet::, for a description of how the returned register value is
|
| - encoded.
|
| + extern struct gdb_reader_funcs *gdb_init_reader (void);
|
|
|
| - Reply:
|
| - `XX...'
|
| - the register's value
|
| + `struct gdb_reader_funcs' contains a set of pointers to callback
|
| +functions. These functions are executed to read the debug info
|
| +generated by the JIT compiler (`read'), to unwind stack frames
|
| +(`unwind') and to create canonical frame IDs (`get_Frame_id'). It also
|
| +has a callback that is called when the reader is being unloaded
|
| +(`destroy'). The struct looks like this
|
|
|
| - `E NN'
|
| - for an error
|
| + struct gdb_reader_funcs
|
| + {
|
| + /* Must be set to GDB_READER_INTERFACE_VERSION. */
|
| + int reader_version;
|
|
|
| - `'
|
| - Indicating an unrecognized QUERY.
|
| + /* For use by the reader. */
|
| + void *priv_data;
|
|
|
| -`P N...=R...'
|
| - Write register N... with value R.... The register number N is in
|
| - hexadecimal, and R... contains two hex digits for each byte in the
|
| - register (target byte order).
|
| + gdb_read_debug_info *read;
|
| + gdb_unwind_frame *unwind;
|
| + gdb_get_frame_id *get_frame_id;
|
| + gdb_destroy_reader *destroy;
|
| + };
|
|
|
| - Reply:
|
| - `OK'
|
| - for success
|
| + The callbacks are provided with another set of callbacks by GDB to
|
| +do their job. For `read', these callbacks are passed in a `struct
|
| +gdb_symbol_callbacks' and for `unwind' and `get_frame_id', in a `struct
|
| +gdb_unwind_callbacks'. `struct gdb_symbol_callbacks' has callbacks to
|
| +create new object files and new symbol tables inside those object
|
| +files. `struct gdb_unwind_callbacks' has callbacks to read registers
|
| +off the current frame and to write out the values of the registers in
|
| +the previous frame. Both have a callback (`target_read') to read bytes
|
| +off the target's address space.
|
|
|
| - `E NN'
|
| - for an error
|
| +
|
| +File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top
|
| +
|
| +30 In-Process Agent
|
| +*******************
|
| +
|
| +The traditional debugging model is conceptually low-speed, but works
|
| +fine, because most bugs can be reproduced in debugging-mode execution.
|
| +However, as multi-core or many-core processors are becoming mainstream,
|
| +and multi-threaded programs become more and more popular, there should
|
| +be more and more bugs that only manifest themselves at normal-mode
|
| +execution, for example, thread races, because debugger's interference
|
| +with the program's timing may conceal the bugs. On the other hand, in
|
| +some applications, it is not feasible for the debugger to interrupt the
|
| +program's execution long enough for the developer to learn anything
|
| +helpful about its behavior. If the program's correctness depends on
|
| +its real-time behavior, delays introduced by a debugger might cause the
|
| +program to fail, even when the code itself is correct. It is useful to
|
| +be able to observe the program's behavior without interrupting it.
|
|
|
| -`q NAME PARAMS...'
|
| -`Q NAME PARAMS...'
|
| - General query (`q') and set (`Q'). These packets are described
|
| - fully in *Note General Query Packets::.
|
| + Therefore, traditional debugging model is too intrusive to reproduce
|
| +some bugs. In order to reduce the interference with the program, we can
|
| +reduce the number of operations performed by debugger. The "In-Process
|
| +Agent", a shared library, is running within the same process with
|
| +inferior, and is able to perform some debugging operations itself. As
|
| +a result, debugger is only involved when necessary, and performance of
|
| +debugging can be improved accordingly. Note that interference with
|
| +program can be reduced but can't be removed completely, because the
|
| +in-process agent will still stop or slow down the program.
|
| +
|
| + The in-process agent can interpret and execute Agent Expressions
|
| +(*note Agent Expressions::) during performing debugging operations. The
|
| +agent expressions can be used for different purposes, such as collecting
|
| +data in tracepoints, and condition evaluation in breakpoints.
|
| +
|
| + You can control whether the in-process agent is used as an aid for
|
| +debugging with the following commands:
|
| +
|
| +`set agent on'
|
| + Causes the in-process agent to perform some operations on behalf
|
| + of the debugger. Just which operations requested by the user will
|
| + be done by the in-process agent depends on the its capabilities.
|
| + For example, if you request to evaluate breakpoint conditions in
|
| + the in-process agent, and the in-process agent has such capability
|
| + as well, then breakpoint conditions will be evaluated in the
|
| + in-process agent.
|
| +
|
| +`set agent off'
|
| + Disables execution of debugging operations by the in-process
|
| + agent. All of the operations will be performed by GDB.
|
| +
|
| +`show agent'
|
| + Display the current setting of execution of debugging operations by
|
| + the in-process agent.
|
|
|
| -`r'
|
| - Reset the entire system.
|
| +* Menu:
|
|
|
| - Don't use this packet; use the `R' packet instead.
|
| +* In-Process Agent Protocol::
|
|
|
| -`R XX'
|
| - Restart the program being debugged. XX, while needed, is ignored.
|
| - This packet is only available in extended mode (*note extended
|
| - mode::).
|
| +
|
| +File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent
|
|
|
| - The `R' packet has no reply.
|
| +30.1 In-Process Agent Protocol
|
| +==============================
|
|
|
| -`s [ADDR]'
|
| - Single step. ADDR is the address at which to resume. If ADDR is
|
| - omitted, resume at same address.
|
| +The in-process agent is able to communicate with both GDB and GDBserver
|
| +(*note In-Process Agent::). This section documents the protocol used
|
| +for communications between GDB or GDBserver and the IPA. In general,
|
| +GDB or GDBserver sends commands (*note IPA Protocol Commands::) and
|
| +data to in-process agent, and then in-process agent replies back with
|
| +the return result of the command, or some other information. The data
|
| +sent to in-process agent is composed of primitive data types, such as
|
| +4-byte or 8-byte type, and composite types, which are called objects
|
| +(*note IPA Protocol Objects::).
|
|
|
| - This packet is deprecated for multi-threading support. *Note
|
| - vCont packet::.
|
| +* Menu:
|
|
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +* IPA Protocol Objects::
|
| +* IPA Protocol Commands::
|
|
|
| -`S SIG[;ADDR]'
|
| - Step with signal. This is analogous to the `C' packet, but
|
| - requests a single-step, rather than a normal resumption of
|
| - execution.
|
| +
|
| +File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol
|
|
|
| - This packet is deprecated for multi-threading support. *Note
|
| - vCont packet::.
|
| +30.1.1 IPA Protocol Objects
|
| +---------------------------
|
|
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +The commands sent to and results received from agent may contain some
|
| +complex data types called "objects".
|
| +
|
| + The in-process agent is running on the same machine with GDB or
|
| +GDBserver, so it doesn't have to handle as much differences between two
|
| +ends as remote protocol (*note Remote Protocol::) tries to handle.
|
| +However, there are still some differences of two ends in two processes:
|
| +
|
| + 1. word size. On some 64-bit machines, GDB or GDBserver can be
|
| + compiled as a 64-bit executable, while in-process agent is a
|
| + 32-bit one.
|
| +
|
| + 2. ABI. Some machines may have multiple types of ABI, GDB or
|
| + GDBserver is compiled with one, and in-process agent is compiled
|
| + with the other one.
|
| +
|
| + Here are the IPA Protocol Objects:
|
| +
|
| + 1. agent expression object. It represents an agent expression (*note
|
| + Agent Expressions::).
|
| +
|
| + 2. tracepoint action object. It represents a tracepoint action
|
| + (*note Tracepoint Action Lists: Tracepoint Actions.) to collect
|
| + registers, memory, static trace data and to evaluate expression.
|
| +
|
| + 3. tracepoint object. It represents a tracepoint (*note
|
| + Tracepoints::).
|
| +
|
| + The following table describes important attributes of each IPA
|
| +protocol object:
|
| +
|
| +Name Size Description
|
| +---------------------------------------------------------------------------
|
| +_agent expression
|
| +object_
|
| +length 4 length of bytes code
|
| +byte code LENGTH contents of byte code
|
| +_tracepoint action
|
| +for collecting
|
| +memory_
|
| +'M' 1 type of tracepoint action
|
| +addr 8 if BASEREG is `-1', ADDR is the
|
| + address of the lowest byte to
|
| + collect, otherwise ADDR is the
|
| + offset of BASEREG for memory
|
| + collecting.
|
| +len 8 length of memory for collecting
|
| +basereg 4 the register number containing the
|
| + starting memory address for
|
| + collecting.
|
| +_tracepoint action
|
| +for collecting
|
| +registers_
|
| +'R' 1 type of tracepoint action
|
| +_tracepoint action
|
| +for collecting static
|
| +trace data_
|
| +'L' 1 type of tracepoint action
|
| +_tracepoint action
|
| +for expression
|
| +evaluation_
|
| +'X' 1 type of tracepoint action
|
| +agent expression length of *note agent expression object::
|
| +_tracepoint object_
|
| +number 4 number of tracepoint
|
| +address 8 address of tracepoint inserted on
|
| +type 4 type of tracepoint
|
| +enabled 1 enable or disable of tracepoint
|
| +step_count 8 step
|
| +pass_count 8 pass
|
| +numactions 4 number of tracepoint actions
|
| +hit count 8 hit count
|
| +trace frame usage 8 trace frame usage
|
| +compiled_cond 8 compiled condition
|
| +orig_size 8 orig size
|
| +condition 4 if zero if condition is NULL,
|
| + condition is otherwise is *note agent expression
|
| + NULL object::
|
| + otherwise
|
| + length of
|
| + *note agent
|
| + expression
|
| + object::
|
| +actions variable numactions number of *note
|
| + tracepoint action object::
|
|
|
| -`t ADDR:PP,MM'
|
| - Search backwards starting at address ADDR for a match with pattern
|
| - PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3
|
| - digits.
|
| +
|
| +File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol
|
|
|
| -`T THREAD-ID'
|
| - Find out if the thread THREAD-ID is alive. *Note thread-id
|
| - syntax::.
|
| +30.1.2 IPA Protocol Commands
|
| +----------------------------
|
|
|
| - Reply:
|
| - `OK'
|
| - thread is still alive
|
| +The spaces in each command are delimiters to ease reading this commands
|
| +specification. They don't exist in real commands.
|
| +
|
| +`FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD'
|
| + Installs a new fast tracepoint described by TRACEPOINT_OBJECT
|
| + (*note tracepoint object::). GDB_JUMP_PAD_HEAD, 8-byte long, is
|
| + the head of "jumppad", which is used to jump to data collection
|
| + routine in IPA finally.
|
| +
|
| + Replies:
|
| + `OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP'
|
| + TARGET_ADDRESS is address of tracepoint in the inferior.
|
| + GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of
|
| + TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. FJUMP
|
| + contains a sequence of instructions jump to jumppad entry.
|
| + FJUMP_SIZE, 4-byte long, is the size of FJUMP.
|
|
|
| `E NN'
|
| - thread is dead
|
| + for an error
|
|
|
| -`v'
|
| - Packets starting with `v' are identified by a multi-letter name,
|
| - up to the first `;' or `?' (or the end of the packet).
|
|
|
| -`vAttach;PID'
|
| - Attach to a new process with the specified process ID PID. The
|
| - process ID is a hexadecimal integer identifying the process. In
|
| - all-stop mode, all threads in the attached process are stopped; in
|
| - non-stop mode, it may be attached without being stopped if that is
|
| - supported by the target.
|
| +`close'
|
| + Closes the in-process agent. This command is sent when GDB or
|
| + GDBserver is about to kill inferiors.
|
|
|
| - This packet is only available in extended mode (*note extended
|
| - mode::).
|
| +`qTfSTM'
|
| + *Note qTfSTM::.
|
|
|
| - Reply:
|
| +`qTsSTM'
|
| + *Note qTsSTM::.
|
| +
|
| +`qTSTMat'
|
| + *Note qTSTMat::.
|
| +
|
| +`probe_marker_at:ADDRESS'
|
| + Asks in-process agent to probe the marker at ADDRESS.
|
| +
|
| + Replies:
|
| `E NN'
|
| for an error
|
|
|
| - `Any stop packet'
|
| - for success in all-stop mode (*note Stop Reply Packets::)
|
| +`unprobe_marker_at:ADDRESS'
|
| + Asks in-process agent to unprobe the marker at ADDRESS.
|
|
|
| - `OK'
|
| - for success in non-stop mode (*note Remote Non-Stop::)
|
| +
|
| +File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top
|
|
|
| -`vCont[;ACTION[:THREAD-ID]]...'
|
| - Resume the inferior, specifying different actions for each thread.
|
| - If an action is specified with no THREAD-ID, then it is applied to
|
| - any threads that don't have a specific action specified; if no
|
| - default action is specified then other threads should remain
|
| - stopped in all-stop mode and in their current state in non-stop
|
| - mode. Specifying multiple default actions is an error; specifying
|
| - no actions is also an error. Thread IDs are specified using the
|
| - syntax described in *Note thread-id syntax::.
|
| +31 Reporting Bugs in GDB
|
| +************************
|
|
|
| - Currently supported actions are:
|
| +Your bug reports play an essential role in making GDB reliable.
|
|
|
| - `c'
|
| - Continue.
|
| + Reporting a bug may help you by bringing a solution to your problem,
|
| +or it may not. But in any case the principal function of a bug report
|
| +is to help the entire community by making the next version of GDB work
|
| +better. Bug reports are your contribution to the maintenance of GDB.
|
|
|
| - `C SIG'
|
| - Continue with signal SIG. The signal SIG should be two hex
|
| - digits.
|
| + In order for a bug report to serve its purpose, you must include the
|
| +information that enables us to fix the bug.
|
|
|
| - `s'
|
| - Step.
|
| +* Menu:
|
|
|
| - `S SIG'
|
| - Step with signal SIG. The signal SIG should be two hex
|
| - digits.
|
| +* Bug Criteria:: Have you found a bug?
|
| +* Bug Reporting:: How to report bugs
|
|
|
| - `t'
|
| - Stop.
|
| +
|
| +File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs
|
|
|
| - The optional argument ADDR normally associated with the `c', `C',
|
| - `s', and `S' packets is not supported in `vCont'.
|
| +31.1 Have You Found a Bug?
|
| +==========================
|
|
|
| - The `t' action is only relevant in non-stop mode (*note Remote
|
| - Non-Stop::) and may be ignored by the stub otherwise. A stop
|
| - reply should be generated for any affected thread not already
|
| - stopped. When a thread is stopped by means of a `t' action, the
|
| - corresponding stop reply should indicate that the thread has
|
| - stopped with signal `0', regardless of whether the target uses
|
| - some other signal as an implementation detail.
|
| +If you are not sure whether you have found a bug, here are some
|
| +guidelines:
|
|
|
| - The stub must support `vCont' if it reports support for
|
| - multiprocess extensions (*note multiprocess extensions::). Note
|
| - that in this case `vCont' actions can be specified to apply to all
|
| - threads in a process by using the `pPID.-1' form of the THREAD-ID.
|
| + * If the debugger gets a fatal signal, for any input whatever, that
|
| + is a GDB bug. Reliable debuggers never crash.
|
|
|
| - Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| + * If GDB produces an error message for valid input, that is a bug.
|
| + (Note that if you're cross debugging, the problem may also be
|
| + somewhere in the connection to the target.)
|
|
|
| -`vCont?'
|
| - Request a list of actions supported by the `vCont' packet.
|
| + * If GDB does not produce an error message for invalid input, that
|
| + is a bug. However, you should note that your idea of "invalid
|
| + input" might be our idea of "an extension" or "support for
|
| + traditional practice".
|
|
|
| - Reply:
|
| - `vCont[;ACTION...]'
|
| - The `vCont' packet is supported. Each ACTION is a supported
|
| - command in the `vCont' packet.
|
| + * If you are an experienced user of debugging tools, your suggestions
|
| + for improvement of GDB are welcome in any case.
|
|
|
| - `'
|
| - The `vCont' packet is not supported.
|
| +
|
| +File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs
|
|
|
| -`vFile:OPERATION:PARAMETER...'
|
| - Perform a file operation on the target system. For details, see
|
| - *Note Host I/O Packets::.
|
| +31.2 How to Report Bugs
|
| +=======================
|
|
|
| -`vFlashErase:ADDR,LENGTH'
|
| - Direct the stub to erase LENGTH bytes of flash starting at ADDR.
|
| - The region may enclose any number of flash blocks, but its start
|
| - and end must fall on block boundaries, as indicated by the flash
|
| - block size appearing in the memory map (*note Memory Map
|
| - Format::). GDB groups flash memory programming operations
|
| - together, and sends a `vFlashDone' request after each group; the
|
| - stub is allowed to delay erase operation until the `vFlashDone'
|
| - packet is received.
|
| +A number of companies and individuals offer support for GNU products.
|
| +If you obtained GDB from a support organization, we recommend you
|
| +contact that organization first.
|
| +
|
| + You can find contact information for many support companies and
|
| +individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
|
| +
|
| + In any event, we also recommend that you submit bug reports for GDB.
|
| +The preferred method is to submit them directly using GDB's Bugs web
|
| +page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the
|
| +e-mail gateway <bug-gdb@gnu.org> can be used.
|
| +
|
| + *Do not send bug reports to `info-gdb', or to `help-gdb', or to any
|
| +newsgroups.* Most users of GDB do not want to receive bug reports.
|
| +Those that do have arranged to receive `bug-gdb'.
|
| +
|
| + The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
|
| +serves as a repeater. The mailing list and the newsgroup carry exactly
|
| +the same messages. Often people think of posting bug reports to the
|
| +newsgroup instead of mailing them. This appears to work, but it has one
|
| +problem which can be crucial: a newsgroup posting often lacks a mail
|
| +path back to the sender. Thus, if we need to ask for more information,
|
| +we may be unable to reach you. For this reason, it is better to send
|
| +bug reports to the mailing list.
|
| +
|
| + The fundamental principle of reporting bugs usefully is this:
|
| +*report all the facts*. If you are not sure whether to state a fact or
|
| +leave it out, state it!
|
| +
|
| + Often people omit facts because they think they know what causes the
|
| +problem and assume that some details do not matter. Thus, you might
|
| +assume that the name of the variable you use in an example does not
|
| +matter. Well, probably it does not, but one cannot be sure. Perhaps
|
| +the bug is a stray memory reference which happens to fetch from the
|
| +location where that name is stored in memory; perhaps, if the name were
|
| +different, the contents of that location would fool the debugger into
|
| +doing the right thing despite the bug. Play it safe and give a
|
| +specific, complete example. That is the easiest thing for you to do,
|
| +and the most helpful.
|
| +
|
| + Keep in mind that the purpose of a bug report is to enable us to fix
|
| +the bug. It may be that the bug has been reported previously, but
|
| +neither you nor we can know that unless your bug report is complete and
|
| +self-contained.
|
| +
|
| + Sometimes people give a few sketchy facts and ask, "Does this ring a
|
| +bell?" Those bug reports are useless, and we urge everyone to _refuse
|
| +to respond to them_ except to chide the sender to report bugs properly.
|
| +
|
| + To enable us to fix the bug, you should include all these things:
|
| +
|
| + * The version of GDB. GDB announces it if you start with no
|
| + arguments; you can also print it at any time using `show version'.
|
| +
|
| + Without this, we will not know whether there is any point in
|
| + looking for the bug in the current version of GDB.
|
| +
|
| + * The type of machine you are using, and the operating system name
|
| + and version number.
|
| +
|
| + * The details of the GDB build-time configuration. GDB shows these
|
| + details if you invoke it with the `--configuration' command-line
|
| + option, or if you type `show configuration' at GDB's prompt.
|
| +
|
| + * What compiler (and its version) was used to compile GDB--e.g.
|
| + "gcc-2.8.1".
|
| +
|
| + * What compiler (and its version) was used to compile the program
|
| + you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
|
| + C Compiler". For GCC, you can say `gcc --version' to get this
|
| + information; for other compilers, see the documentation for those
|
| + compilers.
|
| +
|
| + * The command arguments you gave the compiler to compile your
|
| + example and observe the bug. For example, did you use `-O'? To
|
| + guarantee you will not omit something important, list them all. A
|
| + copy of the Makefile (or the output from make) is sufficient.
|
| +
|
| + If we were to try to guess the arguments, we would probably guess
|
| + wrong and then we might not encounter the bug.
|
| +
|
| + * A complete input script, and all necessary source files, that will
|
| + reproduce the bug.
|
| +
|
| + * A description of what behavior you observe that you believe is
|
| + incorrect. For example, "It gets a fatal signal."
|
| +
|
| + Of course, if the bug is that GDB gets a fatal signal, then we
|
| + will certainly notice it. But if the bug is incorrect output, we
|
| + might not notice unless it is glaringly wrong. You might as well
|
| + not give us a chance to make a mistake.
|
| +
|
| + Even if the problem you experience is a fatal signal, you should
|
| + still say so explicitly. Suppose something strange is going on,
|
| + such as, your copy of GDB is out of synch, or you have encountered
|
| + a bug in the C library on your system. (This has happened!) Your
|
| + copy might crash and ours would not. If you told us to expect a
|
| + crash, then when ours fails to crash, we would know that the bug
|
| + was not happening for us. If you had not told us to expect a
|
| + crash, then we would not be able to draw any conclusion from our
|
| + observations.
|
| +
|
| + To collect all this information, you can use a session recording
|
| + program such as `script', which is available on many Unix systems.
|
| + Just run your GDB session inside `script' and then include the
|
| + `typescript' file with your bug report.
|
| +
|
| + Another way to record a GDB session is to run GDB inside Emacs and
|
| + then save the entire buffer to a file.
|
| +
|
| + * If you wish to suggest changes to the GDB source, send us context
|
| + diffs. If you even discuss something in the GDB source, refer to
|
| + it by context, not by line number.
|
| +
|
| + The line numbers in our development sources will not match those
|
| + in your sources. Your line numbers would convey no useful
|
| + information to us.
|
| +
|
| +
|
| + Here are some things that are not necessary:
|
| +
|
| + * A description of the envelope of the bug.
|
|
|
| - Reply:
|
| - `OK'
|
| - for success
|
| + Often people who encounter a bug spend a lot of time investigating
|
| + which changes to the input file will make the bug go away and which
|
| + changes will not affect it.
|
|
|
| - `E NN'
|
| - for an error
|
| + This is often time consuming and not very useful, because the way
|
| + we will find the bug is by running a single example under the
|
| + debugger with breakpoints, not by pure deduction from a series of
|
| + examples. We recommend that you save your time for something else.
|
|
|
| -`vFlashWrite:ADDR:XX...'
|
| - Direct the stub to write data to flash address ADDR. The data is
|
| - passed in binary form using the same encoding as for the `X'
|
| - packet (*note Binary Data::). The memory ranges specified by
|
| - `vFlashWrite' packets preceding a `vFlashDone' packet must not
|
| - overlap, and must appear in order of increasing addresses
|
| - (although `vFlashErase' packets for higher addresses may already
|
| - have been received; the ordering is guaranteed only between
|
| - `vFlashWrite' packets). If a packet writes to an address that was
|
| - neither erased by a preceding `vFlashErase' packet nor by some
|
| - other target-specific method, the results are unpredictable.
|
| + Of course, if you can find a simpler example to report _instead_
|
| + of the original one, that is a convenience for us. Errors in the
|
| + output will be easier to spot, running under the debugger will take
|
| + less time, and so on.
|
|
|
| - Reply:
|
| - `OK'
|
| - for success
|
| + However, simplification is not vital; if you do not want to do
|
| + this, report the bug anyway and send us the entire test case you
|
| + used.
|
|
|
| - `E.memtype'
|
| - for vFlashWrite addressing non-flash memory
|
| + * A patch for the bug.
|
|
|
| - `E NN'
|
| - for an error
|
| + A patch for the bug does help us if it is a good one. But do not
|
| + omit the necessary information, such as the test case, on the
|
| + assumption that a patch is all we need. We might see problems
|
| + with your patch and decide to fix the problem another way, or we
|
| + might not understand it at all.
|
|
|
| -`vFlashDone'
|
| - Indicate to the stub that flash programming operation is finished.
|
| - The stub is permitted to delay or batch the effects of a group of
|
| - `vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
|
| - packet is received. The contents of the affected regions of flash
|
| - memory are unpredictable until the `vFlashDone' request is
|
| - completed.
|
| + Sometimes with a program as complicated as GDB it is very hard to
|
| + construct an example that will make the program follow a certain
|
| + path through the code. If you do not send us the example, we will
|
| + not be able to construct one, so we will not be able to verify
|
| + that the bug is fixed.
|
|
|
| -`vKill;PID'
|
| - Kill the process with the specified process ID. PID is a
|
| - hexadecimal integer identifying the process. This packet is used
|
| - in preference to `k' when multiprocess protocol extensions are
|
| - supported; see *Note multiprocess extensions::.
|
| + And if we cannot understand what bug you are trying to fix, or why
|
| + your patch should be an improvement, we will not install it. A
|
| + test case will help us to understand.
|
|
|
| - Reply:
|
| - `E NN'
|
| - for an error
|
| + * A guess about what the bug is or what it depends on.
|
|
|
| - `OK'
|
| - for success
|
| + Such guesses are usually wrong. Even we cannot guess right about
|
| + such things without first using the debugger to find the facts.
|
|
|
| -`vRun;FILENAME[;ARGUMENT]...'
|
| - Run the program FILENAME, passing it each ARGUMENT on its command
|
| - line. The file and arguments are hex-encoded strings. If
|
| - FILENAME is an empty string, the stub may use a default program
|
| - (e.g. the last program run). The program is created in the stopped
|
| - state.
|
| +
|
| +File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top
|
|
|
| - This packet is only available in extended mode (*note extended
|
| - mode::).
|
| +32 Command Line Editing
|
| +***********************
|
|
|
| - Reply:
|
| - `E NN'
|
| - for an error
|
| +This chapter describes the basic features of the GNU command line
|
| +editing interface.
|
|
|
| - `Any stop packet'
|
| - for success (*note Stop Reply Packets::)
|
| +* Menu:
|
|
|
| -`vStopped'
|
| - In non-stop mode (*note Remote Non-Stop::), acknowledge a previous
|
| - stop reply and prompt for the stub to report another one.
|
| +* Introduction and Notation:: Notation used in this text.
|
| +* Readline Interaction:: The minimum set of commands for editing a line.
|
| +* Readline Init File:: Customizing Readline from a user's view.
|
| +* Bindable Readline Commands:: A description of most of the Readline commands
|
| + available for binding
|
| +* Readline vi Mode:: A short description of how to make Readline
|
| + behave like the vi editor.
|
|
|
| - Reply:
|
| - `Any stop packet'
|
| - if there is another unreported stop event (*note Stop Reply
|
| - Packets::)
|
| +
|
| +File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
|
|
|
| - `OK'
|
| - if there are no unreported stop events
|
| +32.1 Introduction to Line Editing
|
| +=================================
|
|
|
| -`X ADDR,LENGTH:XX...'
|
| - Write data to memory, where the data is transmitted in binary.
|
| - ADDR is address, LENGTH is number of bytes, `XX...' is binary data
|
| - (*note Binary Data::).
|
| +The following paragraphs describe the notation used to represent
|
| +keystrokes.
|
|
|
| - Reply:
|
| - `OK'
|
| - for success
|
| + The text `C-k' is read as `Control-K' and describes the character
|
| +produced when the <k> key is pressed while the Control key is depressed.
|
|
|
| - `E NN'
|
| - for an error
|
| + The text `M-k' is read as `Meta-K' and describes the character
|
| +produced when the Meta key (if you have one) is depressed, and the <k>
|
| +key is pressed. The Meta key is labeled <ALT> on many keyboards. On
|
| +keyboards with two keys labeled <ALT> (usually to either side of the
|
| +space bar), the <ALT> on the left side is generally set to work as a
|
| +Meta key. The <ALT> key on the right may also be configured to work as
|
| +a Meta key or may be configured as some other modifier, such as a
|
| +Compose key for typing accented characters.
|
|
|
| -`z TYPE,ADDR,KIND'
|
| -`Z TYPE,ADDR,KIND'
|
| - Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
|
| - starting at address ADDRESS of kind KIND.
|
| + If you do not have a Meta or <ALT> key, or another key working as a
|
| +Meta key, the identical keystroke can be generated by typing <ESC>
|
| +_first_, and then typing <k>. Either process is known as "metafying"
|
| +the <k> key.
|
|
|
| - Each breakpoint and watchpoint packet TYPE is documented
|
| - separately.
|
| + The text `M-C-k' is read as `Meta-Control-k' and describes the
|
| +character produced by "metafying" `C-k'.
|
|
|
| - _Implementation notes: A remote target shall return an empty string
|
| - for an unrecognized breakpoint or watchpoint packet TYPE. A
|
| - remote target shall support either both or neither of a given
|
| - `ZTYPE...' and `zTYPE...' packet pair. To avoid potential
|
| - problems with duplicate packets, the operations should be
|
| - implemented in an idempotent way._
|
| + In addition, several keys have their own names. Specifically,
|
| +<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
|
| +when seen in this text, or in an init file (*note Readline Init File::).
|
| +If your keyboard lacks a <LFD> key, typing <C-j> will produce the
|
| +desired character. The <RET> key may be labeled <Return> or <Enter> on
|
| +some keyboards.
|
|
|
| -`z0,ADDR,KIND'
|
| -`Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'
|
| - Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
|
| - of type KIND.
|
| +
|
| +File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
|
|
|
| - A memory breakpoint is implemented by replacing the instruction at
|
| - ADDR with a software breakpoint or trap instruction. The KIND is
|
| - target-specific and typically indicates the size of the breakpoint
|
| - in bytes that should be inserted. E.g., the ARM and MIPS can
|
| - insert either a 2 or 4 byte breakpoint. Some architectures have
|
| - additional meanings for KIND; COND_LIST is an optional list of
|
| - conditional expressions in bytecode form that should be evaluated
|
| - on the target's side. These are the conditions that should be
|
| - taken into consideration when deciding if the breakpoint trigger
|
| - should be reported back to GDBN.
|
| +32.2 Readline Interaction
|
| +=========================
|
|
|
| - The COND_LIST parameter is comprised of a series of expressions,
|
| - concatenated without separators. Each expression has the following
|
| - form:
|
| +Often during an interactive session you type in a long line of text,
|
| +only to notice that the first word on the line is misspelled. The
|
| +Readline library gives you a set of commands for manipulating the text
|
| +as you type it in, allowing you to just fix your typo, and not forcing
|
| +you to retype the majority of the line. Using these editing commands,
|
| +you move the cursor to the place that needs correction, and delete or
|
| +insert the text of the corrections. Then, when you are satisfied with
|
| +the line, you simply press <RET>. You do not have to be at the end of
|
| +the line to press <RET>; the entire line is accepted regardless of the
|
| +location of the cursor within the line.
|
|
|
| - `X LEN,EXPR'
|
| - LEN is the length of the bytecode expression and EXPR is the
|
| - actual conditional expression in bytecode form.
|
| +* Menu:
|
|
|
| +* Readline Bare Essentials:: The least you need to know about Readline.
|
| +* Readline Movement Commands:: Moving about the input line.
|
| +* Readline Killing Commands:: How to delete text, and how to get it back!
|
| +* Readline Arguments:: Giving numeric arguments to commands.
|
| +* Searching:: Searching through previous lines.
|
|
|
| - The optional CMD_LIST parameter introduces commands that may be
|
| - run on the target, rather than being reported back to GDB. The
|
| - parameter starts with a numeric flag PERSIST; if the flag is
|
| - nonzero, then the breakpoint may remain active and the commands
|
| - continue to be run even when GDB disconnects from the target.
|
| - Following this flag is a series of expressions concatenated with no
|
| - separators. Each expression has the following form:
|
| +
|
| +File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
|
|
|
| - `X LEN,EXPR'
|
| - LEN is the length of the bytecode expression and EXPR is the
|
| - actual conditional expression in bytecode form.
|
| +32.2.1 Readline Bare Essentials
|
| +-------------------------------
|
|
|
| +In order to enter characters into the line, simply type them. The typed
|
| +character appears where the cursor was, and then the cursor moves one
|
| +space to the right. If you mistype a character, you can use your erase
|
| +character to back up and delete the mistyped character.
|
|
|
| - see *Note Architecture-Specific Protocol Details::.
|
| + Sometimes you may mistype a character, and not notice the error
|
| +until you have typed several other characters. In that case, you can
|
| +type `C-b' to move the cursor to the left, and then correct your
|
| +mistake. Afterwards, you can move the cursor to the right with `C-f'.
|
|
|
| - _Implementation note: It is possible for a target to copy or move
|
| - code that contains memory breakpoints (e.g., when implementing
|
| - overlays). The behavior of this packet, in the presence of such a
|
| - target, is not defined._
|
| + When you add text in the middle of a line, you will notice that
|
| +characters to the right of the cursor are `pushed over' to make room
|
| +for the text that you have inserted. Likewise, when you delete text
|
| +behind the cursor, characters to the right of the cursor are `pulled
|
| +back' to fill in the blank space created by the removal of the text. A
|
| +list of the bare essentials for editing the text of an input line
|
| +follows.
|
|
|
| - Reply:
|
| - `OK'
|
| - success
|
| +`C-b'
|
| + Move back one character.
|
|
|
| - `'
|
| - not supported
|
| +`C-f'
|
| + Move forward one character.
|
|
|
| - `E NN'
|
| - for an error
|
| +<DEL> or <Backspace>
|
| + Delete the character to the left of the cursor.
|
|
|
| -`z1,ADDR,KIND'
|
| -`Z1,ADDR,KIND[;COND_LIST...]'
|
| - Insert (`Z1') or remove (`z1') a hardware breakpoint at address
|
| - ADDR.
|
| +`C-d'
|
| + Delete the character underneath the cursor.
|
|
|
| - A hardware breakpoint is implemented using a mechanism that is not
|
| - dependant on being able to modify the target's memory. KIND and
|
| - COND_LIST have the same meaning as in `Z0' packets.
|
| +Printing characters
|
| + Insert the character into the line at the cursor.
|
|
|
| - _Implementation note: A hardware breakpoint is not affected by code
|
| - movement._
|
| +`C-_' or `C-x C-u'
|
| + Undo the last editing command. You can undo all the way back to an
|
| + empty line.
|
|
|
| - Reply:
|
| - `OK'
|
| - success
|
| +(Depending on your configuration, the <Backspace> key be set to delete
|
| +the character to the left of the cursor and the <DEL> key set to delete
|
| +the character underneath the cursor, like `C-d', rather than the
|
| +character to the left of the cursor.)
|
|
|
| - `'
|
| - not supported
|
| +
|
| +File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
|
|
|
| - `E NN'
|
| - for an error
|
| +32.2.2 Readline Movement Commands
|
| +---------------------------------
|
|
|
| -`z2,ADDR,KIND'
|
| -`Z2,ADDR,KIND'
|
| - Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND
|
| - is interpreted as the number of bytes to watch.
|
| +The above table describes the most basic keystrokes that you need in
|
| +order to do editing of the input line. For your convenience, many
|
| +other commands have been added in addition to `C-b', `C-f', `C-d', and
|
| +<DEL>. Here are some commands for moving more rapidly about the line.
|
|
|
| - Reply:
|
| - `OK'
|
| - success
|
| +`C-a'
|
| + Move to the start of the line.
|
|
|
| - `'
|
| - not supported
|
| +`C-e'
|
| + Move to the end of the line.
|
|
|
| - `E NN'
|
| - for an error
|
| +`M-f'
|
| + Move forward a word, where a word is composed of letters and
|
| + digits.
|
|
|
| -`z3,ADDR,KIND'
|
| -`Z3,ADDR,KIND'
|
| - Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is
|
| - interpreted as the number of bytes to watch.
|
| +`M-b'
|
| + Move backward a word.
|
|
|
| - Reply:
|
| - `OK'
|
| - success
|
| +`C-l'
|
| + Clear the screen, reprinting the current line at the top.
|
|
|
| - `'
|
| - not supported
|
| + Notice how `C-f' moves forward a character, while `M-f' moves
|
| +forward a word. It is a loose convention that control keystrokes
|
| +operate on characters while meta keystrokes operate on words.
|
|
|
| - `E NN'
|
| - for an error
|
| +
|
| +File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
|
|
|
| -`z4,ADDR,KIND'
|
| -`Z4,ADDR,KIND'
|
| - Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND
|
| - is interpreted as the number of bytes to watch.
|
| +32.2.3 Readline Killing Commands
|
| +--------------------------------
|
|
|
| - Reply:
|
| - `OK'
|
| - success
|
| +"Killing" text means to delete the text from the line, but to save it
|
| +away for later use, usually by "yanking" (re-inserting) it back into
|
| +the line. (`Cut' and `paste' are more recent jargon for `kill' and
|
| +`yank'.)
|
|
|
| - `'
|
| - not supported
|
| + If the description for a command says that it `kills' text, then you
|
| +can be sure that you can get the text back in a different (or the same)
|
| +place later.
|
|
|
| - `E NN'
|
| - for an error
|
| + When you use a kill command, the text is saved in a "kill-ring".
|
| +Any number of consecutive kills save all of the killed text together, so
|
| +that when you yank it back, you get it all. The kill ring is not line
|
| +specific; the text that you killed on a previously typed line is
|
| +available to be yanked back later, when you are typing another line.
|
|
|
| + Here is the list of commands for killing text.
|
|
|
| -
|
| -File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
|
| +`C-k'
|
| + Kill the text from the current cursor position to the end of the
|
| + line.
|
|
|
| -E.3 Stop Reply Packets
|
| -======================
|
| +`M-d'
|
| + Kill from the cursor to the end of the current word, or, if between
|
| + words, to the end of the next word. Word boundaries are the same
|
| + as those used by `M-f'.
|
|
|
| -The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?'
|
| -packets can receive any of the below as a reply. Except for `?' and
|
| -`vStopped', that reply is only returned when the target halts. In the
|
| -below the exact meaning of "signal number" is defined by the header
|
| -`include/gdb/signals.h' in the GDB source code.
|
| +`M-<DEL>'
|
| + Kill from the cursor the start of the current word, or, if between
|
| + words, to the start of the previous word. Word boundaries are the
|
| + same as those used by `M-b'.
|
|
|
| - As in the description of request packets, we include spaces in the
|
| -reply templates for clarity; these are not part of the reply packet's
|
| -syntax. No GDB stop reply packet uses spaces to separate its
|
| -components.
|
| +`C-w'
|
| + Kill from the cursor to the previous whitespace. This is
|
| + different than `M-<DEL>' because the word boundaries differ.
|
|
|
| -`S AA'
|
| - The program received signal number AA (a two-digit hexadecimal
|
| - number). This is equivalent to a `T' response with no N:R pairs.
|
|
|
| -`T AA N1:R1;N2:R2;...'
|
| - The program received signal number AA (a two-digit hexadecimal
|
| - number). This is equivalent to an `S' response, except that the
|
| - `N:R' pairs can carry values of important registers and other
|
| - information directly in the stop reply packet, reducing round-trip
|
| - latency. Single-step and breakpoint traps are reported this way.
|
| - Each `N:R' pair is interpreted as follows:
|
| + Here is how to "yank" the text back into the line. Yanking means to
|
| +copy the most-recently-killed text from the kill buffer.
|
|
|
| - * If N is a hexadecimal number, it is a register number, and the
|
| - corresponding R gives that register's value. R is a series
|
| - of bytes in target byte order, with each byte given by a
|
| - two-digit hex number.
|
| +`C-y'
|
| + Yank the most recently killed text back into the buffer at the
|
| + cursor.
|
|
|
| - * If N is `thread', then R is the THREAD-ID of the stopped
|
| - thread, as specified in *Note thread-id syntax::.
|
| +`M-y'
|
| + Rotate the kill-ring, and yank the new top. You can only do this
|
| + if the prior command is `C-y' or `M-y'.
|
|
|
| - * If N is `core', then R is the hexadecimal number of the core
|
| - on which the stop event was detected.
|
| +
|
| +File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
|
|
|
| - * If N is a recognized "stop reason", it describes a more
|
| - specific event that stopped the target. The currently
|
| - defined stop reasons are listed below. AA should be `05',
|
| - the trap signal. At most one stop reason should be present.
|
| +32.2.4 Readline Arguments
|
| +-------------------------
|
|
|
| - * Otherwise, GDB should ignore this `N:R' pair and go on to the
|
| - next; this allows us to extend the protocol in the future.
|
| +You can pass numeric arguments to Readline commands. Sometimes the
|
| +argument acts as a repeat count, other times it is the sign of the
|
| +argument that is significant. If you pass a negative argument to a
|
| +command which normally acts in a forward direction, that command will
|
| +act in a backward direction. For example, to kill text back to the
|
| +start of the line, you might type `M-- C-k'.
|
| +
|
| + The general way to pass numeric arguments to a command is to type
|
| +meta digits before the command. If the first `digit' typed is a minus
|
| +sign (`-'), then the sign of the argument will be negative. Once you
|
| +have typed one meta digit to get the argument started, you can type the
|
| +remainder of the digits, and then the command. For example, to give
|
| +the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
|
| +will delete the next ten characters on the input line.
|
|
|
| - The currently defined stop reasons are:
|
| +
|
| +File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
|
| +
|
| +32.2.5 Searching for Commands in the History
|
| +--------------------------------------------
|
| +
|
| +Readline provides commands for searching through the command history
|
| +for lines containing a specified string. There are two search modes:
|
| +"incremental" and "non-incremental".
|
| +
|
| + Incremental searches begin before the user has finished typing the
|
| +search string. As each character of the search string is typed,
|
| +Readline displays the next entry from the history matching the string
|
| +typed so far. An incremental search requires only as many characters
|
| +as needed to find the desired history entry. To search backward in the
|
| +history for a particular string, type `C-r'. Typing `C-s' searches
|
| +forward through the history. The characters present in the value of
|
| +the `isearch-terminators' variable are used to terminate an incremental
|
| +search. If that variable has not been assigned a value, the <ESC> and
|
| +`C-J' characters will terminate an incremental search. `C-g' will
|
| +abort an incremental search and restore the original line. When the
|
| +search is terminated, the history entry containing the search string
|
| +becomes the current line.
|
| +
|
| + To find other matching entries in the history list, type `C-r' or
|
| +`C-s' as appropriate. This will search backward or forward in the
|
| +history for the next entry matching the search string typed so far.
|
| +Any other key sequence bound to a Readline command will terminate the
|
| +search and execute that command. For instance, a <RET> will terminate
|
| +the search and accept the line, thereby executing the command from the
|
| +history list. A movement command will terminate the search, make the
|
| +last line found the current line, and begin editing.
|
| +
|
| + Readline remembers the last incremental search string. If two
|
| +`C-r's are typed without any intervening characters defining a new
|
| +search string, any remembered search string is used.
|
| +
|
| + Non-incremental searches read the entire search string before
|
| +starting to search for matching history lines. The search string may be
|
| +typed by the user or be part of the contents of the current line.
|
|
|
| - `watch'
|
| - `rwatch'
|
| - `awatch'
|
| - The packet indicates a watchpoint hit, and R is the data
|
| - address, in hex.
|
| +
|
| +File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
|
|
|
| - `library'
|
| - The packet indicates that the loaded libraries have changed.
|
| - GDB should use `qXfer:libraries:read' to fetch a new list of
|
| - loaded libraries. R is ignored.
|
| +32.3 Readline Init File
|
| +=======================
|
|
|
| - `replaylog'
|
| - The packet indicates that the target cannot continue replaying
|
| - logged execution events, because it has reached the end (or
|
| - the beginning when executing backward) of the log. The value
|
| - of R will be either `begin' or `end'. *Note Reverse
|
| - Execution::, for more information.
|
| +Although the Readline library comes with a set of Emacs-like
|
| +keybindings installed by default, it is possible to use a different set
|
| +of keybindings. Any user can customize programs that use Readline by
|
| +putting commands in an "inputrc" file, conventionally in his home
|
| +directory. The name of this file is taken from the value of the
|
| +environment variable `INPUTRC'. If that variable is unset, the default
|
| +is `~/.inputrc'. If that file does not exist or cannot be read, the
|
| +ultimate default is `/etc/inputrc'.
|
|
|
| -`W AA'
|
| -`W AA ; process:PID'
|
| - The process exited, and AA is the exit status. This is only
|
| - applicable to certain targets.
|
| + When a program which uses the Readline library starts up, the init
|
| +file is read, and the key bindings are set.
|
|
|
| - The second form of the response, including the process ID of the
|
| - exited process, can be used only when GDB has reported support for
|
| - multiprocess protocol extensions; see *Note multiprocess
|
| - extensions::. The PID is formatted as a big-endian hex string.
|
| + In addition, the `C-x C-r' command re-reads this init file, thus
|
| +incorporating any changes that you might have made to it.
|
|
|
| -`X AA'
|
| -`X AA ; process:PID'
|
| - The process terminated with signal AA.
|
| +* Menu:
|
|
|
| - The second form of the response, including the process ID of the
|
| - terminated process, can be used only when GDB has reported support
|
| - for multiprocess protocol extensions; see *Note multiprocess
|
| - extensions::. The PID is formatted as a big-endian hex string.
|
| +* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
|
|
|
| -`O XX...'
|
| - `XX...' is hex encoding of ASCII data, to be written as the
|
| - program's console output. This can happen at any time while the
|
| - program is running and the debugger should continue to wait for
|
| - `W', `T', etc. This reply is not permitted in non-stop mode.
|
| +* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
|
|
|
| -`F CALL-ID,PARAMETER...'
|
| - CALL-ID is the identifier which says which host system call should
|
| - be called. This is just the name of the function. Translation
|
| - into the correct system call is only applicable as it's defined in
|
| - GDB. *Note File-I/O Remote Protocol Extension::, for a list of
|
| - implemented system calls.
|
| +* Sample Init File:: An example inputrc file.
|
|
|
| - `PARAMETER...' is a list of parameters as defined for this very
|
| - system call.
|
| +
|
| +File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
|
| +
|
| +32.3.1 Readline Init File Syntax
|
| +--------------------------------
|
| +
|
| +There are only a few basic constructs allowed in the Readline init
|
| +file. Blank lines are ignored. Lines beginning with a `#' are
|
| +comments. Lines beginning with a `$' indicate conditional constructs
|
| +(*note Conditional Init Constructs::). Other lines denote variable
|
| +settings and key bindings.
|
| +
|
| +Variable Settings
|
| + You can modify the run-time behavior of Readline by altering the
|
| + values of variables in Readline using the `set' command within the
|
| + init file. The syntax is simple:
|
| +
|
| + set VARIABLE VALUE
|
| +
|
| + Here, for example, is how to change from the default Emacs-like
|
| + key binding to use `vi' line editing commands:
|
| +
|
| + set editing-mode vi
|
| +
|
| + Variable names and values, where appropriate, are recognized
|
| + without regard to case. Unrecognized variable names are ignored.
|
| +
|
| + Boolean variables (those that can be set to on or off) are set to
|
| + on if the value is null or empty, ON (case-insensitive), or 1.
|
| + Any other value results in the variable being set to off.
|
| +
|
| + A great deal of run-time behavior is changeable with the following
|
| + variables.
|
| +
|
| + `bell-style'
|
| + Controls what happens when Readline wants to ring the
|
| + terminal bell. If set to `none', Readline never rings the
|
| + bell. If set to `visible', Readline uses a visible bell if
|
| + one is available. If set to `audible' (the default),
|
| + Readline attempts to ring the terminal's bell.
|
| +
|
| + `bind-tty-special-chars'
|
| + If set to `on', Readline attempts to bind the control
|
| + characters treated specially by the kernel's terminal driver
|
| + to their Readline equivalents.
|
| +
|
| + `comment-begin'
|
| + The string to insert at the beginning of the line when the
|
| + `insert-comment' command is executed. The default value is
|
| + `"#"'.
|
| +
|
| + `completion-display-width'
|
| + The number of screen columns used to display possible matches
|
| + when performing completion. The value is ignored if it is
|
| + less than 0 or greater than the terminal screen width. A
|
| + value of 0 will cause matches to be displayed one per line.
|
| + The default value is -1.
|
| +
|
| + `completion-ignore-case'
|
| + If set to `on', Readline performs filename matching and
|
| + completion in a case-insensitive fashion. The default value
|
| + is `off'.
|
| +
|
| + `completion-map-case'
|
| + If set to `on', and COMPLETION-IGNORE-CASE is enabled,
|
| + Readline treats hyphens (`-') and underscores (`_') as
|
| + equivalent when performing case-insensitive filename matching
|
| + and completion.
|
| +
|
| + `completion-prefix-display-length'
|
| + The length in characters of the common prefix of a list of
|
| + possible completions that is displayed without modification.
|
| + When set to a value greater than zero, common prefixes longer
|
| + than this value are replaced with an ellipsis when displaying
|
| + possible completions.
|
| +
|
| + `completion-query-items'
|
| + The number of possible completions that determines when the
|
| + user is asked whether the list of possibilities should be
|
| + displayed. If the number of possible completions is greater
|
| + than this value, Readline will ask the user whether or not he
|
| + wishes to view them; otherwise, they are simply listed. This
|
| + variable must be set to an integer value greater than or
|
| + equal to 0. A negative value means Readline should never ask.
|
| + The default limit is `100'.
|
| +
|
| + `convert-meta'
|
| + If set to `on', Readline will convert characters with the
|
| + eighth bit set to an ASCII key sequence by stripping the
|
| + eighth bit and prefixing an <ESC> character, converting them
|
| + to a meta-prefixed key sequence. The default value is `on'.
|
| +
|
| + `disable-completion'
|
| + If set to `On', Readline will inhibit word completion.
|
| + Completion characters will be inserted into the line as if
|
| + they had been mapped to `self-insert'. The default is `off'.
|
| +
|
| + `editing-mode'
|
| + The `editing-mode' variable controls which default set of key
|
| + bindings is used. By default, Readline starts up in Emacs
|
| + editing mode, where the keystrokes are most similar to Emacs.
|
| + This variable can be set to either `emacs' or `vi'.
|
| +
|
| + `echo-control-characters'
|
| + When set to `on', on operating systems that indicate they
|
| + support it, readline echoes a character corresponding to a
|
| + signal generated from the keyboard. The default is `on'.
|
| +
|
| + `enable-keypad'
|
| + When set to `on', Readline will try to enable the application
|
| + keypad when it is called. Some systems need this to enable
|
| + the arrow keys. The default is `off'.
|
| +
|
| + `enable-meta-key'
|
| + When set to `on', Readline will try to enable any meta
|
| + modifier key the terminal claims to support when it is
|
| + called. On many terminals, the meta key is used to send
|
| + eight-bit characters. The default is `on'.
|
| +
|
| + `expand-tilde'
|
| + If set to `on', tilde expansion is performed when Readline
|
| + attempts word completion. The default is `off'.
|
| +
|
| + `history-preserve-point'
|
| + If set to `on', the history code attempts to place the point
|
| + (the current cursor position) at the same location on each
|
| + history line retrieved with `previous-history' or
|
| + `next-history'. The default is `off'.
|
| +
|
| + `history-size'
|
| + Set the maximum number of history entries saved in the
|
| + history list. If set to zero, the number of entries in the
|
| + history list is not limited.
|
| +
|
| + `horizontal-scroll-mode'
|
| + This variable can be set to either `on' or `off'. Setting it
|
| + to `on' means that the text of the lines being edited will
|
| + scroll horizontally on a single screen line when they are
|
| + longer than the width of the screen, instead of wrapping onto
|
| + a new screen line. By default, this variable is set to `off'.
|
| +
|
| + `input-meta'
|
| + If set to `on', Readline will enable eight-bit input (it will
|
| + not clear the eighth bit in the characters it reads),
|
| + regardless of what the terminal claims it can support. The
|
| + default value is `off'. The name `meta-flag' is a synonym
|
| + for this variable.
|
| +
|
| + `isearch-terminators'
|
| + The string of characters that should terminate an incremental
|
| + search without subsequently executing the character as a
|
| + command (*note Searching::). If this variable has not been
|
| + given a value, the characters <ESC> and `C-J' will terminate
|
| + an incremental search.
|
| +
|
| + `keymap'
|
| + Sets Readline's idea of the current keymap for key binding
|
| + commands. Acceptable `keymap' names are `emacs',
|
| + `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
|
| + `vi-command', and `vi-insert'. `vi' is equivalent to
|
| + `vi-command'; `emacs' is equivalent to `emacs-standard'. The
|
| + default value is `emacs'. The value of the `editing-mode'
|
| + variable also affects the default keymap.
|
| +
|
| + `mark-directories'
|
| + If set to `on', completed directory names have a slash
|
| + appended. The default is `on'.
|
| +
|
| + `mark-modified-lines'
|
| + This variable, when set to `on', causes Readline to display an
|
| + asterisk (`*') at the start of history lines which have been
|
| + modified. This variable is `off' by default.
|
| +
|
| + `mark-symlinked-directories'
|
| + If set to `on', completed names which are symbolic links to
|
| + directories have a slash appended (subject to the value of
|
| + `mark-directories'). The default is `off'.
|
| +
|
| + `match-hidden-files'
|
| + This variable, when set to `on', causes Readline to match
|
| + files whose names begin with a `.' (hidden files) when
|
| + performing filename completion. If set to `off', the leading
|
| + `.' must be supplied by the user in the filename to be
|
| + completed. This variable is `on' by default.
|
| +
|
| + `menu-complete-display-prefix'
|
| + If set to `on', menu completion displays the common prefix of
|
| + the list of possible completions (which may be empty) before
|
| + cycling through the list. The default is `off'.
|
| +
|
| + `output-meta'
|
| + If set to `on', Readline will display characters with the
|
| + eighth bit set directly rather than as a meta-prefixed escape
|
| + sequence. The default is `off'.
|
| +
|
| + `page-completions'
|
| + If set to `on', Readline uses an internal `more'-like pager
|
| + to display a screenful of possible completions at a time.
|
| + This variable is `on' by default.
|
| +
|
| + `print-completions-horizontally'
|
| + If set to `on', Readline will display completions with matches
|
| + sorted horizontally in alphabetical order, rather than down
|
| + the screen. The default is `off'.
|
| +
|
| + `revert-all-at-newline'
|
| + If set to `on', Readline will undo all changes to history
|
| + lines before returning when `accept-line' is executed. By
|
| + default, history lines may be modified and retain individual
|
| + undo lists across calls to `readline'. The default is `off'.
|
| +
|
| + `show-all-if-ambiguous'
|
| + This alters the default behavior of the completion functions.
|
| + If set to `on', words which have more than one possible
|
| + completion cause the matches to be listed immediately instead
|
| + of ringing the bell. The default value is `off'.
|
| +
|
| + `show-all-if-unmodified'
|
| + This alters the default behavior of the completion functions
|
| + in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
|
| + `on', words which have more than one possible completion
|
| + without any possible partial completion (the possible
|
| + completions don't share a common prefix) cause the matches to
|
| + be listed immediately instead of ringing the bell. The
|
| + default value is `off'.
|
| +
|
| + `skip-completed-text'
|
| + If set to `on', this alters the default completion behavior
|
| + when inserting a single match into the line. It's only
|
| + active when performing completion in the middle of a word.
|
| + If enabled, readline does not insert characters from the
|
| + completion that match characters after point in the word
|
| + being completed, so portions of the word following the cursor
|
| + are not duplicated. For instance, if this is enabled,
|
| + attempting completion when the cursor is after the `e' in
|
| + `Makefile' will result in `Makefile' rather than
|
| + `Makefilefile', assuming there is a single possible
|
| + completion. The default value is `off'.
|
| +
|
| + `visible-stats'
|
| + If set to `on', a character denoting a file's type is
|
| + appended to the filename when listing possible completions.
|
| + The default is `off'.
|
| +
|
| +
|
| +Key Bindings
|
| + The syntax for controlling key bindings in the init file is
|
| + simple. First you need to find the name of the command that you
|
| + want to change. The following sections contain tables of the
|
| + command name, the default keybinding, if any, and a short
|
| + description of what the command does.
|
| +
|
| + Once you know the name of the command, simply place on a line in
|
| + the init file the name of the key you wish to bind the command to,
|
| + a colon, and then the name of the command. There can be no space
|
| + between the key name and the colon - that will be interpreted as
|
| + part of the key name. The name of the key can be expressed in
|
| + different ways, depending on what you find most comfortable.
|
| +
|
| + In addition to command names, readline allows keys to be bound to
|
| + a string that is inserted when the key is pressed (a MACRO).
|
| +
|
| + KEYNAME: FUNCTION-NAME or MACRO
|
| + KEYNAME is the name of a key spelled out in English. For
|
| + example:
|
| + Control-u: universal-argument
|
| + Meta-Rubout: backward-kill-word
|
| + Control-o: "> output"
|
| +
|
| + In the above example, `C-u' is bound to the function
|
| + `universal-argument', `M-DEL' is bound to the function
|
| + `backward-kill-word', and `C-o' is bound to run the macro
|
| + expressed on the right hand side (that is, to insert the text
|
| + `> output' into the line).
|
| +
|
| + A number of symbolic character names are recognized while
|
| + processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
|
| + NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
|
| +
|
| + "KEYSEQ": FUNCTION-NAME or MACRO
|
| + KEYSEQ differs from KEYNAME above in that strings denoting an
|
| + entire key sequence can be specified, by placing the key
|
| + sequence in double quotes. Some GNU Emacs style key escapes
|
| + can be used, as in the following example, but the special
|
| + character names are not recognized.
|
| +
|
| + "\C-u": universal-argument
|
| + "\C-x\C-r": re-read-init-file
|
| + "\e[11~": "Function Key 1"
|
| +
|
| + In the above example, `C-u' is again bound to the function
|
| + `universal-argument' (just as it was in the first example),
|
| + `C-x C-r' is bound to the function `re-read-init-file', and
|
| + `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function
|
| + Key 1'.
|
| +
|
| +
|
| + The following GNU Emacs style escape sequences are available when
|
| + specifying key sequences:
|
| +
|
| + `\C-'
|
| + control prefix
|
| +
|
| + `\M-'
|
| + meta prefix
|
| +
|
| + `\e'
|
| + an escape character
|
| +
|
| + `\\'
|
| + backslash
|
| +
|
| + `\"'
|
| + <">, a double quotation mark
|
| +
|
| + `\''
|
| + <'>, a single quote or apostrophe
|
| +
|
| + In addition to the GNU Emacs style escape sequences, a second set
|
| + of backslash escapes is available:
|
| +
|
| + `\a'
|
| + alert (bell)
|
| +
|
| + `\b'
|
| + backspace
|
| +
|
| + `\d'
|
| + delete
|
|
|
| - The target replies with this packet when it expects GDB to call a
|
| - host system call on behalf of the target. GDB replies with an
|
| - appropriate `F' packet and keeps up waiting for the next reply
|
| - packet from the target. The latest `C', `c', `S' or `s' action is
|
| - expected to be continued. *Note File-I/O Remote Protocol
|
| - Extension::, for more details.
|
| + `\f'
|
| + form feed
|
|
|
| + `\n'
|
| + newline
|
|
|
| -
|
| -File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol
|
| + `\r'
|
| + carriage return
|
|
|
| -E.4 General Query Packets
|
| -=========================
|
| + `\t'
|
| + horizontal tab
|
|
|
| -Packets starting with `q' are "general query packets"; packets starting
|
| -with `Q' are "general set packets". General query and set packets are
|
| -a semi-unified form for retrieving and sending information to and from
|
| -the stub.
|
| + `\v'
|
| + vertical tab
|
|
|
| - The initial letter of a query or set packet is followed by a name
|
| -indicating what sort of thing the packet applies to. For example, GDB
|
| -may use a `qSymbol' packet to exchange symbol definitions with the
|
| -stub. These packet names follow some conventions:
|
| + `\NNN'
|
| + the eight-bit character whose value is the octal value NNN
|
| + (one to three digits)
|
|
|
| - * The name must not contain commas, colons or semicolons.
|
| + `\xHH'
|
| + the eight-bit character whose value is the hexadecimal value
|
| + HH (one or two hex digits)
|
|
|
| - * Most GDB query and set packets have a leading upper case letter.
|
| + When entering the text of a macro, single or double quotes must be
|
| + used to indicate a macro definition. Unquoted text is assumed to
|
| + be a function name. In the macro body, the backslash escapes
|
| + described above are expanded. Backslash will quote any other
|
| + character in the macro text, including `"' and `''. For example,
|
| + the following binding will make `C-x \' insert a single `\' into
|
| + the line:
|
| + "\C-x\\": "\\"
|
|
|
| - * The names of custom vendor packets should use a company prefix, in
|
| - lower case, followed by a period. For example, packets designed at
|
| - the Acme Corporation might begin with `qacme.foo' (for querying
|
| - foos) or `Qacme.bar' (for setting bars).
|
|
|
| - The name of a query or set packet should be separated from any
|
| -parameters by a `:'; the parameters themselves should be separated by
|
| -`,' or `;'. Stubs must be careful to match the full packet name, and
|
| -check for a separator or the end of the packet, in case two packet
|
| -names share a common prefix. New packets should not begin with `qC',
|
| -`qP', or `qL'(1).
|
| +
|
| +File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
|
| +
|
| +32.3.2 Conditional Init Constructs
|
| +----------------------------------
|
| +
|
| +Readline implements a facility similar in spirit to the conditional
|
| +compilation features of the C preprocessor which allows key bindings
|
| +and variable settings to be performed as the result of tests. There
|
| +are four parser directives used.
|
| +
|
| +`$if'
|
| + The `$if' construct allows bindings to be made based on the
|
| + editing mode, the terminal being used, or the application using
|
| + Readline. The text of the test extends to the end of the line; no
|
| + characters are required to isolate it.
|
| +
|
| + `mode'
|
| + The `mode=' form of the `$if' directive is used to test
|
| + whether Readline is in `emacs' or `vi' mode. This may be
|
| + used in conjunction with the `set keymap' command, for
|
| + instance, to set bindings in the `emacs-standard' and
|
| + `emacs-ctlx' keymaps only if Readline is starting out in
|
| + `emacs' mode.
|
| +
|
| + `term'
|
| + The `term=' form may be used to include terminal-specific key
|
| + bindings, perhaps to bind the key sequences output by the
|
| + terminal's function keys. The word on the right side of the
|
| + `=' is tested against both the full name of the terminal and
|
| + the portion of the terminal name before the first `-'. This
|
| + allows `sun' to match both `sun' and `sun-cmd', for instance.
|
| +
|
| + `application'
|
| + The APPLICATION construct is used to include
|
| + application-specific settings. Each program using the
|
| + Readline library sets the APPLICATION NAME, and you can test
|
| + for a particular value. This could be used to bind key
|
| + sequences to functions useful for a specific program. For
|
| + instance, the following command adds a key sequence that
|
| + quotes the current or previous word in Bash:
|
| + $if Bash
|
| + # Quote the current or previous word
|
| + "\C-xq": "\eb\"\ef\""
|
| + $endif
|
| +
|
| +`$endif'
|
| + This command, as seen in the previous example, terminates an `$if'
|
| + command.
|
| +
|
| +`$else'
|
| + Commands in this branch of the `$if' directive are executed if the
|
| + test fails.
|
| +
|
| +`$include'
|
| + This directive takes a single filename as an argument and reads
|
| + commands and bindings from that file. For example, the following
|
| + directive reads from `/etc/inputrc':
|
| + $include /etc/inputrc
|
|
|
| - Like the descriptions of the other packets, each description here
|
| -has a template showing the packet's overall syntax, followed by an
|
| -explanation of the packet's meaning. We include spaces in some of the
|
| -templates for clarity; these are not part of the packet's syntax. No
|
| -GDB packet uses spaces to separate its components.
|
| +
|
| +File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
|
| +
|
| +32.3.3 Sample Init File
|
| +-----------------------
|
| +
|
| +Here is an example of an INPUTRC file. This illustrates key binding,
|
| +variable assignment, and conditional syntax.
|
| +
|
| +
|
| + # This file controls the behaviour of line input editing for
|
| + # programs that use the GNU Readline library. Existing
|
| + # programs include FTP, Bash, and GDB.
|
| + #
|
| + # You can re-read the inputrc file with C-x C-r.
|
| + # Lines beginning with '#' are comments.
|
| + #
|
| + # First, include any systemwide bindings and variable
|
| + # assignments from /etc/Inputrc
|
| + $include /etc/Inputrc
|
| +
|
| + #
|
| + # Set various bindings for emacs mode.
|
| +
|
| + set editing-mode emacs
|
| +
|
| + $if mode=emacs
|
| +
|
| + Meta-Control-h: backward-kill-word Text after the function name is ignored
|
| +
|
| + #
|
| + # Arrow keys in keypad mode
|
| + #
|
| + #"\M-OD": backward-char
|
| + #"\M-OC": forward-char
|
| + #"\M-OA": previous-history
|
| + #"\M-OB": next-history
|
| + #
|
| + # Arrow keys in ANSI mode
|
| + #
|
| + "\M-[D": backward-char
|
| + "\M-[C": forward-char
|
| + "\M-[A": previous-history
|
| + "\M-[B": next-history
|
| + #
|
| + # Arrow keys in 8 bit keypad mode
|
| + #
|
| + #"\M-\C-OD": backward-char
|
| + #"\M-\C-OC": forward-char
|
| + #"\M-\C-OA": previous-history
|
| + #"\M-\C-OB": next-history
|
| + #
|
| + # Arrow keys in 8 bit ANSI mode
|
| + #
|
| + #"\M-\C-[D": backward-char
|
| + #"\M-\C-[C": forward-char
|
| + #"\M-\C-[A": previous-history
|
| + #"\M-\C-[B": next-history
|
| +
|
| + C-q: quoted-insert
|
| +
|
| + $endif
|
| +
|
| + # An old-style binding. This happens to be the default.
|
| + TAB: complete
|
| +
|
| + # Macros that are convenient for shell interaction
|
| + $if Bash
|
| + # edit the path
|
| + "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
|
| + # prepare to type a quoted word --
|
| + # insert open and close double quotes
|
| + # and move to just after the open quote
|
| + "\C-x\"": "\"\"\C-b"
|
| + # insert a backslash (testing backslash escapes
|
| + # in sequences and macros)
|
| + "\C-x\\": "\\"
|
| + # Quote the current or previous word
|
| + "\C-xq": "\eb\"\ef\""
|
| + # Add a binding to refresh the line, which is unbound
|
| + "\C-xr": redraw-current-line
|
| + # Edit variable on current line.
|
| + "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
|
| + $endif
|
| +
|
| + # use a visible bell if one is available
|
| + set bell-style visible
|
| +
|
| + # don't strip characters to 7 bits when reading
|
| + set input-meta on
|
| +
|
| + # allow iso-latin1 characters to be inserted rather
|
| + # than converted to prefix-meta sequences
|
| + set convert-meta off
|
| +
|
| + # display characters with the eighth bit set directly
|
| + # rather than as meta-prefixed characters
|
| + set output-meta on
|
| +
|
| + # if there are more than 150 possible completions for
|
| + # a word, ask the user if he wants to see all of them
|
| + set completion-query-items 150
|
| +
|
| + # For FTP
|
| + $if Ftp
|
| + "\C-xg": "get \M-?"
|
| + "\C-xt": "put \M-?"
|
| + "\M-.": yank-last-arg
|
| + $endif
|
|
|
| - Here are the currently defined query and set packets:
|
| +
|
| +File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
|
|
|
| -`QAgent:1'
|
| +32.4 Bindable Readline Commands
|
| +===============================
|
|
|
| -`QAgent:0'
|
| - Turn on or off the agent as a helper to perform some debugging
|
| - operations delegated from GDB (*note Control Agent::).
|
| +* Menu:
|
|
|
| -`QAllow:OP:VAL...'
|
| - Specify which operations GDB expects to request of the target, as
|
| - a semicolon-separated list of operation name and value pairs.
|
| - Possible values for OP include `WriteReg', `WriteMem',
|
| - `InsertBreak', `InsertTrace', `InsertFastTrace', and `Stop'. VAL
|
| - is either 0, indicating that GDB will not request the operation,
|
| - or 1, indicating that it may. (The target can then use this to
|
| - set up its own internals optimally, for instance if the debugger
|
| - never expects to insert breakpoints, it may not need to install
|
| - its own trap handler.)
|
| +* Commands For Moving:: Moving about the line.
|
| +* Commands For History:: Getting at previous lines.
|
| +* Commands For Text:: Commands for changing text.
|
| +* Commands For Killing:: Commands for killing and yanking.
|
| +* Numeric Arguments:: Specifying numeric arguments, repeat counts.
|
| +* Commands For Completion:: Getting Readline to do the typing for you.
|
| +* Keyboard Macros:: Saving and re-executing typed characters
|
| +* Miscellaneous Commands:: Other miscellaneous commands.
|
|
|
| -`qC'
|
| - Return the current thread ID.
|
| + This section describes Readline commands that may be bound to key
|
| +sequences. Command names without an accompanying key sequence are
|
| +unbound by default.
|
|
|
| - Reply:
|
| - `QC THREAD-ID'
|
| - Where THREAD-ID is a thread ID as documented in *Note
|
| - thread-id syntax::.
|
| + In the following descriptions, "point" refers to the current cursor
|
| +position, and "mark" refers to a cursor position saved by the
|
| +`set-mark' command. The text between the point and mark is referred to
|
| +as the "region".
|
|
|
| - `(anything else)'
|
| - Any other reply implies the old thread ID.
|
| +
|
| +File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
|
|
|
| -`qCRC:ADDR,LENGTH'
|
| - Compute the CRC checksum of a block of memory using CRC-32 defined
|
| - in IEEE 802.3. The CRC is computed byte at a time, taking the most
|
| - significant bit of each byte first. The initial pattern code
|
| - `0xffffffff' is used to ensure leading zeros affect the CRC.
|
| +32.4.1 Commands For Moving
|
| +--------------------------
|
|
|
| - _Note:_ This is the same CRC used in validating separate debug
|
| - files (*note Debugging Information in Separate Files: Separate
|
| - Debug Files.). However the algorithm is slightly different. When
|
| - validating separate debug files, the CRC is computed taking the
|
| - _least_ significant bit of each byte first, and the final result
|
| - is inverted to detect trailing zeros.
|
| +`beginning-of-line (C-a)'
|
| + Move to the start of the current line.
|
|
|
| - Reply:
|
| - `E NN'
|
| - An error (such as memory fault)
|
| +`end-of-line (C-e)'
|
| + Move to the end of the line.
|
|
|
| - `C CRC32'
|
| - The specified memory region's checksum is CRC32.
|
| +`forward-char (C-f)'
|
| + Move forward a character.
|
|
|
| -`QDisableRandomization:VALUE'
|
| - Some target operating systems will randomize the virtual address
|
| - space of the inferior process as a security feature, but provide a
|
| - feature to disable such randomization, e.g. to allow for a more
|
| - deterministic debugging experience. On such systems, this packet
|
| - with a VALUE of 1 directs the target to disable address space
|
| - randomization for processes subsequently started via `vRun'
|
| - packets, while a packet with a VALUE of 0 tells the target to
|
| - enable address space randomization.
|
| +`backward-char (C-b)'
|
| + Move back a character.
|
|
|
| - This packet is only available in extended mode (*note extended
|
| - mode::).
|
| +`forward-word (M-f)'
|
| + Move forward to the end of the next word. Words are composed of
|
| + letters and digits.
|
|
|
| - Reply:
|
| - `OK'
|
| - The request succeeded.
|
| +`backward-word (M-b)'
|
| + Move back to the start of the current or previous word. Words are
|
| + composed of letters and digits.
|
|
|
| - `E NN'
|
| - An error occurred. NN are hex digits.
|
| +`clear-screen (C-l)'
|
| + Clear the screen and redraw the current line, leaving the current
|
| + line at the top of the screen.
|
|
|
| - `'
|
| - An empty reply indicates that `QDisableRandomization' is not
|
| - supported by the stub.
|
| +`redraw-current-line ()'
|
| + Refresh the current line. By default, this is unbound.
|
|
|
| - This packet is not probed by default; the remote stub must request
|
| - it, by supplying an appropriate `qSupported' response (*note
|
| - qSupported::). This should only be done on targets that actually
|
| - support disabling address space randomization.
|
|
|
| -`qfThreadInfo'
|
| -`qsThreadInfo'
|
| - Obtain a list of all active thread IDs from the target (OS).
|
| - Since there may be too many active threads to fit into one reply
|
| - packet, this query works iteratively: it may require more than one
|
| - query/reply sequence to obtain the entire list of threads. The
|
| - first query of the sequence will be the `qfThreadInfo' query;
|
| - subsequent queries in the sequence will be the `qsThreadInfo'
|
| - query.
|
| +
|
| +File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
|
| +
|
| +32.4.2 Commands For Manipulating The History
|
| +--------------------------------------------
|
| +
|
| +`accept-line (Newline or Return)'
|
| + Accept the line regardless of where the cursor is. If this line is
|
| + non-empty, it may be added to the history list for future recall
|
| + with `add_history()'. If this line is a modified history line,
|
| + the history line is restored to its original state.
|
| +
|
| +`previous-history (C-p)'
|
| + Move `back' through the history list, fetching the previous
|
| + command.
|
| +
|
| +`next-history (C-n)'
|
| + Move `forward' through the history list, fetching the next command.
|
| +
|
| +`beginning-of-history (M-<)'
|
| + Move to the first line in the history.
|
| +
|
| +`end-of-history (M->)'
|
| + Move to the end of the input history, i.e., the line currently
|
| + being entered.
|
| +
|
| +`reverse-search-history (C-r)'
|
| + Search backward starting at the current line and moving `up'
|
| + through the history as necessary. This is an incremental search.
|
| +
|
| +`forward-search-history (C-s)'
|
| + Search forward starting at the current line and moving `down'
|
| + through the the history as necessary. This is an incremental
|
| + search.
|
| +
|
| +`non-incremental-reverse-search-history (M-p)'
|
| + Search backward starting at the current line and moving `up'
|
| + through the history as necessary using a non-incremental search
|
| + for a string supplied by the user.
|
| +
|
| +`non-incremental-forward-search-history (M-n)'
|
| + Search forward starting at the current line and moving `down'
|
| + through the the history as necessary using a non-incremental search
|
| + for a string supplied by the user.
|
| +
|
| +`history-search-forward ()'
|
| + Search forward through the history for the string of characters
|
| + between the start of the current line and the point. This is a
|
| + non-incremental search. By default, this command is unbound.
|
| +
|
| +`history-search-backward ()'
|
| + Search backward through the history for the string of characters
|
| + between the start of the current line and the point. This is a
|
| + non-incremental search. By default, this command is unbound.
|
| +
|
| +`yank-nth-arg (M-C-y)'
|
| + Insert the first argument to the previous command (usually the
|
| + second word on the previous line) at point. With an argument N,
|
| + insert the Nth word from the previous command (the words in the
|
| + previous command begin with word 0). A negative argument inserts
|
| + the Nth word from the end of the previous command. Once the
|
| + argument N is computed, the argument is extracted as if the `!N'
|
| + history expansion had been specified.
|
| +
|
| +`yank-last-arg (M-. or M-_)'
|
| + Insert last argument to the previous command (the last word of the
|
| + previous history entry). With a numeric argument, behave exactly
|
| + like `yank-nth-arg'. Successive calls to `yank-last-arg' move
|
| + back through the history list, inserting the last word (or the
|
| + word specified by the argument to the first call) of each line in
|
| + turn. Any numeric argument supplied to these successive calls
|
| + determines the direction to move through the history. A negative
|
| + argument switches the direction through the history (back or
|
| + forward). The history expansion facilities are used to extract
|
| + the last argument, as if the `!$' history expansion had been
|
| + specified.
|
|
|
| - NOTE: This packet replaces the `qL' query (see below).
|
|
|
| - Reply:
|
| - `m THREAD-ID'
|
| - A single thread ID
|
| +
|
| +File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
|
|
|
| - `m THREAD-ID,THREAD-ID...'
|
| - a comma-separated list of thread IDs
|
| +32.4.3 Commands For Changing Text
|
| +---------------------------------
|
|
|
| - `l'
|
| - (lower case letter `L') denotes end of list.
|
| +`delete-char (C-d)'
|
| + Delete the character at point. If point is at the beginning of
|
| + the line, there are no characters in the line, and the last
|
| + character typed was not bound to `delete-char', then return EOF.
|
|
|
| - In response to each query, the target will reply with a list of
|
| - one or more thread IDs, separated by commas. GDB will respond to
|
| - each reply with a request for more thread ids (using the `qs' form
|
| - of the query), until the target responds with `l' (lower-case ell,
|
| - for "last"). Refer to *Note thread-id syntax::, for the format of
|
| - the THREAD-ID fields.
|
| +`backward-delete-char (Rubout)'
|
| + Delete the character behind the cursor. A numeric argument means
|
| + to kill the characters instead of deleting them.
|
|
|
| -`qGetTLSAddr:THREAD-ID,OFFSET,LM'
|
| - Fetch the address associated with thread local storage specified
|
| - by THREAD-ID, OFFSET, and LM.
|
| +`forward-backward-delete-char ()'
|
| + Delete the character under the cursor, unless the cursor is at the
|
| + end of the line, in which case the character behind the cursor is
|
| + deleted. By default, this is not bound to a key.
|
|
|
| - THREAD-ID is the thread ID associated with the thread for which to
|
| - fetch the TLS address. *Note thread-id syntax::.
|
| +`quoted-insert (C-q or C-v)'
|
| + Add the next character typed to the line verbatim. This is how to
|
| + insert key sequences like `C-q', for example.
|
|
|
| - OFFSET is the (big endian, hex encoded) offset associated with the
|
| - thread local variable. (This offset is obtained from the debug
|
| - information associated with the variable.)
|
| +`tab-insert (M-<TAB>)'
|
| + Insert a tab character.
|
|
|
| - LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
|
| - load module associated with the thread local storage. For example,
|
| - a GNU/Linux system will pass the link map address of the shared
|
| - object associated with the thread local storage under
|
| - consideration. Other operating environments may choose to
|
| - represent the load module differently, so the precise meaning of
|
| - this parameter will vary.
|
| +`self-insert (a, b, A, 1, !, ...)'
|
| + Insert yourself.
|
|
|
| - Reply:
|
| - `XX...'
|
| - Hex encoded (big endian) bytes representing the address of
|
| - the thread local storage requested.
|
| +`transpose-chars (C-t)'
|
| + Drag the character before the cursor forward over the character at
|
| + the cursor, moving the cursor forward as well. If the insertion
|
| + point is at the end of the line, then this transposes the last two
|
| + characters of the line. Negative arguments have no effect.
|
|
|
| - `E NN'
|
| - An error occurred. NN are hex digits.
|
| +`transpose-words (M-t)'
|
| + Drag the word before point past the word after point, moving point
|
| + past that word as well. If the insertion point is at the end of
|
| + the line, this transposes the last two words on the line.
|
|
|
| - `'
|
| - An empty reply indicates that `qGetTLSAddr' is not supported
|
| - by the stub.
|
| +`upcase-word (M-u)'
|
| + Uppercase the current (or following) word. With a negative
|
| + argument, uppercase the previous word, but do not move the cursor.
|
|
|
| -`qGetTIBAddr:THREAD-ID'
|
| - Fetch address of the Windows OS specific Thread Information Block.
|
| +`downcase-word (M-l)'
|
| + Lowercase the current (or following) word. With a negative
|
| + argument, lowercase the previous word, but do not move the cursor.
|
|
|
| - THREAD-ID is the thread ID associated with the thread.
|
| +`capitalize-word (M-c)'
|
| + Capitalize the current (or following) word. With a negative
|
| + argument, capitalize the previous word, but do not move the cursor.
|
|
|
| - Reply:
|
| - `XX...'
|
| - Hex encoded (big endian) bytes representing the linear
|
| - address of the thread information block.
|
| +`overwrite-mode ()'
|
| + Toggle overwrite mode. With an explicit positive numeric argument,
|
| + switches to overwrite mode. With an explicit non-positive numeric
|
| + argument, switches to insert mode. This command affects only
|
| + `emacs' mode; `vi' mode does overwrite differently. Each call to
|
| + `readline()' starts in insert mode.
|
|
|
| - `E NN'
|
| - An error occured. This means that either the thread was not
|
| - found, or the address could not be retrieved.
|
| + In overwrite mode, characters bound to `self-insert' replace the
|
| + text at point rather than pushing the text to the right.
|
| + Characters bound to `backward-delete-char' replace the character
|
| + before point with a space.
|
|
|
| - `'
|
| - An empty reply indicates that `qGetTIBAddr' is not supported
|
| - by the stub.
|
| + By default, this command is unbound.
|
|
|
| -`qL STARTFLAG THREADCOUNT NEXTTHREAD'
|
| - Obtain thread information from RTOS. Where: STARTFLAG (one hex
|
| - digit) is one to indicate the first query and zero to indicate a
|
| - subsequent query; THREADCOUNT (two hex digits) is the maximum
|
| - number of threads the response packet can contain; and NEXTTHREAD
|
| - (eight hex digits), for subsequent queries (STARTFLAG is zero), is
|
| - returned in the response as ARGTHREAD.
|
|
|
| - Don't use this packet; use the `qfThreadInfo' query instead (see
|
| - above).
|
| +
|
| +File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
|
|
|
| - Reply:
|
| - `qM COUNT DONE ARGTHREAD THREAD...'
|
| - Where: COUNT (two hex digits) is the number of threads being
|
| - returned; DONE (one hex digit) is zero to indicate more
|
| - threads and one indicates no further threads; ARGTHREADID
|
| - (eight hex digits) is NEXTTHREAD from the request packet;
|
| - THREAD... is a sequence of thread IDs from the target.
|
| - THREADID (eight hex digits). See
|
| - `remote.c:parse_threadlist_response()'.
|
| +32.4.4 Killing And Yanking
|
| +--------------------------
|
|
|
| -`qOffsets'
|
| - Get section offsets that the target used when relocating the
|
| - downloaded image.
|
| +`kill-line (C-k)'
|
| + Kill the text from point to the end of the line.
|
|
|
| - Reply:
|
| - `Text=XXX;Data=YYY[;Bss=ZZZ]'
|
| - Relocate the `Text' section by XXX from its original address.
|
| - Relocate the `Data' section by YYY from its original address.
|
| - If the object file format provides segment information (e.g.
|
| - ELF `PT_LOAD' program headers), GDB will relocate entire
|
| - segments by the supplied offsets.
|
| +`backward-kill-line (C-x Rubout)'
|
| + Kill backward to the beginning of the line.
|
|
|
| - _Note: while a `Bss' offset may be included in the response,
|
| - GDB ignores this and instead applies the `Data' offset to the
|
| - `Bss' section._
|
| +`unix-line-discard (C-u)'
|
| + Kill backward from the cursor to the beginning of the current line.
|
|
|
| - `TextSeg=XXX[;DataSeg=YYY]'
|
| - Relocate the first segment of the object file, which
|
| - conventionally contains program code, to a starting address
|
| - of XXX. If `DataSeg' is specified, relocate the second
|
| - segment, which conventionally contains modifiable data, to a
|
| - starting address of YYY. GDB will report an error if the
|
| - object file does not contain segment information, or does not
|
| - contain at least as many segments as mentioned in the reply.
|
| - Extra segments are kept at fixed offsets relative to the last
|
| - relocated segment.
|
| +`kill-whole-line ()'
|
| + Kill all characters on the current line, no matter where point is.
|
| + By default, this is unbound.
|
|
|
| -`qP MODE THREAD-ID'
|
| - Returns information on THREAD-ID. Where: MODE is a hex encoded 32
|
| - bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).
|
| +`kill-word (M-d)'
|
| + Kill from point to the end of the current word, or if between
|
| + words, to the end of the next word. Word boundaries are the same
|
| + as `forward-word'.
|
|
|
| - Don't use this packet; use the `qThreadExtraInfo' query instead
|
| - (see below).
|
| +`backward-kill-word (M-<DEL>)'
|
| + Kill the word behind point. Word boundaries are the same as
|
| + `backward-word'.
|
|
|
| - Reply: see `remote.c:remote_unpack_thread_info_response()'.
|
| +`unix-word-rubout (C-w)'
|
| + Kill the word behind point, using white space as a word boundary.
|
| + The killed text is saved on the kill-ring.
|
|
|
| -`QNonStop:1'
|
| +`unix-filename-rubout ()'
|
| + Kill the word behind point, using white space and the slash
|
| + character as the word boundaries. The killed text is saved on the
|
| + kill-ring.
|
|
|
| -`QNonStop:0'
|
| - Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode.
|
| - *Note Remote Non-Stop::, for more information.
|
| +`delete-horizontal-space ()'
|
| + Delete all spaces and tabs around point. By default, this is
|
| + unbound.
|
|
|
| - Reply:
|
| - `OK'
|
| - The request succeeded.
|
| +`kill-region ()'
|
| + Kill the text in the current region. By default, this command is
|
| + unbound.
|
|
|
| - `E NN'
|
| - An error occurred. NN are hex digits.
|
| +`copy-region-as-kill ()'
|
| + Copy the text in the region to the kill buffer, so it can be yanked
|
| + right away. By default, this command is unbound.
|
|
|
| - `'
|
| - An empty reply indicates that `QNonStop' is not supported by
|
| - the stub.
|
| +`copy-backward-word ()'
|
| + Copy the word before point to the kill buffer. The word
|
| + boundaries are the same as `backward-word'. By default, this
|
| + command is unbound.
|
|
|
| - This packet is not probed by default; the remote stub must request
|
| - it, by supplying an appropriate `qSupported' response (*note
|
| - qSupported::). Use of this packet is controlled by the `set
|
| - non-stop' command; *note Non-Stop Mode::.
|
| +`copy-forward-word ()'
|
| + Copy the word following point to the kill buffer. The word
|
| + boundaries are the same as `forward-word'. By default, this
|
| + command is unbound.
|
|
|
| -`QPassSignals: SIGNAL [;SIGNAL]...'
|
| - Each listed SIGNAL should be passed directly to the inferior
|
| - process. Signals are numbered identically to continue packets and
|
| - stop replies (*note Stop Reply Packets::). Each SIGNAL list item
|
| - should be strictly greater than the previous item. These signals
|
| - do not need to stop the inferior, or be reported to GDB. All
|
| - other signals should be reported to GDB. Multiple `QPassSignals'
|
| - packets do not combine; any earlier `QPassSignals' list is
|
| - completely replaced by the new list. This packet improves
|
| - performance when using `handle SIGNAL nostop noprint pass'.
|
| +`yank (C-y)'
|
| + Yank the top of the kill ring into the buffer at point.
|
|
|
| - Reply:
|
| - `OK'
|
| - The request succeeded.
|
| +`yank-pop (M-y)'
|
| + Rotate the kill-ring, and yank the new top. You can only do this
|
| + if the prior command is `yank' or `yank-pop'.
|
|
|
| - `E NN'
|
| - An error occurred. NN are hex digits.
|
| +
|
| +File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
|
|
|
| - `'
|
| - An empty reply indicates that `QPassSignals' is not supported
|
| - by the stub.
|
| +32.4.5 Specifying Numeric Arguments
|
| +-----------------------------------
|
|
|
| - Use of this packet is controlled by the `set remote pass-signals'
|
| - command (*note set remote pass-signals: Remote Configuration.).
|
| - This packet is not probed by default; the remote stub must request
|
| - it, by supplying an appropriate `qSupported' response (*note
|
| - qSupported::).
|
| +`digit-argument (M-0, M-1, ... M--)'
|
| + Add this digit to the argument already accumulating, or start a new
|
| + argument. `M--' starts a negative argument.
|
| +
|
| +`universal-argument ()'
|
| + This is another way to specify an argument. If this command is
|
| + followed by one or more digits, optionally with a leading minus
|
| + sign, those digits define the argument. If the command is
|
| + followed by digits, executing `universal-argument' again ends the
|
| + numeric argument, but is otherwise ignored. As a special case, if
|
| + this command is immediately followed by a character that is
|
| + neither a digit or minus sign, the argument count for the next
|
| + command is multiplied by four. The argument count is initially
|
| + one, so executing this function the first time makes the argument
|
| + count four, a second time makes the argument count sixteen, and so
|
| + on. By default, this is not bound to a key.
|
|
|
| -`QProgramSignals: SIGNAL [;SIGNAL]...'
|
| - Each listed SIGNAL may be delivered to the inferior process.
|
| - Others should be silently discarded.
|
| +
|
| +File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
|
|
|
| - In some cases, the remote stub may need to decide whether to
|
| - deliver a signal to the program or not without GDB involvement.
|
| - One example of that is while detaching -- the program's threads
|
| - may have stopped for signals that haven't yet had a chance of
|
| - being reported to GDB, and so the remote stub can use the signal
|
| - list specified by this packet to know whether to deliver or ignore
|
| - those pending signals.
|
| +32.4.6 Letting Readline Type For You
|
| +------------------------------------
|
|
|
| - This does not influence whether to deliver a signal as requested
|
| - by a resumption packet (*note vCont packet::).
|
| +`complete (<TAB>)'
|
| + Attempt to perform completion on the text before point. The
|
| + actual completion performed is application-specific. The default
|
| + is filename completion.
|
| +
|
| +`possible-completions (M-?)'
|
| + List the possible completions of the text before point. When
|
| + displaying completions, Readline sets the number of columns used
|
| + for display to the value of `completion-display-width', the value
|
| + of the environment variable `COLUMNS', or the screen width, in
|
| + that order.
|
| +
|
| +`insert-completions (M-*)'
|
| + Insert all completions of the text before point that would have
|
| + been generated by `possible-completions'.
|
| +
|
| +`menu-complete ()'
|
| + Similar to `complete', but replaces the word to be completed with
|
| + a single match from the list of possible completions. Repeated
|
| + execution of `menu-complete' steps through the list of possible
|
| + completions, inserting each match in turn. At the end of the list
|
| + of completions, the bell is rung (subject to the setting of
|
| + `bell-style') and the original text is restored. An argument of N
|
| + moves N positions forward in the list of matches; a negative
|
| + argument may be used to move backward through the list. This
|
| + command is intended to be bound to <TAB>, but is unbound by
|
| + default.
|
| +
|
| +`menu-complete-backward ()'
|
| + Identical to `menu-complete', but moves backward through the list
|
| + of possible completions, as if `menu-complete' had been given a
|
| + negative argument.
|
| +
|
| +`delete-char-or-list ()'
|
| + Deletes the character under the cursor if not at the beginning or
|
| + end of the line (like `delete-char'). If at the end of the line,
|
| + behaves identically to `possible-completions'. This command is
|
| + unbound by default.
|
|
|
| - Signals are numbered identically to continue packets and stop
|
| - replies (*note Stop Reply Packets::). Each SIGNAL list item
|
| - should be strictly greater than the previous item. Multiple
|
| - `QProgramSignals' packets do not combine; any earlier
|
| - `QProgramSignals' list is completely replaced by the new list.
|
|
|
| - Reply:
|
| - `OK'
|
| - The request succeeded.
|
| +
|
| +File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
|
|
|
| - `E NN'
|
| - An error occurred. NN are hex digits.
|
| +32.4.7 Keyboard Macros
|
| +----------------------
|
|
|
| - `'
|
| - An empty reply indicates that `QProgramSignals' is not
|
| - supported by the stub.
|
| +`start-kbd-macro (C-x ()'
|
| + Begin saving the characters typed into the current keyboard macro.
|
|
|
| - Use of this packet is controlled by the `set remote
|
| - program-signals' command (*note set remote program-signals: Remote
|
| - Configuration.). This packet is not probed by default; the remote
|
| - stub must request it, by supplying an appropriate `qSupported'
|
| - response (*note qSupported::).
|
| +`end-kbd-macro (C-x ))'
|
| + Stop saving the characters typed into the current keyboard macro
|
| + and save the definition.
|
|
|
| -`qRcmd,COMMAND'
|
| - COMMAND (hex encoded) is passed to the local interpreter for
|
| - execution. Invalid commands should be reported using the output
|
| - string. Before the final result packet, the target may also
|
| - respond with a number of intermediate `OOUTPUT' console output
|
| - packets. _Implementors should note that providing access to a
|
| - stubs's interpreter may have security implications_.
|
| +`call-last-kbd-macro (C-x e)'
|
| + Re-execute the last keyboard macro defined, by making the
|
| + characters in the macro appear as if typed at the keyboard.
|
|
|
| - Reply:
|
| - `OK'
|
| - A command response with no output.
|
|
|
| - `OUTPUT'
|
| - A command response with the hex encoded output string OUTPUT.
|
| +
|
| +File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
|
| +
|
| +32.4.8 Some Miscellaneous Commands
|
| +----------------------------------
|
| +
|
| +`re-read-init-file (C-x C-r)'
|
| + Read in the contents of the INPUTRC file, and incorporate any
|
| + bindings or variable assignments found there.
|
| +
|
| +`abort (C-g)'
|
| + Abort the current editing command and ring the terminal's bell
|
| + (subject to the setting of `bell-style').
|
| +
|
| +`do-uppercase-version (M-a, M-b, M-X, ...)'
|
| + If the metafied character X is lowercase, run the command that is
|
| + bound to the corresponding uppercase character.
|
| +
|
| +`prefix-meta (<ESC>)'
|
| + Metafy the next character typed. This is for keyboards without a
|
| + meta key. Typing `<ESC> f' is equivalent to typing `M-f'.
|
| +
|
| +`undo (C-_ or C-x C-u)'
|
| + Incremental undo, separately remembered for each line.
|
| +
|
| +`revert-line (M-r)'
|
| + Undo all changes made to this line. This is like executing the
|
| + `undo' command enough times to get back to the beginning.
|
| +
|
| +`tilde-expand (M-~)'
|
| + Perform tilde expansion on the current word.
|
| +
|
| +`set-mark (C-@)'
|
| + Set the mark to the point. If a numeric argument is supplied, the
|
| + mark is set to that position.
|
| +
|
| +`exchange-point-and-mark (C-x C-x)'
|
| + Swap the point with the mark. The current cursor position is set
|
| + to the saved position, and the old cursor position is saved as the
|
| + mark.
|
| +
|
| +`character-search (C-])'
|
| + A character is read and point is moved to the next occurrence of
|
| + that character. A negative count searches for previous
|
| + occurrences.
|
| +
|
| +`character-search-backward (M-C-])'
|
| + A character is read and point is moved to the previous occurrence
|
| + of that character. A negative count searches for subsequent
|
| + occurrences.
|
| +
|
| +`skip-csi-sequence ()'
|
| + Read enough characters to consume a multi-key sequence such as
|
| + those defined for keys like Home and End. Such sequences begin
|
| + with a Control Sequence Indicator (CSI), usually ESC-[. If this
|
| + sequence is bound to "\e[", keys producing such sequences will
|
| + have no effect unless explicitly bound to a readline command,
|
| + instead of inserting stray characters into the editing buffer.
|
| + This is unbound by default, but usually bound to ESC-[.
|
| +
|
| +`insert-comment (M-#)'
|
| + Without a numeric argument, the value of the `comment-begin'
|
| + variable is inserted at the beginning of the current line. If a
|
| + numeric argument is supplied, this command acts as a toggle: if
|
| + the characters at the beginning of the line do not match the value
|
| + of `comment-begin', the value is inserted, otherwise the
|
| + characters in `comment-begin' are deleted from the beginning of
|
| + the line. In either case, the line is accepted as if a newline
|
| + had been typed.
|
| +
|
| +`dump-functions ()'
|
| + Print all of the functions and their key bindings to the Readline
|
| + output stream. If a numeric argument is supplied, the output is
|
| + formatted in such a way that it can be made part of an INPUTRC
|
| + file. This command is unbound by default.
|
| +
|
| +`dump-variables ()'
|
| + Print all of the settable variables and their values to the
|
| + Readline output stream. If a numeric argument is supplied, the
|
| + output is formatted in such a way that it can be made part of an
|
| + INPUTRC file. This command is unbound by default.
|
| +
|
| +`dump-macros ()'
|
| + Print all of the Readline key sequences bound to macros and the
|
| + strings they output. If a numeric argument is supplied, the
|
| + output is formatted in such a way that it can be made part of an
|
| + INPUTRC file. This command is unbound by default.
|
| +
|
| +`emacs-editing-mode (C-e)'
|
| + When in `vi' command mode, this causes a switch to `emacs' editing
|
| + mode.
|
| +
|
| +`vi-editing-mode (M-C-j)'
|
| + When in `emacs' editing mode, this causes a switch to `vi' editing
|
| + mode.
|
|
|
| - `E NN'
|
| - Indicate a badly formed request.
|
|
|
| - `'
|
| - An empty reply indicates that `qRcmd' is not recognized.
|
| +
|
| +File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
|
|
|
| - (Note that the `qRcmd' packet's name is separated from the command
|
| - by a `,', not a `:', contrary to the naming conventions above.
|
| - Please don't use this packet as a model for new packets.)
|
| +32.5 Readline vi Mode
|
| +=====================
|
|
|
| -`qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'
|
| - Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and
|
| - LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes,
|
| - hex encoded.
|
| +While the Readline library does not have a full set of `vi' editing
|
| +functions, it does contain enough to allow simple editing of the line.
|
| +The Readline `vi' mode behaves as specified in the POSIX standard.
|
|
|
| - Reply:
|
| - `0'
|
| - The pattern was not found.
|
| + In order to switch interactively between `emacs' and `vi' editing
|
| +modes, use the command `M-C-j' (bound to emacs-editing-mode when in
|
| +`vi' mode and to vi-editing-mode in `emacs' mode). The Readline
|
| +default is `emacs' mode.
|
|
|
| - `1,address'
|
| - The pattern was found at ADDRESS.
|
| + When you enter a line in `vi' mode, you are already placed in
|
| +`insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
|
| +you into `command' mode, where you can edit the text of the line with
|
| +the standard `vi' movement keys, move to previous history lines with
|
| +`k' and subsequent lines with `j', and so forth.
|
|
|
| - `E NN'
|
| - A badly formed request or an error was encountered while
|
| - searching memory.
|
| +
|
| +File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top
|
|
|
| - `'
|
| - An empty reply indicates that `qSearch:memory' is not
|
| - recognized.
|
| +33 Using History Interactively
|
| +******************************
|
|
|
| -`QStartNoAckMode'
|
| - Request that the remote stub disable the normal `+'/`-' protocol
|
| - acknowledgments (*note Packet Acknowledgment::).
|
| +This chapter describes how to use the GNU History Library interactively,
|
| +from a user's standpoint. It should be considered a user's guide. For
|
| +information on using the GNU History Library in your own programs,
|
| +*note Programming with GNU History: (history)Programming with GNU
|
| +History.
|
|
|
| - Reply:
|
| - `OK'
|
| - The stub has switched to no-acknowledgment mode. GDB
|
| - acknowledges this reponse, but neither the stub nor GDB shall
|
| - send or expect further `+'/`-' acknowledgments in the current
|
| - connection.
|
| +* Menu:
|
|
|
| - `'
|
| - An empty reply indicates that the stub does not support
|
| - no-acknowledgment mode.
|
| +* History Interaction:: What it feels like using History as a user.
|
|
|
| -`qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
|
| - Tell the remote stub about features supported by GDB, and query
|
| - the stub for features it supports. This packet allows GDB and the
|
| - remote stub to take advantage of each others' features.
|
| - `qSupported' also consolidates multiple feature probes at startup,
|
| - to improve GDB performance--a single larger packet performs better
|
| - than multiple smaller probe packets on high-latency links. Some
|
| - features may enable behavior which must not be on by default, e.g.
|
| - because it would confuse older clients or stubs. Other features
|
| - may describe packets which could be automatically probed for, but
|
| - are not. These features must be reported before GDB will use
|
| - them. This "default unsupported" behavior is not appropriate for
|
| - all packets, but it helps to keep the initial connection time
|
| - under control with new versions of GDB which support increasing
|
| - numbers of packets.
|
| +
|
| +File: gdb.info, Node: History Interaction, Up: Using History Interactively
|
|
|
| - Reply:
|
| - `STUBFEATURE [;STUBFEATURE]...'
|
| - The stub supports or does not support each returned
|
| - STUBFEATURE, depending on the form of each STUBFEATURE (see
|
| - below for the possible forms).
|
| +33.1 History Expansion
|
| +======================
|
|
|
| - `'
|
| - An empty reply indicates that `qSupported' is not recognized,
|
| - or that no features needed to be reported to GDB.
|
| +The History library provides a history expansion feature that is similar
|
| +to the history expansion provided by `csh'. This section describes the
|
| +syntax used to manipulate the history information.
|
| +
|
| + History expansions introduce words from the history list into the
|
| +input stream, making it easy to repeat commands, insert the arguments
|
| +to a previous command into the current input line, or fix errors in
|
| +previous commands quickly.
|
| +
|
| + History expansion takes place in two parts. The first is to
|
| +determine which line from the history list should be used during
|
| +substitution. The second is to select portions of that line for
|
| +inclusion into the current one. The line selected from the history is
|
| +called the "event", and the portions of that line that are acted upon
|
| +are called "words". Various "modifiers" are available to manipulate
|
| +the selected words. The line is broken into words in the same fashion
|
| +that Bash does, so that several words surrounded by quotes are
|
| +considered one word. History expansions are introduced by the
|
| +appearance of the history expansion character, which is `!' by default.
|
|
|
| - The allowed forms for each feature (either a GDBFEATURE in the
|
| - `qSupported' packet, or a STUBFEATURE in the response) are:
|
| +* Menu:
|
|
|
| - `NAME=VALUE'
|
| - The remote protocol feature NAME is supported, and associated
|
| - with the specified VALUE. The format of VALUE depends on the
|
| - feature, but it must not include a semicolon.
|
| +* Event Designators:: How to specify which history line to use.
|
| +* Word Designators:: Specifying which words are of interest.
|
| +* Modifiers:: Modifying the results of substitution.
|
|
|
| - `NAME+'
|
| - The remote protocol feature NAME is supported, and does not
|
| - need an associated value.
|
| +
|
| +File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
|
|
|
| - `NAME-'
|
| - The remote protocol feature NAME is not supported.
|
| +33.1.1 Event Designators
|
| +------------------------
|
|
|
| - `NAME?'
|
| - The remote protocol feature NAME may be supported, and GDB
|
| - should auto-detect support in some other way when it is
|
| - needed. This form will not be used for GDBFEATURE
|
| - notifications, but may be used for STUBFEATURE responses.
|
| +An event designator is a reference to a command line entry in the
|
| +history list. Unless the reference is absolute, events are relative to
|
| +the current position in the history list.
|
|
|
| - Whenever the stub receives a `qSupported' request, the supplied
|
| - set of GDB features should override any previous request. This
|
| - allows GDB to put the stub in a known state, even if the stub had
|
| - previously been communicating with a different version of GDB.
|
| +`!'
|
| + Start a history substitution, except when followed by a space, tab,
|
| + the end of the line, or `='.
|
|
|
| - The following values of GDBFEATURE (for the packet sent by GDB)
|
| - are defined:
|
| +`!N'
|
| + Refer to command line N.
|
|
|
| - `multiprocess'
|
| - This feature indicates whether GDB supports multiprocess
|
| - extensions to the remote protocol. GDB does not use such
|
| - extensions unless the stub also reports that it supports them
|
| - by including `multiprocess+' in its `qSupported' reply.
|
| - *Note multiprocess extensions::, for details.
|
| +`!-N'
|
| + Refer to the command N lines back.
|
|
|
| - `xmlRegisters'
|
| - This feature indicates that GDB supports the XML target
|
| - description. If the stub sees `xmlRegisters=' with target
|
| - specific strings separated by a comma, it will report register
|
| - description.
|
| +`!!'
|
| + Refer to the previous command. This is a synonym for `!-1'.
|
|
|
| - `qRelocInsn'
|
| - This feature indicates whether GDB supports the `qRelocInsn'
|
| - packet (*note Relocate instruction reply packet: Tracepoint
|
| - Packets.).
|
| +`!STRING'
|
| + Refer to the most recent command preceding the current position in
|
| + the history list starting with STRING.
|
|
|
| - Stubs should ignore any unknown values for GDBFEATURE. Any GDB
|
| - which sends a `qSupported' packet supports receiving packets of
|
| - unlimited length (earlier versions of GDB may reject overly long
|
| - responses). Additional values for GDBFEATURE may be defined in
|
| - the future to let the stub take advantage of new features in GDB,
|
| - e.g. incompatible improvements in the remote protocol--the
|
| - `multiprocess' feature is an example of such a feature. The
|
| - stub's reply should be independent of the GDBFEATURE entries sent
|
| - by GDB; first GDB describes all the features it supports, and then
|
| - the stub replies with all the features it supports.
|
| +`!?STRING[?]'
|
| + Refer to the most recent command preceding the current position in
|
| + the history list containing STRING. The trailing `?' may be
|
| + omitted if the STRING is followed immediately by a newline.
|
|
|
| - Similarly, GDB will silently ignore unrecognized stub feature
|
| - responses, as long as each response uses one of the standard forms.
|
| +`^STRING1^STRING2^'
|
| + Quick Substitution. Repeat the last command, replacing STRING1
|
| + with STRING2. Equivalent to `!!:s/STRING1/STRING2/'.
|
|
|
| - Some features are flags. A stub which supports a flag feature
|
| - should respond with a `+' form response. Other features require
|
| - values, and the stub should respond with an `=' form response.
|
| +`!#'
|
| + The entire command line typed so far.
|
|
|
| - Each feature has a default value, which GDB will use if
|
| - `qSupported' is not available or if the feature is not mentioned
|
| - in the `qSupported' response. The default values are fixed; a
|
| - stub is free to omit any feature responses that match the defaults.
|
|
|
| - Not all features can be probed, but for those which can, the
|
| - probing mechanism is useful: in some cases, a stub's internal
|
| - architecture may not allow the protocol layer to know some
|
| - information about the underlying target in advance. This is
|
| - especially common in stubs which may be configured for multiple
|
| - targets.
|
| +
|
| +File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
|
|
|
| - These are the currently defined stub features and their properties:
|
| +33.1.2 Word Designators
|
| +-----------------------
|
|
|
| - Feature Name Value Default Probe Allowed
|
| - Required
|
| - `PacketSize' Yes `-' No
|
| - `qXfer:auxv:read' No `-' Yes
|
| - `qXfer:features:read' No `-' Yes
|
| - `qXfer:libraries:read' No `-' Yes
|
| - `qXfer:memory-map:read' No `-' Yes
|
| - `qXfer:sdata:read' No `-' Yes
|
| - `qXfer:spu:read' No `-' Yes
|
| - `qXfer:spu:write' No `-' Yes
|
| - `qXfer:siginfo:read' No `-' Yes
|
| - `qXfer:siginfo:write' No `-' Yes
|
| - `qXfer:threads:read' No `-' Yes
|
| - `qXfer:traceframe-info:read'No `-' Yes
|
| - `qXfer:uib:read' No `-' Yes
|
| - `qXfer:fdpic:read' No `-' Yes
|
| - `QNonStop' No `-' Yes
|
| - `QPassSignals' No `-' Yes
|
| - `QStartNoAckMode' No `-' Yes
|
| - `multiprocess' No `-' No
|
| - `ConditionalBreakpoints'No `-' No
|
| - `ConditionalTracepoints'No `-' No
|
| - `ReverseContinue' No `-' No
|
| - `ReverseStep' No `-' No
|
| - `TracepointSource' No `-' No
|
| - `QAgent' No `-' No
|
| - `QAllow' No `-' No
|
| - `QDisableRandomization' No `-' No
|
| - `EnableDisableTracepoints'No `-' No
|
| - `tracenz' No `-' No
|
| - `BreakpointCommands' No `-' No
|
| +Word designators are used to select desired words from the event. A
|
| +`:' separates the event specification from the word designator. It may
|
| +be omitted if the word designator begins with a `^', `$', `*', `-', or
|
| +`%'. Words are numbered from the beginning of the line, with the first
|
| +word being denoted by 0 (zero). Words are inserted into the current
|
| +line separated by single spaces.
|
|
|
| - These are the currently defined stub features, in more detail:
|
| + For example,
|
|
|
| - `PacketSize=BYTES'
|
| - The remote stub can accept packets up to at least BYTES in
|
| - length. GDB will send packets up to this size for bulk
|
| - transfers, and will never send larger packets. This is a
|
| - limit on the data characters in the packet, including the
|
| - frame and checksum. There is no trailing NUL byte in a
|
| - remote protocol packet; if the stub stores packets in a
|
| - NUL-terminated format, it should allow an extra byte in its
|
| - buffer for the NUL. If this stub feature is not supported,
|
| - GDB guesses based on the size of the `g' packet response.
|
| +`!!'
|
| + designates the preceding command. When you type this, the
|
| + preceding command is repeated in toto.
|
|
|
| - `qXfer:auxv:read'
|
| - The remote stub understands the `qXfer:auxv:read' packet
|
| - (*note qXfer auxiliary vector read::).
|
| +`!!:$'
|
| + designates the last argument of the preceding command. This may be
|
| + shortened to `!$'.
|
|
|
| - `qXfer:features:read'
|
| - The remote stub understands the `qXfer:features:read' packet
|
| - (*note qXfer target description read::).
|
| +`!fi:2'
|
| + designates the second argument of the most recent command starting
|
| + with the letters `fi'.
|
|
|
| - `qXfer:libraries:read'
|
| - The remote stub understands the `qXfer:libraries:read' packet
|
| - (*note qXfer library list read::).
|
| + Here are the word designators:
|
|
|
| - `qXfer:libraries-svr4:read'
|
| - The remote stub understands the `qXfer:libraries-svr4:read'
|
| - packet (*note qXfer svr4 library list read::).
|
| +`0 (zero)'
|
| + The `0'th word. For many applications, this is the command word.
|
|
|
| - `qXfer:memory-map:read'
|
| - The remote stub understands the `qXfer:memory-map:read' packet
|
| - (*note qXfer memory map read::).
|
| +`N'
|
| + The Nth word.
|
|
|
| - `qXfer:sdata:read'
|
| - The remote stub understands the `qXfer:sdata:read' packet
|
| - (*note qXfer sdata read::).
|
| +`^'
|
| + The first argument; that is, word 1.
|
|
|
| - `qXfer:spu:read'
|
| - The remote stub understands the `qXfer:spu:read' packet
|
| - (*note qXfer spu read::).
|
| +`$'
|
| + The last argument.
|
|
|
| - `qXfer:spu:write'
|
| - The remote stub understands the `qXfer:spu:write' packet
|
| - (*note qXfer spu write::).
|
| +`%'
|
| + The word matched by the most recent `?STRING?' search.
|
|
|
| - `qXfer:siginfo:read'
|
| - The remote stub understands the `qXfer:siginfo:read' packet
|
| - (*note qXfer siginfo read::).
|
| +`X-Y'
|
| + A range of words; `-Y' abbreviates `0-Y'.
|
|
|
| - `qXfer:siginfo:write'
|
| - The remote stub understands the `qXfer:siginfo:write' packet
|
| - (*note qXfer siginfo write::).
|
| +`*'
|
| + All of the words, except the `0'th. This is a synonym for `1-$'.
|
| + It is not an error to use `*' if there is just one word in the
|
| + event; the empty string is returned in that case.
|
|
|
| - `qXfer:threads:read'
|
| - The remote stub understands the `qXfer:threads:read' packet
|
| - (*note qXfer threads read::).
|
| +`X*'
|
| + Abbreviates `X-$'
|
|
|
| - `qXfer:traceframe-info:read'
|
| - The remote stub understands the `qXfer:traceframe-info:read'
|
| - packet (*note qXfer traceframe info read::).
|
| +`X-'
|
| + Abbreviates `X-$' like `X*', but omits the last word.
|
|
|
| - `qXfer:uib:read'
|
| - The remote stub understands the `qXfer:uib:read' packet
|
| - (*note qXfer unwind info block::).
|
|
|
| - `qXfer:fdpic:read'
|
| - The remote stub understands the `qXfer:fdpic:read' packet
|
| - (*note qXfer fdpic loadmap read::).
|
| + If a word designator is supplied without an event specification, the
|
| +previous command is used as the event.
|
|
|
| - `QNonStop'
|
| - The remote stub understands the `QNonStop' packet (*note
|
| - QNonStop::).
|
| +
|
| +File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
|
|
|
| - `QPassSignals'
|
| - The remote stub understands the `QPassSignals' packet (*note
|
| - QPassSignals::).
|
| +33.1.3 Modifiers
|
| +----------------
|
|
|
| - `QStartNoAckMode'
|
| - The remote stub understands the `QStartNoAckMode' packet and
|
| - prefers to operate in no-acknowledgment mode. *Note Packet
|
| - Acknowledgment::.
|
| +After the optional word designator, you can add a sequence of one or
|
| +more of the following modifiers, each preceded by a `:'.
|
|
|
| - `multiprocess'
|
| - The remote stub understands the multiprocess extensions to
|
| - the remote protocol syntax. The multiprocess extensions
|
| - affect the syntax of thread IDs in both packets and replies
|
| - (*note thread-id syntax::), and add process IDs to the `D'
|
| - packet and `W' and `X' replies. Note that reporting this
|
| - feature indicates support for the syntactic extensions only,
|
| - not that the stub necessarily supports debugging of more than
|
| - one process at a time. The stub must not use multiprocess
|
| - extensions in packet replies unless GDB has also indicated it
|
| - supports them in its `qSupported' request.
|
| +`h'
|
| + Remove a trailing pathname component, leaving only the head.
|
|
|
| - `qXfer:osdata:read'
|
| - The remote stub understands the `qXfer:osdata:read' packet
|
| - ((*note qXfer osdata read::).
|
| +`t'
|
| + Remove all leading pathname components, leaving the tail.
|
|
|
| - `ConditionalBreakpoints'
|
| - The target accepts and implements evaluation of conditional
|
| - expressions defined for breakpoints. The target will only
|
| - report breakpoint triggers when such conditions are true
|
| - (*note Break Conditions: Conditions.).
|
| +`r'
|
| + Remove a trailing suffix of the form `.SUFFIX', leaving the
|
| + basename.
|
|
|
| - `ConditionalTracepoints'
|
| - The remote stub accepts and implements conditional
|
| - expressions defined for tracepoints (*note Tracepoint
|
| - Conditions::).
|
| +`e'
|
| + Remove all but the trailing suffix.
|
|
|
| - `ReverseContinue'
|
| - The remote stub accepts and implements the reverse continue
|
| - packet (*note bc::).
|
| +`p'
|
| + Print the new command but do not execute it.
|
|
|
| - `ReverseStep'
|
| - The remote stub accepts and implements the reverse step packet
|
| - (*note bs::).
|
| +`s/OLD/NEW/'
|
| + Substitute NEW for the first occurrence of OLD in the event line.
|
| + Any delimiter may be used in place of `/'. The delimiter may be
|
| + quoted in OLD and NEW with a single backslash. If `&' appears in
|
| + NEW, it is replaced by OLD. A single backslash will quote the
|
| + `&'. The final delimiter is optional if it is the last character
|
| + on the input line.
|
|
|
| - `TracepointSource'
|
| - The remote stub understands the `QTDPsrc' packet that supplies
|
| - the source form of tracepoint definitions.
|
| +`&'
|
| + Repeat the previous substitution.
|
|
|
| - `QAgent'
|
| - The remote stub understands the `QAgent' packet.
|
| +`g'
|
| +`a'
|
| + Cause changes to be applied over the entire event line. Used in
|
| + conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
|
|
|
| - `QAllow'
|
| - The remote stub understands the `QAllow' packet.
|
| +`G'
|
| + Apply the following `s' modifier once to each word in the event.
|
|
|
| - `QDisableRandomization'
|
| - The remote stub understands the `QDisableRandomization'
|
| - packet.
|
|
|
| - `StaticTracepoint'
|
| - The remote stub supports static tracepoints.
|
| +
|
| +File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top
|
|
|
| - `InstallInTrace'
|
| - The remote stub supports installing tracepoint in tracing.
|
| +Appendix A In Memoriam
|
| +**********************
|
|
|
| - `EnableDisableTracepoints'
|
| - The remote stub supports the `QTEnable' (*note QTEnable::) and
|
| - `QTDisable' (*note QTDisable::) packets that allow tracepoints
|
| - to be enabled and disabled while a trace experiment is
|
| - running.
|
| +The GDB project mourns the loss of the following long-time contributors:
|
|
|
| - `tracenz'
|
| - The remote stub supports the `tracenz' bytecode for
|
| - collecting strings. See *Note Bytecode Descriptions:: for
|
| - details about the bytecode.
|
| +`Fred Fish'
|
| + Fred was a long-standing contributor to GDB (1991-2006), and to
|
| + Free Software in general. Outside of GDB, he was known in the
|
| + Amiga world for his series of Fish Disks, and the GeekGadget
|
| + project.
|
|
|
| - `BreakpointCommands'
|
| - The remote stub supports running a breakpoint's command list
|
| - itself, rather than reporting the hit to GDB.
|
| +`Michael Snyder'
|
| + Michael was one of the Global Maintainers of the GDB project, with
|
| + contributions recorded as early as 1996, until 2011. In addition
|
| + to his day to day participation, he was a large driving force
|
| + behind adding Reverse Debugging to GDB.
|
|
|
| + Beyond their technical contributions to the project, they were also
|
| +enjoyable members of the Free Software Community. We will miss them.
|
|
|
| -`qSymbol::'
|
| - Notify the target that GDB is prepared to serve symbol lookup
|
| - requests. Accept requests from the target for the values of
|
| - symbols.
|
| +
|
| +File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top
|
| +
|
| +Appendix B Formatting Documentation
|
| +***********************************
|
| +
|
| +The GDB 4 release includes an already-formatted reference card, ready
|
| +for printing with PostScript or Ghostscript, in the `gdb' subdirectory
|
| +of the main source directory(1). If you can use PostScript or
|
| +Ghostscript with your printer, you can print the reference card
|
| +immediately with `refcard.ps'.
|
| +
|
| + The release also includes the source for the reference card. You
|
| +can format it, using TeX, by typing:
|
| +
|
| + make refcard.dvi
|
| +
|
| + The GDB reference card is designed to print in "landscape" mode on
|
| +US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
|
| +high. You will need to specify this form of printing as an option to
|
| +your DVI output program.
|
| +
|
| + All the documentation for GDB comes as part of the machine-readable
|
| +distribution. The documentation is written in Texinfo format, which is
|
| +a documentation system that uses a single source file to produce both
|
| +on-line information and a printed manual. You can use one of the Info
|
| +formatting commands to create the on-line version of the documentation
|
| +and TeX (or `texi2roff') to typeset the printed version.
|
| +
|
| + GDB includes an already formatted copy of the on-line Info version
|
| +of this manual in the `gdb' subdirectory. The main Info file is
|
| +`gdb-7.6.50.20131211-cvs/gdb/gdb.info', and it refers to subordinate
|
| +files matching `gdb.info*' in the same directory. If necessary, you
|
| +can print out these files, or read them with any editor; but they are
|
| +easier to read using the `info' subsystem in GNU Emacs or the
|
| +standalone `info' program, available as part of the GNU Texinfo
|
| +distribution.
|
| +
|
| + If you want to format these Info files yourself, you need one of the
|
| +Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
|
| +
|
| + If you have `makeinfo' installed, and are in the top level GDB
|
| +source directory (`gdb-7.6.50.20131211-cvs', in the case of version
|
| +7.6.50.20131211-cvs), you can make the Info file by typing:
|
| +
|
| + cd gdb
|
| + make gdb.info
|
| +
|
| + If you want to typeset and print copies of this manual, you need TeX,
|
| +a program to print its DVI output files, and `texinfo.tex', the Texinfo
|
| +definitions file.
|
| +
|
| + TeX is a typesetting program; it does not print files directly, but
|
| +produces output files called DVI files. To print a typeset document,
|
| +you need a program to print DVI files. If your system has TeX
|
| +installed, chances are it has such a program. The precise command to
|
| +use depends on your system; `lpr -d' is common; another (for PostScript
|
| +devices) is `dvips'. The DVI print command may require a file name
|
| +without any extension or a `.dvi' extension.
|
| +
|
| + TeX also requires a macro definitions file called `texinfo.tex'.
|
| +This file tells TeX how to typeset a document written in Texinfo
|
| +format. On its own, TeX cannot either read or typeset a Texinfo file.
|
| +`texinfo.tex' is distributed with GDB and is located in the
|
| +`gdb-VERSION-NUMBER/texinfo' directory.
|
| +
|
| + If you have TeX and a DVI printer program installed, you can typeset
|
| +and print this manual. First switch to the `gdb' subdirectory of the
|
| +main source directory (for example, to `gdb-7.6.50.20131211-cvs/gdb')
|
| +and type:
|
| +
|
| + make gdb.dvi
|
| +
|
| + Then give `gdb.dvi' to your DVI printing program.
|
|
|
| - Reply:
|
| - `OK'
|
| - The target does not need to look up any (more) symbols.
|
| + ---------- Footnotes ----------
|
|
|
| - `qSymbol:SYM_NAME'
|
| - The target requests the value of symbol SYM_NAME (hex
|
| - encoded). GDB may provide the value by using the
|
| - `qSymbol:SYM_VALUE:SYM_NAME' message, described below.
|
| + (1) In `gdb-7.6.50.20131211-cvs/gdb/refcard.ps' of the version
|
| +7.6.50.20131211-cvs release.
|
|
|
| -`qSymbol:SYM_VALUE:SYM_NAME'
|
| - Set the value of SYM_NAME to SYM_VALUE.
|
| +
|
| +File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top
|
|
|
| - SYM_NAME (hex encoded) is the name of a symbol whose value the
|
| - target has previously requested.
|
| +Appendix C Installing GDB
|
| +*************************
|
|
|
| - SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot
|
| - supply a value for SYM_NAME, then this field will be empty.
|
| +* Menu:
|
|
|
| - Reply:
|
| - `OK'
|
| - The target does not need to look up any (more) symbols.
|
| +* Requirements:: Requirements for building GDB
|
| +* Running Configure:: Invoking the GDB `configure' script
|
| +* Separate Objdir:: Compiling GDB in another directory
|
| +* Config Names:: Specifying names for hosts and targets
|
| +* Configure Options:: Summary of options for configure
|
| +* System-wide configuration:: Having a system-wide init file
|
|
|
| - `qSymbol:SYM_NAME'
|
| - The target requests the value of a new symbol SYM_NAME (hex
|
| - encoded). GDB will continue to supply the values of symbols
|
| - (if available), until the target ceases to request them.
|
| +
|
| +File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB
|
|
|
| -`qTBuffer'
|
| +C.1 Requirements for Building GDB
|
| +=================================
|
|
|
| -`QTBuffer'
|
| +Building GDB requires various tools and packages to be available.
|
| +Other packages will be used only if they are found.
|
|
|
| -`QTDisconnected'
|
| -`QTDP'
|
| -`QTDPsrc'
|
| -`QTDV'
|
| -`qTfP'
|
| -`qTfV'
|
| -`QTFrame'
|
| -`qTMinFTPILen'
|
| - *Note Tracepoint Packets::.
|
| +Tools/Packages Necessary for Building GDB
|
| +=========================================
|
|
|
| -`qThreadExtraInfo,THREAD-ID'
|
| - Obtain a printable string description of a thread's attributes from
|
| - the target OS. THREAD-ID is a thread ID; see *Note thread-id
|
| - syntax::. This string may contain anything that the target OS
|
| - thinks is interesting for GDB to tell the user about the thread.
|
| - The string is displayed in GDB's `info threads' display. Some
|
| - examples of possible thread extra info strings are `Runnable', or
|
| - `Blocked on Mutex'.
|
| +ISO C90 compiler
|
| + GDB is written in ISO C90. It should be buildable with any
|
| + working C90 compiler, e.g. GCC.
|
|
|
| - Reply:
|
| - `XX...'
|
| - Where `XX...' is a hex encoding of ASCII data, comprising the
|
| - printable string containing the extra information about the
|
| - thread's attributes.
|
|
|
| - (Note that the `qThreadExtraInfo' packet's name is separated from
|
| - the command by a `,', not a `:', contrary to the naming
|
| - conventions above. Please don't use this packet as a model for new
|
| - packets.)
|
| +Tools/Packages Optional for Building GDB
|
| +========================================
|
|
|
| -`QTNotes'
|
| +Expat
|
| + GDB can use the Expat XML parsing library. This library may be
|
| + included with your operating system distribution; if it is not, you
|
| + can get the latest version from `http://expat.sourceforge.net'.
|
| + The `configure' script will search for this library in several
|
| + standard locations; if it is installed in an unusual path, you can
|
| + use the `--with-libexpat-prefix' option to specify its location.
|
|
|
| -`qTP'
|
| + Expat is used for:
|
|
|
| -`QTSave'
|
| + * Remote protocol memory maps (*note Memory Map Format::)
|
|
|
| -`qTsP'
|
| + * Target descriptions (*note Target Descriptions::)
|
|
|
| -`qTsV'
|
| -`QTStart'
|
| -`QTStop'
|
| -`QTEnable'
|
| -`QTDisable'
|
| -`QTinit'
|
| -`QTro'
|
| -`qTStatus'
|
| -`qTV'
|
| -`qTfSTM'
|
| -`qTsSTM'
|
| -`qTSTMat'
|
| - *Note Tracepoint Packets::.
|
| + * Remote shared library lists (*Note Library List Format::, or
|
| + alternatively *note Library List Format for SVR4 Targets::)
|
|
|
| -`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
|
| - Read uninterpreted bytes from the target's special data area
|
| - identified by the keyword OBJECT. Request LENGTH bytes starting
|
| - at OFFSET bytes into the data. The content and encoding of ANNEX
|
| - is specific to OBJECT; it can supply additional details about what
|
| - data to access.
|
| + * MS-Windows shared libraries (*note Shared Libraries::)
|
|
|
| - Here are the specific requests of this form defined so far. All
|
| - `qXfer:OBJECT:read:...' requests use the same reply formats,
|
| - listed below.
|
| + * Traceframe info (*note Traceframe Info Format::)
|
|
|
| - `qXfer:auxv:read::OFFSET,LENGTH'
|
| - Access the target's "auxiliary vector". *Note auxiliary
|
| - vector: OS Information. Note ANNEX must be empty.
|
| + * Branch trace (*note Branch Trace Format::)
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| +zlib
|
| + GDB will use the `zlib' library, if available, to read compressed
|
| + debug sections. Some linkers, such as GNU gold, are capable of
|
| + producing binaries with compressed debug sections. If GDB is
|
| + compiled with `zlib', it will be able to read the debug
|
| + information in such binaries.
|
|
|
| - `qXfer:features:read:ANNEX:OFFSET,LENGTH'
|
| - Access the "target description". *Note Target
|
| - Descriptions::. The annex specifies which XML document to
|
| - access. The main description is always loaded from the
|
| - `target.xml' annex.
|
| + The `zlib' library is likely included with your operating system
|
| + distribution; if it is not, you can get the latest version from
|
| + `http://zlib.net'.
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| +iconv
|
| + GDB's features related to character sets (*note Character Sets::)
|
| + require a functioning `iconv' implementation. If you are on a GNU
|
| + system, then this is provided by the GNU C Library. Some other
|
| + systems also provide a working `iconv'.
|
|
|
| - `qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
|
| - Access the target's list of loaded libraries. *Note Library
|
| - List Format::. The annex part of the generic `qXfer' packet
|
| - must be empty (*note qXfer read::).
|
| + If GDB is using the `iconv' program which is installed in a
|
| + non-standard place, you will need to tell GDB where to find it.
|
| + This is done with `--with-iconv-bin' which specifies the directory
|
| + that contains the `iconv' program.
|
|
|
| - Targets which maintain a list of libraries in the program's
|
| - memory do not need to implement this packet; it is designed
|
| - for platforms where the operating system manages the list of
|
| - loaded libraries.
|
| + On systems without `iconv', you can install GNU Libiconv. If you
|
| + have previously installed Libiconv, you can use the
|
| + `--with-libiconv-prefix' option to configure.
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| + GDB's top-level `configure' and `Makefile' will arrange to build
|
| + Libiconv if a directory named `libiconv' appears in the top-most
|
| + source directory. If Libiconv is built this way, and if the
|
| + operating system does not provide a suitable `iconv'
|
| + implementation, then the just-built library will automatically be
|
| + used by GDB. One easy way to set this up is to download GNU
|
| + Libiconv, unpack it, and then rename the directory holding the
|
| + Libiconv source code to `libiconv'.
|
|
|
| - `qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH'
|
| - Access the target's list of loaded libraries when the target
|
| - is an SVR4 platform. *Note Library List Format for SVR4
|
| - Targets::. The annex part of the generic `qXfer' packet must
|
| - be empty (*note qXfer read::).
|
| +
|
| +File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB
|
|
|
| - This packet is optional for better performance on SVR4
|
| - targets. GDB uses memory read packets to read the SVR4
|
| - library list otherwise.
|
| +C.2 Invoking the GDB `configure' Script
|
| +=======================================
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| +GDB comes with a `configure' script that automates the process of
|
| +preparing GDB for installation; you can then use `make' to build the
|
| +`gdb' program.
|
|
|
| - `qXfer:memory-map:read::OFFSET,LENGTH'
|
| - Access the target's "memory-map". *Note Memory Map Format::.
|
| - The annex part of the generic `qXfer' packet must be empty
|
| - (*note qXfer read::).
|
| + The GDB distribution includes all the source code you need for GDB
|
| +in a single directory, whose name is usually composed by appending the
|
| +version number to `gdb'.
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| + For example, the GDB version 7.6.50.20131211-cvs distribution is in
|
| +the `gdb-7.6.50.20131211-cvs' directory. That directory contains:
|
|
|
| - `qXfer:sdata:read::OFFSET,LENGTH'
|
| - Read contents of the extra collected static tracepoint marker
|
| - information. The annex part of the generic `qXfer' packet
|
| - must be empty (*note qXfer read::). *Note Tracepoint Action
|
| - Lists: Tracepoint Actions.
|
| +`gdb-7.6.50.20131211-cvs/configure (and supporting files)'
|
| + script for configuring GDB and all its supporting libraries
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| +`gdb-7.6.50.20131211-cvs/gdb'
|
| + the source specific to GDB itself
|
|
|
| - `qXfer:siginfo:read::OFFSET,LENGTH'
|
| - Read contents of the extra signal information on the target
|
| - system. The annex part of the generic `qXfer' packet must be
|
| - empty (*note qXfer read::).
|
| +`gdb-7.6.50.20131211-cvs/bfd'
|
| + source for the Binary File Descriptor library
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| +`gdb-7.6.50.20131211-cvs/include'
|
| + GNU include files
|
|
|
| - `qXfer:spu:read:ANNEX:OFFSET,LENGTH'
|
| - Read contents of an `spufs' file on the target system. The
|
| - annex specifies which file to read; it must be of the form
|
| - `ID/NAME', where ID specifies an SPU context ID in the target
|
| - process, and NAME identifes the `spufs' file in that context
|
| - to be accessed.
|
| +`gdb-7.6.50.20131211-cvs/libiberty'
|
| + source for the `-liberty' free software library
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| +`gdb-7.6.50.20131211-cvs/opcodes'
|
| + source for the library of opcode tables and disassemblers
|
|
|
| - `qXfer:threads:read::OFFSET,LENGTH'
|
| - Access the list of threads on target. *Note Thread List
|
| - Format::. The annex part of the generic `qXfer' packet must
|
| - be empty (*note qXfer read::).
|
| +`gdb-7.6.50.20131211-cvs/readline'
|
| + source for the GNU command-line interface
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| +`gdb-7.6.50.20131211-cvs/glob'
|
| + source for the GNU filename pattern-matching subroutine
|
|
|
| - `qXfer:traceframe-info:read::OFFSET,LENGTH'
|
| - Return a description of the current traceframe's contents.
|
| - *Note Traceframe Info Format::. The annex part of the generic
|
| - `qXfer' packet must be empty (*note qXfer read::).
|
| +`gdb-7.6.50.20131211-cvs/mmalloc'
|
| + source for the GNU memory-mapped malloc package
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| + The simplest way to configure and build GDB is to run `configure'
|
| +from the `gdb-VERSION-NUMBER' source directory, which in this example
|
| +is the `gdb-7.6.50.20131211-cvs' directory.
|
|
|
| - `qXfer:uib:read:PC:OFFSET,LENGTH'
|
| - Return the unwind information block for PC. This packet is
|
| - used on OpenVMS/ia64 to ask the kernel unwind information.
|
| + First switch to the `gdb-VERSION-NUMBER' source directory if you are
|
| +not already in it; then run `configure'. Pass the identifier for the
|
| +platform on which GDB will run as an argument.
|
|
|
| - This packet is not probed by default.
|
| + For example:
|
|
|
| - `qXfer:fdpic:read:ANNEX:OFFSET,LENGTH'
|
| - Read contents of `loadmap's on the target system. The annex,
|
| - either `exec' or `interp', specifies which `loadmap',
|
| - executable `loadmap' or interpreter `loadmap' to read.
|
| + cd gdb-7.6.50.20131211-cvs
|
| + ./configure HOST
|
| + make
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| +where HOST is an identifier such as `sun4' or `decstation', that
|
| +identifies the platform where GDB will run. (You can often leave off
|
| +HOST; `configure' tries to guess the correct value by examining your
|
| +system.)
|
|
|
| - `qXfer:osdata:read::OFFSET,LENGTH'
|
| - Access the target's "operating system information". *Note
|
| - Operating System Information::.
|
| + Running `configure HOST' and then running `make' builds the `bfd',
|
| +`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
|
| +The configured source files, and the binaries, are left in the
|
| +corresponding source directories.
|
|
|
| + `configure' is a Bourne-shell (`/bin/sh') script; if your system
|
| +does not recognize this automatically when you run a different shell,
|
| +you may need to run `sh' on it explicitly:
|
|
|
| - Reply:
|
| - `m DATA'
|
| - Data DATA (*note Binary Data::) has been read from the
|
| - target. There may be more data at a higher address (although
|
| - it is permitted to return `m' even for the last valid block
|
| - of data, as long as at least one byte of data was read).
|
| - DATA may have fewer bytes than the LENGTH in the request.
|
| + sh configure HOST
|
|
|
| - `l DATA'
|
| - Data DATA (*note Binary Data::) has been read from the target.
|
| - There is no more data to be read. DATA may have fewer bytes
|
| - than the LENGTH in the request.
|
| -
|
| - `l'
|
| - The OFFSET in the request is at the end of the data. There
|
| - is no more data to be read.
|
| + If you run `configure' from a directory that contains source
|
| +directories for multiple libraries or programs, such as the
|
| +`gdb-7.6.50.20131211-cvs' source directory for version
|
| +7.6.50.20131211-cvs, `configure' creates configuration files for every
|
| +directory level underneath (unless you tell it not to, with the
|
| +`--norecursion' option).
|
|
|
| - `E00'
|
| - The request was malformed, or ANNEX was invalid.
|
| + You should run the `configure' script from the top directory in the
|
| +source tree, the `gdb-VERSION-NUMBER' directory. If you run
|
| +`configure' from one of the subdirectories, you will configure only
|
| +that subdirectory. That is usually not what you want. In particular,
|
| +if you run the first `configure' from the `gdb' subdirectory of the
|
| +`gdb-VERSION-NUMBER' directory, you will omit the configuration of
|
| +`bfd', `readline', and other sibling directories of the `gdb'
|
| +subdirectory. This leads to build errors about missing include files
|
| +such as `bfd/bfd.h'.
|
|
|
| - `E NN'
|
| - The offset was invalid, or there was an error encountered
|
| - reading the data. NN is a hex-encoded `errno' value.
|
| + You can install `gdb' anywhere; it has no hardwired paths. However,
|
| +you should make sure that the shell on your path (named by the `SHELL'
|
| +environment variable) is publicly readable. Remember that GDB uses the
|
| +shell to start your program--some systems refuse to let GDB debug child
|
| +processes whose programs are not readable.
|
|
|
| - `'
|
| - An empty reply indicates the OBJECT string was not recognized
|
| - by the stub, or that the object does not support reading.
|
| +
|
| +File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB
|
|
|
| -`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
|
| - Write uninterpreted bytes into the target's special data area
|
| - identified by the keyword OBJECT, starting at OFFSET bytes into
|
| - the data. DATA... is the binary-encoded data (*note Binary
|
| - Data::) to be written. The content and encoding of ANNEX is
|
| - specific to OBJECT; it can supply additional details about what
|
| - data to access.
|
| +C.3 Compiling GDB in Another Directory
|
| +======================================
|
|
|
| - Here are the specific requests of this form defined so far. All
|
| - `qXfer:OBJECT:write:...' requests use the same reply formats,
|
| - listed below.
|
| +If you want to run GDB versions for several host or target machines,
|
| +you need a different `gdb' compiled for each combination of host and
|
| +target. `configure' is designed to make this easy by allowing you to
|
| +generate each configuration in a separate subdirectory, rather than in
|
| +the source directory. If your `make' program handles the `VPATH'
|
| +feature (GNU `make' does), running `make' in each of these directories
|
| +builds the `gdb' program specified there.
|
|
|
| - `qXfer:siginfo:write::OFFSET:DATA...'
|
| - Write DATA to the extra signal information on the target
|
| - system. The annex part of the generic `qXfer' packet must be
|
| - empty (*note qXfer write::).
|
| + To build `gdb' in a separate directory, run `configure' with the
|
| +`--srcdir' option to specify where to find the source. (You also need
|
| +to specify a path to find `configure' itself from your working
|
| +directory. If the path to `configure' would be the same as the
|
| +argument to `--srcdir', you can leave out the `--srcdir' option; it is
|
| +assumed.)
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| + For example, with version 7.6.50.20131211-cvs, you can build GDB in a
|
| +separate directory for a Sun 4 like this:
|
|
|
| - `qXfer:spu:write:ANNEX:OFFSET:DATA...'
|
| - Write DATA to an `spufs' file on the target system. The
|
| - annex specifies which file to write; it must be of the form
|
| - `ID/NAME', where ID specifies an SPU context ID in the target
|
| - process, and NAME identifes the `spufs' file in that context
|
| - to be accessed.
|
| + cd gdb-7.6.50.20131211-cvs
|
| + mkdir ../gdb-sun4
|
| + cd ../gdb-sun4
|
| + ../gdb-7.6.50.20131211-cvs/configure sun4
|
| + make
|
|
|
| - This packet is not probed by default; the remote stub must
|
| - request it, by supplying an appropriate `qSupported' response
|
| - (*note qSupported::).
|
| + When `configure' builds a configuration using a remote source
|
| +directory, it creates a tree for the binaries with the same structure
|
| +(and using the same names) as the tree under the source directory. In
|
| +the example, you'd find the Sun 4 library `libiberty.a' in the
|
| +directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
|
|
|
| - Reply:
|
| - `NN'
|
| - NN (hex encoded) is the number of bytes written. This may be
|
| - fewer bytes than supplied in the request.
|
| + Make sure that your path to the `configure' script has just one
|
| +instance of `gdb' in it. If your path to `configure' looks like
|
| +`../gdb-7.6.50.20131211-cvs/gdb/configure', you are configuring only
|
| +one subdirectory of GDB, not the whole package. This leads to build
|
| +errors about missing include files such as `bfd/bfd.h'.
|
|
|
| - `E00'
|
| - The request was malformed, or ANNEX was invalid.
|
| + One popular reason to build several GDB configurations in separate
|
| +directories is to configure GDB for cross-compiling (where GDB runs on
|
| +one machine--the "host"--while debugging programs that run on another
|
| +machine--the "target"). You specify a cross-debugging target by giving
|
| +the `--target=TARGET' option to `configure'.
|
|
|
| - `E NN'
|
| - The offset was invalid, or there was an error encountered
|
| - writing the data. NN is a hex-encoded `errno' value.
|
| + When you run `make' to build a program or library, you must run it
|
| +in a configured directory--whatever directory you were in when you
|
| +called `configure' (or one of its subdirectories).
|
|
|
| - `'
|
| - An empty reply indicates the OBJECT string was not recognized
|
| - by the stub, or that the object does not support writing.
|
| + The `Makefile' that `configure' generates in each source directory
|
| +also runs recursively. If you type `make' in a source directory such
|
| +as `gdb-7.6.50.20131211-cvs' (or in a separate configured directory
|
| +configured with `--srcdir=DIRNAME/gdb-7.6.50.20131211-cvs'), you will
|
| +build all the required libraries, and then build GDB.
|
|
|
| -`qXfer:OBJECT:OPERATION:...'
|
| - Requests of this form may be added in the future. When a stub does
|
| - not recognize the OBJECT keyword, or its support for OBJECT does
|
| - not recognize the OPERATION keyword, the stub must respond with an
|
| - empty packet.
|
| + When you have multiple hosts or targets configured in separate
|
| +directories, you can run `make' on them in parallel (for example, if
|
| +they are NFS-mounted on each of the hosts); they will not interfere
|
| +with each other.
|
|
|
| -`qAttached:PID'
|
| - Return an indication of whether the remote server attached to an
|
| - existing process or created a new process. When the multiprocess
|
| - protocol extensions are supported (*note multiprocess
|
| - extensions::), PID is an integer in hexadecimal format identifying
|
| - the target process. Otherwise, GDB will omit the PID field and
|
| - the query packet will be simplified as `qAttached'.
|
| +
|
| +File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB
|
|
|
| - This query is used, for example, to know whether the remote process
|
| - should be detached or killed when a GDB session is ended with the
|
| - `quit' command.
|
| +C.4 Specifying Names for Hosts and Targets
|
| +==========================================
|
|
|
| - Reply:
|
| - `1'
|
| - The remote server attached to an existing process.
|
| +The specifications used for hosts and targets in the `configure' script
|
| +are based on a three-part naming scheme, but some short predefined
|
| +aliases are also supported. The full naming scheme encodes three pieces
|
| +of information in the following pattern:
|
|
|
| - `0'
|
| - The remote server created a new process.
|
| + ARCHITECTURE-VENDOR-OS
|
|
|
| - `E NN'
|
| - A badly formed request or an error was encountered.
|
| + For example, you can use the alias `sun4' as a HOST argument, or as
|
| +the value for TARGET in a `--target=TARGET' option. The equivalent
|
| +full name is `sparc-sun-sunos4'.
|
|
|
| + The `configure' script accompanying GDB does not provide any query
|
| +facility to list all supported host and target names or aliases.
|
| +`configure' calls the Bourne shell script `config.sub' to map
|
| +abbreviations to full names; you can read the script, if you wish, or
|
| +you can use it to test your guesses on abbreviations--for example:
|
|
|
| - ---------- Footnotes ----------
|
| + % sh config.sub i386-linux
|
| + i386-pc-linux-gnu
|
| + % sh config.sub alpha-linux
|
| + alpha-unknown-linux-gnu
|
| + % sh config.sub hp9k700
|
| + hppa1.1-hp-hpux
|
| + % sh config.sub sun4
|
| + sparc-sun-sunos4.1.1
|
| + % sh config.sub sun3
|
| + m68k-sun-sunos4.1.1
|
| + % sh config.sub i986v
|
| + Invalid configuration `i986v': machine `i986v' not recognized
|
|
|
| - (1) The `qP' and `qL' packets predate these conventions, and have
|
| -arguments without any terminator for the packet name; we suspect they
|
| -are in widespread use in places that are difficult to upgrade. The
|
| -`qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
|
| -are known to not check for the end of the packet.
|
| +`config.sub' is also distributed in the GDB source directory
|
| +(`gdb-7.6.50.20131211-cvs', for version 7.6.50.20131211-cvs).
|
|
|
|
|
| -File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
|
| -
|
| -E.5 Architecture-Specific Protocol Details
|
| -==========================================
|
| +File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB
|
|
|
| -This section describes how the remote protocol is applied to specific
|
| -target architectures. Also see *Note Standard Target Features::, for
|
| -details of XML target descriptions for each architecture.
|
| +C.5 `configure' Options
|
| +=======================
|
|
|
| -* Menu:
|
| +Here is a summary of the `configure' options and arguments that are
|
| +most often useful for building GDB. `configure' also has several other
|
| +options not listed here. *note (configure.info)What Configure Does::,
|
| +for a full explanation of `configure'.
|
|
|
| -* ARM-Specific Protocol Details::
|
| -* MIPS-Specific Protocol Details::
|
| + configure [--help]
|
| + [--prefix=DIR]
|
| + [--exec-prefix=DIR]
|
| + [--srcdir=DIRNAME]
|
| + [--norecursion] [--rm]
|
| + [--target=TARGET]
|
| + HOST
|
|
|
| -
|
| -File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details
|
| +You may introduce options with a single `-' rather than `--' if you
|
| +prefer; but you may abbreviate option names if you use `--'.
|
|
|
| -E.5.1 ARM-specific Protocol Details
|
| ------------------------------------
|
| +`--help'
|
| + Display a quick summary of how to invoke `configure'.
|
|
|
| -* Menu:
|
| +`--prefix=DIR'
|
| + Configure the source to install programs and files under directory
|
| + `DIR'.
|
|
|
| -* ARM Breakpoint Kinds::
|
| +`--exec-prefix=DIR'
|
| + Configure the source to install programs under directory `DIR'.
|
|
|
| -
|
| -File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details
|
| +`--srcdir=DIRNAME'
|
| + *Warning: using this option requires GNU `make', or another `make'
|
| + that implements the `VPATH' feature.*
|
| + Use this option to make configurations in directories separate
|
| + from the GDB source directories. Among other things, you can use
|
| + this to build (or maintain) several configurations simultaneously,
|
| + in separate directories. `configure' writes
|
| + configuration-specific files in the current directory, but
|
| + arranges for them to use the source in the directory DIRNAME.
|
| + `configure' creates directories under the working directory in
|
| + parallel to the source directories below DIRNAME.
|
|
|
| -E.5.1.1 ARM Breakpoint Kinds
|
| -............................
|
| +`--norecursion'
|
| + Configure only the directory level where `configure' is executed;
|
| + do not propagate configuration to subdirectories.
|
|
|
| -These breakpoint kinds are defined for the `Z0' and `Z1' packets.
|
| +`--target=TARGET'
|
| + Configure GDB for cross-debugging programs running on the specified
|
| + TARGET. Without this option, GDB is configured to debug programs
|
| + that run on the same machine (HOST) as GDB itself.
|
|
|
| -2
|
| - 16-bit Thumb mode breakpoint.
|
| + There is no convenient way to generate a list of all available
|
| + targets.
|
|
|
| -3
|
| - 32-bit Thumb mode (Thumb-2) breakpoint.
|
| +`HOST ...'
|
| + Configure GDB to run on the specified HOST.
|
|
|
| -4
|
| - 32-bit ARM mode breakpoint.
|
| + There is no convenient way to generate a list of all available
|
| + hosts.
|
|
|
| + There are many other options available as well, but they are
|
| +generally needed for special purposes only.
|
|
|
|
|
| -File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details
|
| +File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB
|
|
|
| -E.5.2 MIPS-specific Protocol Details
|
| -------------------------------------
|
| +C.6 System-wide configuration and settings
|
| +==========================================
|
|
|
| -* Menu:
|
| +GDB can be configured to have a system-wide init file; this file will
|
| +be read and executed at startup (*note What GDB does during startup:
|
| +Startup.).
|
|
|
| -* MIPS Register packet Format::
|
| -* MIPS Breakpoint Kinds::
|
| + Here is the corresponding configure option:
|
|
|
| -
|
| -File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details
|
| -
|
| -E.5.2.1 MIPS Register Packet Format
|
| -...................................
|
| +`--with-system-gdbinit=FILE'
|
| + Specify that the default location of the system-wide init file is
|
| + FILE.
|
|
|
| -The following `g'/`G' packets have previously been defined. In the
|
| -below, some thirty-two bit registers are transferred as sixty-four
|
| -bits. Those registers should be zero/sign extended (which?) to fill
|
| -the space allocated. Register bytes are transferred in target byte
|
| -order. The two nibbles within a register byte are transferred
|
| -most-significant - least-significant.
|
| + If GDB has been configured with the option `--prefix=$prefix', it
|
| +may be subject to relocation. Two possible cases:
|
|
|
| -MIPS32
|
| - All registers are transferred as thirty-two bit quantities in the
|
| - order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
|
| - floating-point registers; fsr; fir; fp.
|
| + * If the default location of this init file contains `$prefix', it
|
| + will be subject to relocation. Suppose that the configure options
|
| + are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
|
| + if GDB is moved from `$prefix' to `$install', the system init file
|
| + is looked for as `$install/etc/gdbinit' instead of
|
| + `$prefix/etc/gdbinit'.
|
|
|
| -MIPS64
|
| - All registers are transferred as sixty-four bit quantities
|
| - (including thirty-two bit registers such as `sr'). The ordering
|
| - is the same as `MIPS32'.
|
| + * By contrast, if the default location does not contain the prefix,
|
| + it will not be relocated. E.g. if GDB has been configured with
|
| + `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
|
| + then GDB will always look for `/usr/share/gdb/gdbinit', wherever
|
| + GDB is installed.
|
|
|
| + If the configured location of the system-wide init file (as given by
|
| +the `--with-system-gdbinit' option at configure time) is in the
|
| +data-directory (as specified by `--with-gdb-datadir' at configure time)
|
| +or in one of its subdirectories, then GDB will look for the system-wide
|
| +init file in the directory specified by the `--data-directory'
|
| +command-line option. Note that the system-wide init file is only read
|
| +once, during GDB initialization. If the data-directory is changed
|
| +after GDB has started with the `set data-directory' command, the file
|
| +will not be reread.
|
|
|
| -
|
| -File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details
|
| +* Menu:
|
|
|
| -E.5.2.2 MIPS Breakpoint Kinds
|
| -.............................
|
| +* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts
|
|
|
| -These breakpoint kinds are defined for the `Z0' and `Z1' packets.
|
| +
|
| +File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration
|
|
|
| -2
|
| - 16-bit MIPS16 mode breakpoint.
|
| +C.6.1 Installed System-wide Configuration Scripts
|
| +-------------------------------------------------
|
|
|
| -3
|
| - 16-bit microMIPS mode breakpoint.
|
| +The `system-gdbinit' directory, located inside the data-directory (as
|
| +specified by `--with-gdb-datadir' at configure time) contains a number
|
| +of scripts which can be used as system-wide init files. To
|
| +automatically source those scripts at startup, GDB should be configured
|
| +with `--with-system-gdbinit'. Otherwise, any user should be able to
|
| +source them by hand as needed.
|
|
|
| -4
|
| - 32-bit standard MIPS mode breakpoint.
|
| + The following scripts are currently available:
|
| + * `elinos.py' This script is useful when debugging a program on an
|
| + ELinOS target. It takes advantage of the environment variables
|
| + defined in a standard ELinOS environment in order to determine the
|
| + location of the system shared libraries, and then sets the
|
| + `solib-absolute-prefix' and `solib-search-path' variables
|
| + appropriately.
|
|
|
| -5
|
| - 32-bit microMIPS mode breakpoint.
|
| + * `wrs-linux.py' This script is useful when debugging a program on a
|
| + target running Wind River Linux. It expects the `ENV_PREFIX' to
|
| + be set to the host-side sysroot used by the target system.
|
|
|
|
|
|
|
| -File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol
|
| -
|
| -E.6 Tracepoint Packets
|
| -======================
|
| -
|
| -Here we describe the packets GDB uses to implement tracepoints (*note
|
| -Tracepoints::).
|
| +File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top
|
|
|
| -`QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
|
| - Create a new tracepoint, number N, at ADDR. If ENA is `E', then
|
| - the tracepoint is enabled; if it is `D', then the tracepoint is
|
| - disabled. STEP is the tracepoint's step count, and PASS is its
|
| - pass count. If an `F' is present, then the tracepoint is to be a
|
| - fast tracepoint, and the FLEN is the number of bytes that the
|
| - target should copy elsewhere to make room for the tracepoint. If
|
| - an `X' is present, it introduces a tracepoint condition, which
|
| - consists of a hexadecimal length, followed by a comma and
|
| - hex-encoded bytes, in a manner similar to action encodings as
|
| - described below. If the trailing `-' is present, further `QTDP'
|
| - packets will follow to specify this tracepoint's actions.
|
| +Appendix D Maintenance Commands
|
| +*******************************
|
|
|
| - Replies:
|
| - `OK'
|
| - The packet was understood and carried out.
|
| +In addition to commands intended for GDB users, GDB includes a number
|
| +of commands intended for GDB developers, that are not documented
|
| +elsewhere in this manual. These commands are provided here for
|
| +reference. (For commands that turn on debugging messages, see *note
|
| +Debugging Output::.)
|
|
|
| - `qRelocInsn'
|
| - *Note Relocate instruction reply packet: Tracepoint Packets.
|
| +`maint agent [-at LOCATION,] EXPRESSION'
|
| +`maint agent-eval [-at LOCATION,] EXPRESSION'
|
| + Translate the given EXPRESSION into remote agent bytecodes. This
|
| + command is useful for debugging the Agent Expression mechanism
|
| + (*note Agent Expressions::). The `agent' version produces an
|
| + expression useful for data collection, such as by tracepoints,
|
| + while `maint agent-eval' produces an expression that evaluates
|
| + directly to a result. For instance, a collection expression for
|
| + `globa + globb' will include bytecodes to record four bytes of
|
| + memory at each of the addresses of `globa' and `globb', while
|
| + discarding the result of the addition, while an evaluation
|
| + expression will do the addition and return the sum. If `-at' is
|
| + given, generate remote agent bytecode for LOCATION. If not,
|
| + generate remote agent bytecode for current frame PC address.
|
|
|
| - `'
|
| - The packet was not recognized.
|
| +`maint agent-printf FORMAT,EXPR,...'
|
| + Translate the given format string and list of argument expressions
|
| + into remote agent bytecodes and display them as a disassembled
|
| + list. This command is useful for debugging the agent version of
|
| + dynamic printf (*note Dynamic Printf::).
|
|
|
| -`QTDP:-N:ADDR:[S]ACTION...[-]'
|
| - Define actions to be taken when a tracepoint is hit. N and ADDR
|
| - must be the same as in the initial `QTDP' packet for this
|
| - tracepoint. This packet may only be sent immediately after
|
| - another `QTDP' packet that ended with a `-'. If the trailing `-'
|
| - is present, further `QTDP' packets will follow, specifying more
|
| - actions for this tracepoint.
|
| +`maint info breakpoints'
|
| + Using the same format as `info breakpoints', display both the
|
| + breakpoints you've set explicitly, and those GDB is using for
|
| + internal purposes. Internal breakpoints are shown with negative
|
| + breakpoint numbers. The type column identifies what kind of
|
| + breakpoint is shown:
|
|
|
| - In the series of action packets for a given tracepoint, at most one
|
| - can have an `S' before its first ACTION. If such a packet is
|
| - sent, it and the following packets define "while-stepping"
|
| - actions. Any prior packets define ordinary actions -- that is,
|
| - those taken when the tracepoint is first hit. If no action packet
|
| - has an `S', then all the packets in the series specify ordinary
|
| - tracepoint actions.
|
| + `breakpoint'
|
| + Normal, explicitly set breakpoint.
|
|
|
| - The `ACTION...' portion of the packet is a series of actions,
|
| - concatenated without separators. Each action has one of the
|
| - following forms:
|
| + `watchpoint'
|
| + Normal, explicitly set watchpoint.
|
|
|
| - `R MASK'
|
| - Collect the registers whose bits are set in MASK. MASK is a
|
| - hexadecimal number whose I'th bit is set if register number I
|
| - should be collected. (The least significant bit is numbered
|
| - zero.) Note that MASK may be any number of digits long; it
|
| - may not fit in a 32-bit word.
|
| + `longjmp'
|
| + Internal breakpoint, used to handle correctly stepping through
|
| + `longjmp' calls.
|
|
|
| - `M BASEREG,OFFSET,LEN'
|
| - Collect LEN bytes of memory starting at the address in
|
| - register number BASEREG, plus OFFSET. If BASEREG is `-1',
|
| - then the range has a fixed address: OFFSET is the address of
|
| - the lowest byte to collect. The BASEREG, OFFSET, and LEN
|
| - parameters are all unsigned hexadecimal values (the `-1'
|
| - value for BASEREG is a special case).
|
| + `longjmp resume'
|
| + Internal breakpoint at the target of a `longjmp'.
|
|
|
| - `X LEN,EXPR'
|
| - Evaluate EXPR, whose length is LEN, and collect memory as it
|
| - directs. EXPR is an agent expression, as described in *Note
|
| - Agent Expressions::. Each byte of the expression is encoded
|
| - as a two-digit hex number in the packet; LEN is the number of
|
| - bytes in the expression (and thus one-half the number of hex
|
| - digits in the packet).
|
| + `until'
|
| + Temporary internal breakpoint used by the GDB `until' command.
|
|
|
| + `finish'
|
| + Temporary internal breakpoint used by the GDB `finish'
|
| + command.
|
|
|
| - Any number of actions may be packed together in a single `QTDP'
|
| - packet, as long as the packet does not exceed the maximum packet
|
| - length (400 bytes, for many stubs). There may be only one `R'
|
| - action per tracepoint, and it must precede any `M' or `X' actions.
|
| - Any registers referred to by `M' and `X' actions must be
|
| - collected by a preceding `R' action. (The "while-stepping"
|
| - actions are treated as if they were attached to a separate
|
| - tracepoint, as far as these restrictions are concerned.)
|
| + `shlib events'
|
| + Shared library events.
|
|
|
| - Replies:
|
| - `OK'
|
| - The packet was understood and carried out.
|
|
|
| - `qRelocInsn'
|
| - *Note Relocate instruction reply packet: Tracepoint Packets.
|
| +`maint info bfds'
|
| + This prints information about each `bfd' object that is known to
|
| + GDB. *Note BFD: (bfd)Top.
|
|
|
| - `'
|
| - The packet was not recognized.
|
| +`set displaced-stepping'
|
| +`show displaced-stepping'
|
| + Control whether or not GDB will do "displaced stepping" if the
|
| + target supports it. Displaced stepping is a way to single-step
|
| + over breakpoints without removing them from the inferior, by
|
| + executing an out-of-line copy of the instruction that was
|
| + originally at the breakpoint location. It is also known as
|
| + out-of-line single-stepping.
|
|
|
| -`QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES'
|
| - Specify a source string of tracepoint N at address ADDR. This is
|
| - useful to get accurate reproduction of the tracepoints originally
|
| - downloaded at the beginning of the trace run. TYPE is the name of
|
| - the tracepoint part, such as `cond' for the tracepoint's
|
| - conditional expression (see below for a list of types), while
|
| - BYTES is the string, encoded in hexadecimal.
|
| + `set displaced-stepping on'
|
| + If the target architecture supports it, GDB will use
|
| + displaced stepping to step over breakpoints.
|
|
|
| - START is the offset of the BYTES within the overall source string,
|
| - while SLEN is the total length of the source string. This is
|
| - intended for handling source strings that are longer than will fit
|
| - in a single packet.
|
| + `set displaced-stepping off'
|
| + GDB will not use displaced stepping to step over breakpoints,
|
| + even if such is supported by the target architecture.
|
|
|
| - The available string types are `at' for the location, `cond' for
|
| - the conditional, and `cmd' for an action command. GDB sends a
|
| - separate packet for each command in the action list, in the same
|
| - order in which the commands are stored in the list.
|
| + `set displaced-stepping auto'
|
| + This is the default mode. GDB will use displaced stepping
|
| + only if non-stop mode is active (*note Non-Stop Mode::) and
|
| + the target architecture supports displaced stepping.
|
|
|
| - The target does not need to do anything with source strings except
|
| - report them back as part of the replies to the `qTfP'/`qTsP' query
|
| - packets.
|
| +`maint check-psymtabs'
|
| + Check the consistency of currently expanded psymtabs versus
|
| + symtabs. Use this to check, for example, whether a symbol is in
|
| + one but not the other.
|
|
|
| - Although this packet is optional, and GDB will only send it if the
|
| - target replies with `TracepointSource' *Note General Query
|
| - Packets::, it makes both disconnected tracing and trace files much
|
| - easier to use. Otherwise the user must be careful that the
|
| - tracepoints in effect while looking at trace frames are identical
|
| - to the ones in effect during the trace run; even a small
|
| - discrepancy could cause `tdump' not to work, or a particular trace
|
| - frame not be found.
|
| +`maint check-symtabs'
|
| + Check the consistency of currently expanded symtabs.
|
|
|
| -`QTDV:N:VALUE'
|
| - Create a new trace state variable, number N, with an initial value
|
| - of VALUE, which is a 64-bit signed integer. Both N and VALUE are
|
| - encoded as hexadecimal values. GDB has the option of not using
|
| - this packet for initial values of zero; the target should simply
|
| - create the trace state variables as they are mentioned in
|
| - expressions.
|
| +`maint expand-symtabs [REGEXP]'
|
| + Expand symbol tables. If REGEXP is specified, only expand symbol
|
| + tables for file names matching REGEXP.
|
|
|
| -`QTFrame:N'
|
| - Select the N'th tracepoint frame from the buffer, and use the
|
| - register and memory contents recorded there to answer subsequent
|
| - request packets from GDB.
|
| +`maint cplus first_component NAME'
|
| + Print the first C++ class/namespace component of NAME.
|
|
|
| - A successful reply from the stub indicates that the stub has found
|
| - the requested frame. The response is a series of parts,
|
| - concatenated without separators, describing the frame we selected.
|
| - Each part has one of the following forms:
|
| +`maint cplus namespace'
|
| + Print the list of possible C++ namespaces.
|
|
|
| - `F F'
|
| - The selected frame is number N in the trace frame buffer; F
|
| - is a hexadecimal number. If F is `-1', then there was no
|
| - frame matching the criteria in the request packet.
|
| +`maint demangle NAME'
|
| + Demangle a C++ or Objective-C mangled NAME.
|
|
|
| - `T T'
|
| - The selected trace frame records a hit of tracepoint number T;
|
| - T is a hexadecimal number.
|
| +`maint deprecate COMMAND [REPLACEMENT]'
|
| +`maint undeprecate COMMAND'
|
| + Deprecate or undeprecate the named COMMAND. Deprecated commands
|
| + cause GDB to issue a warning when you use them. The optional
|
| + argument REPLACEMENT says which newer command should be used in
|
| + favor of the deprecated one; if it is given, GDB will mention the
|
| + replacement as part of the warning.
|
|
|
| +`maint dump-me'
|
| + Cause a fatal signal in the debugger and force it to dump its core.
|
| + This is supported only on systems which support aborting a program
|
| + with the `SIGQUIT' signal.
|
|
|
| -`QTFrame:pc:ADDR'
|
| - Like `QTFrame:N', but select the first tracepoint frame after the
|
| - currently selected frame whose PC is ADDR; ADDR is a hexadecimal
|
| - number.
|
| -
|
| -`QTFrame:tdp:T'
|
| - Like `QTFrame:N', but select the first tracepoint frame after the
|
| - currently selected frame that is a hit of tracepoint T; T is a
|
| - hexadecimal number.
|
| -
|
| -`QTFrame:range:START:END'
|
| - Like `QTFrame:N', but select the first tracepoint frame after the
|
| - currently selected frame whose PC is between START (inclusive) and
|
| - END (inclusive); START and END are hexadecimal numbers.
|
| -
|
| -`QTFrame:outside:START:END'
|
| - Like `QTFrame:range:START:END', but select the first frame
|
| - _outside_ the given range of addresses (exclusive).
|
| +`maint internal-error [MESSAGE-TEXT]'
|
| +`maint internal-warning [MESSAGE-TEXT]'
|
| + Cause GDB to call the internal function `internal_error' or
|
| + `internal_warning' and hence behave as though an internal error or
|
| + internal warning has been detected. In addition to reporting the
|
| + internal problem, these functions give the user the opportunity to
|
| + either quit GDB or create a core file of the current GDB session.
|
|
|
| -`qTMinFTPILen'
|
| - This packet requests the minimum length of instruction at which a
|
| - fast tracepoint (*note Set Tracepoints::) may be placed. For
|
| - instance, on the 32-bit x86 architecture, it is possible to use a
|
| - 4-byte jump, but it depends on the target system being able to
|
| - create trampolines in the first 64K of memory, which might or
|
| - might not be possible for that system. So the reply to this
|
| - packet will be 4 if it is able to arrange for that.
|
| + These commands take an optional parameter MESSAGE-TEXT that is
|
| + used as the text of the error or warning message.
|
|
|
| - Replies:
|
| + Here's an example of using `internal-error':
|
|
|
| - `0'
|
| - The minimum instruction length is currently unknown.
|
| + (gdb) maint internal-error testing, 1, 2
|
| + .../maint.c:121: internal-error: testing, 1, 2
|
| + A problem internal to GDB has been detected. Further
|
| + debugging may prove unreliable.
|
| + Quit this debugging session? (y or n) n
|
| + Create a core file? (y or n) n
|
| + (gdb)
|
|
|
| - `LENGTH'
|
| - The minimum instruction length is LENGTH, where LENGTH is
|
| - greater or equal to 1. LENGTH is a hexadecimal number. A
|
| - reply of 1 means that a fast tracepoint may be placed on any
|
| - instruction regardless of size.
|
| +`maint set internal-error ACTION [ask|yes|no]'
|
| +`maint show internal-error ACTION'
|
| +`maint set internal-warning ACTION [ask|yes|no]'
|
| +`maint show internal-warning ACTION'
|
| + When GDB reports an internal problem (error or warning) it gives
|
| + the user the opportunity to both quit GDB and create a core file
|
| + of the current GDB session. These commands let you override the
|
| + default behaviour for each particular ACTION, described in the
|
| + table below.
|
|
|
| - `E'
|
| - An error has occurred.
|
| + `quit'
|
| + You can specify that GDB should always (yes) or never (no)
|
| + quit. The default is to ask the user what to do.
|
|
|
| - `'
|
| - An empty reply indicates that the request is not supported by
|
| - the stub.
|
| + `corefile'
|
| + You can specify that GDB should always (yes) or never (no)
|
| + create a core file. The default is to ask the user what to
|
| + do.
|
|
|
| -`QTStart'
|
| - Begin the tracepoint experiment. Begin collecting data from
|
| - tracepoint hits in the trace frame buffer. This packet supports
|
| - the `qRelocInsn' reply (*note Relocate instruction reply packet:
|
| - Tracepoint Packets.).
|
| +`maint packet TEXT'
|
| + If GDB is talking to an inferior via the serial protocol, then
|
| + this command sends the string TEXT to the inferior, and displays
|
| + the response packet. GDB supplies the initial `$' character, the
|
| + terminating `#' character, and the checksum.
|
|
|
| -`QTStop'
|
| - End the tracepoint experiment. Stop collecting trace frames.
|
| +`maint print architecture [FILE]'
|
| + Print the entire architecture configuration. The optional argument
|
| + FILE names the file where the output goes.
|
|
|
| -`QTEnable:N:ADDR'
|
| - Enable tracepoint N at address ADDR in a started tracepoint
|
| - experiment. If the tracepoint was previously disabled, then
|
| - collection of data from it will resume.
|
| +`maint print c-tdesc'
|
| + Print the current target description (*note Target Descriptions::)
|
| + as a C source file. The created source file can be used in GDB
|
| + when an XML parser is not available to parse the description.
|
|
|
| -`QTDisable:N:ADDR'
|
| - Disable tracepoint N at address ADDR in a started tracepoint
|
| - experiment. No more data will be collected from the tracepoint
|
| - unless `QTEnable:N:ADDR' is subsequently issued.
|
| +`maint print dummy-frames'
|
| + Prints the contents of GDB's internal dummy-frame stack.
|
|
|
| -`QTinit'
|
| - Clear the table of tracepoints, and empty the trace frame buffer.
|
| + (gdb) b add
|
| + ...
|
| + (gdb) print add(2,3)
|
| + Breakpoint 2, add (a=2, b=3) at ...
|
| + 58 return (a + b);
|
| + The program being debugged stopped while in a function called from GDB.
|
| + ...
|
| + (gdb) maint print dummy-frames
|
| + 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
|
| + top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
|
| + call_lo=0x01014000 call_hi=0x01014001
|
| + (gdb)
|
|
|
| -`QTro:START1,END1:START2,END2:...'
|
| - Establish the given ranges of memory as "transparent". The stub
|
| - will answer requests for these ranges from memory's current
|
| - contents, if they were not collected as part of the tracepoint hit.
|
| + Takes an optional file parameter.
|
|
|
| - GDB uses this to mark read-only regions of memory, like those
|
| - containing program code. Since these areas never change, they
|
| - should still have the same contents they did when the tracepoint
|
| - was hit, so there's no reason for the stub to refuse to provide
|
| - their contents.
|
| +`maint print registers [FILE]'
|
| +`maint print raw-registers [FILE]'
|
| +`maint print cooked-registers [FILE]'
|
| +`maint print register-groups [FILE]'
|
| +`maint print remote-registers [FILE]'
|
| + Print GDB's internal register data structures.
|
|
|
| -`QTDisconnected:VALUE'
|
| - Set the choice to what to do with the tracing run when GDB
|
| - disconnects from the target. A VALUE of 1 directs the target to
|
| - continue the tracing run, while 0 tells the target to stop tracing
|
| - if GDB is no longer in the picture.
|
| + The command `maint print raw-registers' includes the contents of
|
| + the raw register cache; the command `maint print cooked-registers'
|
| + includes the (cooked) value of all registers, including registers
|
| + which aren't available on the target nor visible to user; the
|
| + command `maint print register-groups' includes the groups that
|
| + each register is a member of; and the command `maint print
|
| + remote-registers' includes the remote target's register numbers
|
| + and offsets in the `G' packets.
|
|
|
| -`qTStatus'
|
| - Ask the stub if there is a trace experiment running right now.
|
| + These commands take an optional parameter, a file name to which to
|
| + write the information.
|
|
|
| - The reply has the form:
|
| +`maint print reggroups [FILE]'
|
| + Print GDB's internal register group data structures. The optional
|
| + argument FILE tells to what file to write the information.
|
|
|
| - `TRUNNING[;FIELD]...'
|
| - RUNNING is a single digit `1' if the trace is presently
|
| - running, or `0' if not. It is followed by semicolon-separated
|
| - optional fields that an agent may use to report additional
|
| - status.
|
| + The register groups info looks like this:
|
|
|
| + (gdb) maint print reggroups
|
| + Group Type
|
| + general user
|
| + float user
|
| + all user
|
| + vector user
|
| + system user
|
| + save internal
|
| + restore internal
|
|
|
| - If the trace is not running, the agent may report any of several
|
| - explanations as one of the optional fields:
|
| +`flushregs'
|
| + This command forces GDB to flush its internal register cache.
|
|
|
| - `tnotrun:0'
|
| - No trace has been run yet.
|
| +`maint print objfiles [REGEXP]'
|
| + Print a dump of all known object files. If REGEXP is specified,
|
| + only print object files whose names match REGEXP. For each object
|
| + file, this command prints its name, address in memory, and all of
|
| + its psymtabs and symtabs.
|
|
|
| - `tstop[:TEXT]:0'
|
| - The trace was stopped by a user-originated stop command. The
|
| - optional TEXT field is a user-supplied string supplied as
|
| - part of the stop command (for instance, an explanation of why
|
| - the trace was stopped manually). It is hex-encoded.
|
| +`maint print section-scripts [REGEXP]'
|
| + Print a dump of scripts specified in the `.debug_gdb_section'
|
| + section. If REGEXP is specified, only print scripts loaded by
|
| + object files matching REGEXP. For each script, this command
|
| + prints its name as specified in the objfile, and the full path if
|
| + known. *Note dotdebug_gdb_scripts section::.
|
|
|
| - `tfull:0'
|
| - The trace stopped because the trace buffer filled up.
|
| +`maint print statistics'
|
| + This command prints, for each object file in the program, various
|
| + data about that object file followed by the byte cache ("bcache")
|
| + statistics for the object file. The objfile data includes the
|
| + number of minimal, partial, full, and stabs symbols, the number of
|
| + types defined by the objfile, the number of as yet unexpanded psym
|
| + tables, the number of line tables and string tables, and the
|
| + amount of memory used by the various tables. The bcache
|
| + statistics include the counts, sizes, and counts of duplicates of
|
| + all and unique objects, max, average, and median entry size, total
|
| + memory used and its overhead and savings, and various measures of
|
| + the hash table size and chain lengths.
|
|
|
| - `tdisconnected:0'
|
| - The trace stopped because GDB disconnected from the target.
|
| +`maint print target-stack'
|
| + A "target" is an interface between the debugger and a particular
|
| + kind of file or process. Targets can be stacked in "strata", so
|
| + that more than one target can potentially respond to a request.
|
| + In particular, memory accesses will walk down the stack of targets
|
| + until they find a target that is interested in handling that
|
| + particular address.
|
|
|
| - `tpasscount:TPNUM'
|
| - The trace stopped because tracepoint TPNUM exceeded its pass
|
| - count.
|
| + This command prints a short description of each layer that was
|
| + pushed on the "target stack", starting from the top layer down to
|
| + the bottom one.
|
|
|
| - `terror:TEXT:TPNUM'
|
| - The trace stopped because tracepoint TPNUM had an error. The
|
| - string TEXT is available to describe the nature of the error
|
| - (for instance, a divide by zero in the condition expression).
|
| - TEXT is hex encoded.
|
| +`maint print type EXPR'
|
| + Print the type chain for a type specified by EXPR. The argument
|
| + can be either a type name or a symbol. If it is a symbol, the
|
| + type of that symbol is described. The type chain produced by this
|
| + command is a recursive definition of the data type as stored in
|
| + GDB's data structures, including its flags and contained types.
|
|
|
| - `tunknown:0'
|
| - The trace stopped for some other reason.
|
| +`maint set dwarf2 always-disassemble'
|
|
|
| +`maint show dwarf2 always-disassemble'
|
| + Control the behavior of `info address' when using DWARF debugging
|
| + information.
|
|
|
| - Additional optional fields supply statistical and other
|
| - information. Although not required, they are extremely useful for
|
| - users monitoring the progress of a trace run. If a trace has
|
| - stopped, and these numbers are reported, they must reflect the
|
| - state of the just-stopped trace.
|
| + The default is `off', which means that GDB should try to describe
|
| + a variable's location in an easily readable format. When `on',
|
| + GDB will instead display the DWARF location expression in an
|
| + assembly-like format. Note that some locations are too complex
|
| + for GDB to describe simply; in this case you will always see the
|
| + disassembly form.
|
|
|
| - `tframes:N'
|
| - The number of trace frames in the buffer.
|
| + Here is an example of the resulting disassembly:
|
|
|
| - `tcreated:N'
|
| - The total number of trace frames created during the run. This
|
| - may be larger than the trace frame count, if the buffer is
|
| - circular.
|
| + (gdb) info addr argc
|
| + Symbol "argc" is a complex DWARF expression:
|
| + 1: DW_OP_fbreg 0
|
|
|
| - `tsize:N'
|
| - The total size of the trace buffer, in bytes.
|
| + For more information on these expressions, see the DWARF standard
|
| + (http://www.dwarfstd.org/).
|
|
|
| - `tfree:N'
|
| - The number of bytes still unused in the buffer.
|
| +`maint set dwarf2 max-cache-age'
|
| +`maint show dwarf2 max-cache-age'
|
| + Control the DWARF 2 compilation unit cache.
|
|
|
| - `circular:N'
|
| - The value of the circular trace buffer flag. `1' means that
|
| - the trace buffer is circular and old trace frames will be
|
| - discarded if necessary to make room, `0' means that the trace
|
| - buffer is linear and may fill up.
|
| + In object files with inter-compilation-unit references, such as
|
| + those produced by the GCC option `-feliminate-dwarf2-dups', the
|
| + DWARF 2 reader needs to frequently refer to previously read
|
| + compilation units. This setting controls how long a compilation
|
| + unit will remain in the cache if it is not referenced. A higher
|
| + limit means that cached compilation units will be stored in memory
|
| + longer, and more total memory will be used. Setting it to zero
|
| + disables caching, which will slow down GDB startup, but reduce
|
| + memory consumption.
|
|
|
| - `disconn:N'
|
| - The value of the disconnected tracing flag. `1' means that
|
| - tracing will continue after GDB disconnects, `0' means that
|
| - the trace run will stop.
|
| +`maint set profile'
|
| +`maint show profile'
|
| + Control profiling of GDB.
|
|
|
| + Profiling will be disabled until you use the `maint set profile'
|
| + command to enable it. When you enable profiling, the system will
|
| + begin collecting timing and execution count data; when you disable
|
| + profiling or exit GDB, the results will be written to a log file.
|
| + Remember that if you use profiling, GDB will overwrite the
|
| + profiling log file (often called `gmon.out'). If you have a
|
| + record of important profiling data in a `gmon.out' file, be sure
|
| + to move it to a safe location.
|
|
|
| -`qTP:TP:ADDR'
|
| - Ask the stub for the current state of tracepoint number TP at
|
| - address ADDR.
|
| + Configuring with `--enable-profiling' arranges for GDB to be
|
| + compiled with the `-pg' compiler option.
|
|
|
| - Replies:
|
| - `VHITS:USAGE'
|
| - The tracepoint has been hit HITS times so far during the trace
|
| - run, and accounts for USAGE in the trace buffer. Note that
|
| - `while-stepping' steps are not counted as separate hits, but
|
| - the steps' space consumption is added into the usage number.
|
| +`maint set show-debug-regs'
|
| +`maint show show-debug-regs'
|
| + Control whether to show variables that mirror the hardware debug
|
| + registers. Use `on' to enable, `off' to disable. If enabled, the
|
| + debug registers values are shown when GDB inserts or removes a
|
| + hardware breakpoint or watchpoint, and when the inferior triggers
|
| + a hardware-assisted breakpoint or watchpoint.
|
|
|
| +`maint set show-all-tib'
|
| +`maint show show-all-tib'
|
| + Control whether to show all non zero areas within a 1k block
|
| + starting at thread local base, when using the `info w32
|
| + thread-information-block' command.
|
|
|
| -`qTV:VAR'
|
| - Ask the stub for the value of the trace state variable number VAR.
|
| +`maint set per-command'
|
| +`maint show per-command'
|
| + GDB can display the resources used by each command. This is
|
| + useful in debugging performance problems.
|
| +
|
| + `maint set per-command space [on|off]'
|
| + `maint show per-command space'
|
| + Enable or disable the printing of the memory used by GDB for
|
| + each command. If enabled, GDB will display how much memory
|
| + each command took, following the command's own output. This
|
| + can also be requested by invoking GDB with the `--statistics'
|
| + command-line switch (*note Mode Options::).
|
| +
|
| + `maint set per-command time [on|off]'
|
| + `maint show per-command time'
|
| + Enable or disable the printing of the execution time of GDB
|
| + for each command. If enabled, GDB will display how much time
|
| + it took to execute each command, following the command's own
|
| + output. Both CPU time and wallclock time are printed.
|
| + Printing both is useful when trying to determine whether the
|
| + cost is CPU or, e.g., disk/network latency. Note that the
|
| + CPU time printed is for GDB only, it does not include the
|
| + execution time of the inferior because there's no mechanism
|
| + currently to compute how much time was spent by GDB and how
|
| + much time was spent by the program been debugged. This can
|
| + also be requested by invoking GDB with the `--statistics'
|
| + command-line switch (*note Mode Options::).
|
| +
|
| + `maint set per-command symtab [on|off]'
|
| + `maint show per-command symtab'
|
| + Enable or disable the printing of basic symbol table
|
| + statistics for each command. If enabled, GDB will display
|
| + the following information:
|
| +
|
| + a. number of symbol tables
|
| +
|
| + b. number of primary symbol tables
|
| +
|
| + c. number of blocks in the blockvector
|
| +
|
| +`maint space VALUE'
|
| + An alias for `maint set per-command space'. A non-zero value
|
| + enables it, zero disables it.
|
| +
|
| +`maint time VALUE'
|
| + An alias for `maint set per-command time'. A non-zero value
|
| + enables it, zero disables it.
|
|
|
| - Replies:
|
| - `VVALUE'
|
| - The value of the variable is VALUE. This will be the current
|
| - value of the variable if the user is examining a running
|
| - target, or a saved value if the variable was collected in the
|
| - trace frame that the user is looking at. Note that multiple
|
| - requests may result in different reply values, such as when
|
| - requesting values while the program is running.
|
| +`maint translate-address [SECTION] ADDR'
|
| + Find the symbol stored at the location specified by the address
|
| + ADDR and an optional section name SECTION. If found, GDB prints
|
| + the name of the closest symbol and an offset from the symbol's
|
| + location to the specified address. This is similar to the `info
|
| + address' command (*note Symbols::), except that this command also
|
| + allows to find symbols in other sections.
|
|
|
| - `U'
|
| - The value of the variable is unknown. This would occur, for
|
| - example, if the user is examining a trace frame in which the
|
| - requested variable was not collected.
|
| + If section was not specified, the section in which the symbol was
|
| + found is also printed. For dynamically linked executables, the
|
| + name of executable or shared library containing the symbol is
|
| + printed as well.
|
|
|
| -`qTfP'
|
| -`qTsP'
|
| - These packets request data about tracepoints that are being used by
|
| - the target. GDB sends `qTfP' to get the first piece of data, and
|
| - multiple `qTsP' to get additional pieces. Replies to these
|
| - packets generally take the form of the `QTDP' packets that define
|
| - tracepoints. (FIXME add detailed syntax)
|
|
|
| -`qTfV'
|
| -`qTsV'
|
| - These packets request data about trace state variables that are on
|
| - the target. GDB sends `qTfV' to get the first vari of data, and
|
| - multiple `qTsV' to get additional variables. Replies to these
|
| - packets follow the syntax of the `QTDV' packets that define trace
|
| - state variables.
|
| + The following command is useful for non-interactive invocations of
|
| +GDB, such as in the test suite.
|
|
|
| -`qTfSTM'
|
| -`qTsSTM'
|
| - These packets request data about static tracepoint markers that
|
| - exist in the target program. GDB sends `qTfSTM' to get the first
|
| - piece of data, and multiple `qTsSTM' to get additional pieces.
|
| - Replies to these packets take the following form:
|
| +`set watchdog NSEC'
|
| + Set the maximum number of seconds GDB will wait for the target
|
| + operation to finish. If this time expires, GDB reports and error
|
| + and the command is aborted.
|
|
|
| - Reply:
|
| - `m ADDRESS:ID:EXTRA'
|
| - A single marker
|
| +`show watchdog'
|
| + Show the current setting of the target wait timeout.
|
|
|
| - `m ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...'
|
| - a comma-separated list of markers
|
| +
|
| +File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
|
|
|
| - `l'
|
| - (lower case letter `L') denotes end of list.
|
| +Appendix E GDB Remote Serial Protocol
|
| +*************************************
|
|
|
| - `E NN'
|
| - An error occurred. NN are hex digits.
|
| +* Menu:
|
|
|
| - `'
|
| - An empty reply indicates that the request is not supported by
|
| - the stub.
|
| +* Overview::
|
| +* Packets::
|
| +* Stop Reply Packets::
|
| +* General Query Packets::
|
| +* Architecture-Specific Protocol Details::
|
| +* Tracepoint Packets::
|
| +* Host I/O Packets::
|
| +* Interrupts::
|
| +* Notification Packets::
|
| +* Remote Non-Stop::
|
| +* Packet Acknowledgment::
|
| +* Examples::
|
| +* File-I/O Remote Protocol Extension::
|
| +* Library List Format::
|
| +* Library List Format for SVR4 Targets::
|
| +* Memory Map Format::
|
| +* Thread List Format::
|
| +* Traceframe Info Format::
|
| +* Branch Trace Format::
|
|
|
| - ADDRESS is encoded in hex. ID and EXTRA are strings encoded in
|
| - hex.
|
| +
|
| +File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
|
|
|
| - In response to each query, the target will reply with a list of
|
| - one or more markers, separated by commas. GDB will respond to each
|
| - reply with a request for more markers (using the `qs' form of the
|
| - query), until the target responds with `l' (lower-case ell, for
|
| - "last").
|
| +E.1 Overview
|
| +============
|
|
|
| -`qTSTMat:ADDRESS'
|
| - This packets requests data about static tracepoint markers in the
|
| - target program at ADDRESS. Replies to this packet follow the
|
| - syntax of the `qTfSTM' and `qTsSTM' packets that list static
|
| - tracepoint markers.
|
| +There may be occasions when you need to know something about the
|
| +protocol--for example, if there is only one serial port to your target
|
| +machine, you might want your program to do something special if it
|
| +recognizes a packet meant for GDB.
|
|
|
| -`QTSave:FILENAME'
|
| - This packet directs the target to save trace data to the file name
|
| - FILENAME in the target's filesystem. FILENAME is encoded as a hex
|
| - string; the interpretation of the file name (relative vs absolute,
|
| - wild cards, etc) is up to the target.
|
| + In the examples below, `->' and `<-' are used to indicate
|
| +transmitted and received data, respectively.
|
|
|
| -`qTBuffer:OFFSET,LEN'
|
| - Return up to LEN bytes of the current contents of trace buffer,
|
| - starting at OFFSET. The trace buffer is treated as if it were a
|
| - contiguous collection of traceframes, as per the trace file format.
|
| - The reply consists as many hex-encoded bytes as the target can
|
| - deliver in a packet; it is not an error to return fewer than were
|
| - asked for. A reply consisting of just `l' indicates that no bytes
|
| - are available.
|
| + All GDB commands and responses (other than acknowledgments and
|
| +notifications, see *note Notification Packets::) are sent as a PACKET.
|
| +A PACKET is introduced with the character `$', the actual PACKET-DATA,
|
| +and the terminating character `#' followed by a two-digit CHECKSUM:
|
|
|
| -`QTBuffer:circular:VALUE'
|
| - This packet directs the target to use a circular trace buffer if
|
| - VALUE is 1, or a linear buffer if the value is 0.
|
| + `$'PACKET-DATA`#'CHECKSUM
|
| + The two-digit CHECKSUM is computed as the modulo 256 sum of all
|
| +characters between the leading `$' and the trailing `#' (an eight bit
|
| +unsigned checksum).
|
|
|
| -`QTNotes:[TYPE:TEXT][;TYPE:TEXT]...'
|
| - This packet adds optional textual notes to the trace run.
|
| - Allowable types include `user', `notes', and `tstop', the TEXT
|
| - fields are arbitrary strings, hex-encoded.
|
| + Implementors should note that prior to GDB 5.0 the protocol
|
| +specification also included an optional two-digit SEQUENCE-ID:
|
|
|
| + `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
|
|
|
| -E.6.1 Relocate instruction reply packet
|
| ----------------------------------------
|
| +That SEQUENCE-ID was appended to the acknowledgment. GDB has never
|
| +output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0
|
| +must not accept SEQUENCE-ID.
|
|
|
| -When installing fast tracepoints in memory, the target may need to
|
| -relocate the instruction currently at the tracepoint address to a
|
| -different address in memory. For most instructions, a simple copy is
|
| -enough, but, for example, call instructions that implicitly push the
|
| -return address on the stack, and relative branches or other PC-relative
|
| -instructions require offset adjustment, so that the effect of executing
|
| -the instruction at a different address is the same as if it had
|
| -executed in the original location.
|
| + When either the host or the target machine receives a packet, the
|
| +first response expected is an acknowledgment: either `+' (to indicate
|
| +the package was received correctly) or `-' (to request retransmission):
|
|
|
| - In response to several of the tracepoint packets, the target may also
|
| -respond with a number of intermediate `qRelocInsn' request packets
|
| -before the final result packet, to have GDB handle this relocation
|
| -operation. If a packet supports this mechanism, its documentation will
|
| -explicitly say so. See for example the above descriptions for the
|
| -`QTStart' and `QTDP' packets. The format of the request is:
|
| + -> `$'PACKET-DATA`#'CHECKSUM
|
| + <- `+'
|
| + The `+'/`-' acknowledgments can be disabled once a connection is
|
| +established. *Note Packet Acknowledgment::, for details.
|
|
|
| -`qRelocInsn:FROM;TO'
|
| - This requests GDB to copy instruction at address FROM to address
|
| - TO, possibly adjusted so that executing the instruction at TO has
|
| - the same effect as executing it at FROM. GDB writes the adjusted
|
| - instruction to target memory starting at TO.
|
| + The host (GDB) sends COMMANDs, and the target (the debugging stub
|
| +incorporated in your program) sends a RESPONSE. In the case of step
|
| +and continue COMMANDs, the response is only sent when the operation has
|
| +completed, and the target has again stopped all threads in all attached
|
| +processes. This is the default all-stop mode behavior, but the remote
|
| +protocol also supports GDB's non-stop execution mode; see *note Remote
|
| +Non-Stop::, for details.
|
|
|
| - Replies:
|
| -`qRelocInsn:ADJUSTED_SIZE'
|
| - Informs the stub the relocation is complete. ADJUSTED_SIZE is the
|
| - length in bytes of resulting relocated instruction sequence.
|
| + PACKET-DATA consists of a sequence of characters with the exception
|
| +of `#' and `$' (see `X' packet for additional exceptions).
|
|
|
| -`E NN'
|
| - A badly formed request was detected, or an error was encountered
|
| - while relocating the instruction.
|
| + Fields within the packet should be separated using `,' `;' or `:'.
|
| +Except where otherwise noted all numbers are represented in HEX with
|
| +leading zeros suppressed.
|
|
|
| -
|
| -File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
|
| + Implementors should note that prior to GDB 5.0, the character `:'
|
| +could not appear as the third character in a packet (as it would
|
| +potentially conflict with the SEQUENCE-ID).
|
|
|
| -E.7 Host I/O Packets
|
| -====================
|
| + Binary data in most packets is encoded either as two hexadecimal
|
| +digits per byte of binary data. This allowed the traditional remote
|
| +protocol to work over connections which were only seven-bit clean.
|
| +Some packets designed more recently assume an eight-bit clean
|
| +connection, and use a more efficient encoding to send and receive
|
| +binary data.
|
|
|
| -The "Host I/O" packets allow GDB to perform I/O operations on the far
|
| -side of a remote link. For example, Host I/O is used to upload and
|
| -download files to a remote target with its own filesystem. Host I/O
|
| -uses the same constant values and data structure layout as the
|
| -target-initiated File-I/O protocol. However, the Host I/O packets are
|
| -structured differently. The target-initiated protocol relies on target
|
| -memory to store parameters and buffers. Host I/O requests are
|
| -initiated by GDB, and the target's memory is not involved. *Note
|
| -File-I/O Remote Protocol Extension::, for more details on the
|
| -target-initiated protocol.
|
| + The binary data representation uses `7d' (ASCII `}') as an escape
|
| +character. Any escaped byte is transmitted as the escape character
|
| +followed by the original character XORed with `0x20'. For example, the
|
| +byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The
|
| +bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
|
| +must always be escaped. Responses sent by the stub must also escape
|
| +`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
|
| +run-length encoded sequence (described next).
|
| +
|
| + Response DATA can be run-length encoded to save space. Run-length
|
| +encoding replaces runs of identical characters with one instance of the
|
| +repeated character, followed by a `*' and a repeat count. The repeat
|
| +count is itself sent encoded, to avoid binary characters in DATA: a
|
| +value of N is sent as `N+29'. For a repeat count greater or equal to
|
| +3, this produces a printable ASCII character, e.g. a space (ASCII code
|
| +32) for a repeat count of 3. (This is because run-length encoding
|
| +starts to win for counts 3 or more.) Thus, for example, `0* ' is a
|
| +run-length encoding of "0000": the space character after `*' means
|
| +repeat the leading `0' `32 - 29 = 3' more times.
|
| +
|
| + The printable characters `#' and `$' or with a numeric value greater
|
| +than 126 must not be used. Runs of six repeats (`#') or seven repeats
|
| +(`$') can be expanded using a repeat count of only five (`"'). For
|
| +example, `00000000' can be encoded as `0*"00'.
|
| +
|
| + The error response returned for some packets includes a two character
|
| +error number. That number is not well defined.
|
| +
|
| + For any COMMAND not supported by the stub, an empty response
|
| +(`$#00') should be returned. That way it is possible to extend the
|
| +protocol. A newer GDB can tell if a packet is supported based on that
|
| +response.
|
| +
|
| + At a minimum, a stub is required to support the `g' and `G' commands
|
| +for register access, and the `m' and `M' commands for memory access.
|
| +Stubs that only control single-threaded targets can implement run
|
| +control with the `c' (continue), and `s' (step) commands. Stubs that
|
| +support multi-threading targets should support the `vCont' command.
|
| +All other commands are optional.
|
| +
|
| +
|
| +File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
|
| +
|
| +E.2 Packets
|
| +===========
|
| +
|
| +The following table provides a complete list of all currently defined
|
| +COMMANDs and their corresponding response DATA. *Note File-I/O Remote
|
| +Protocol Extension::, for details about the File I/O extension of the
|
| +remote protocol.
|
| +
|
| + Each packet's description has a template showing the packet's overall
|
| +syntax, followed by an explanation of the packet's meaning. We include
|
| +spaces in some of the templates for clarity; these are not part of the
|
| +packet's syntax. No GDB packet uses spaces to separate its components.
|
| +For example, a template like `foo BAR BAZ' describes a packet beginning
|
| +with the three ASCII bytes `foo', followed by a BAR, followed directly
|
| +by a BAZ. GDB does not transmit a space character between the `foo'
|
| +and the BAR, or between the BAR and the BAZ.
|
| +
|
| + Several packets and replies include a THREAD-ID field to identify a
|
| +thread. Normally these are positive numbers with a target-specific
|
| +interpretation, formatted as big-endian hex strings. A THREAD-ID can
|
| +also be a literal `-1' to indicate all threads, or `0' to pick any
|
| +thread.
|
| +
|
| + In addition, the remote protocol supports a multiprocess feature in
|
| +which the THREAD-ID syntax is extended to optionally include both
|
| +process and thread ID fields, as `pPID.TID'. The PID (process) and TID
|
| +(thread) components each have the format described above: a positive
|
| +number with target-specific interpretation formatted as a big-endian
|
| +hex string, literal `-1' to indicate all processes or threads
|
| +(respectively), or `0' to indicate an arbitrary process or thread.
|
| +Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It
|
| +is an error to specify all processes but a specific thread, such as
|
| +`p-1.TID'. Note that the `p' prefix is _not_ used for those packets
|
| +and replies explicitly documented to include a process ID, rather than
|
| +a THREAD-ID.
|
| +
|
| + The multiprocess THREAD-ID syntax extensions are only used if both
|
| +GDB and the stub report support for the `multiprocess' feature using
|
| +`qSupported'. *Note multiprocess extensions::, for more information.
|
| +
|
| + Note that all packet forms beginning with an upper- or lower-case
|
| +letter, other than those described here, are reserved for future use.
|
| +
|
| + Here are the packet descriptions.
|
| +
|
| +`!'
|
| + Enable extended mode. In extended mode, the remote server is made
|
| + persistent. The `R' packet is used to restart the program being
|
| + debugged.
|
| +
|
| + Reply:
|
| + `OK'
|
| + The remote target both supports and has enabled extended mode.
|
| +
|
| +`?'
|
| + Indicate the reason the target halted. The reply is the same as
|
| + for step and continue. This packet has a special interpretation
|
| + when the target is in non-stop mode; see *note Remote Non-Stop::.
|
| +
|
| + Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +
|
| +`A ARGLEN,ARGNUM,ARG,...'
|
| + Initialized `argv[]' array passed into program. ARGLEN specifies
|
| + the number of bytes in the hex encoded byte stream ARG. See
|
| + `gdbserver' for more details.
|
| +
|
| + Reply:
|
| + `OK'
|
| + The arguments were set.
|
| +
|
| + `E NN'
|
| + An error occurred.
|
| +
|
| +`b BAUD'
|
| + (Don't use this packet; its behavior is not well-defined.) Change
|
| + the serial line speed to BAUD.
|
| +
|
| + JTC: _When does the transport layer state change? When it's
|
| + received, or after the ACK is transmitted. In either case, there
|
| + are problems if the command or the acknowledgment packet is
|
| + dropped._
|
| +
|
| + Stan: _If people really wanted to add something like this, and get
|
| + it working for the first time, they ought to modify ser-unix.c to
|
| + send some kind of out-of-band message to a specially-setup stub
|
| + and have the switch happen "in between" packets, so that from
|
| + remote protocol's point of view, nothing actually happened._
|
| +
|
| +`B ADDR,MODE'
|
| + Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
|
| +
|
| + Don't use this packet. Use the `Z' and `z' packets instead (*note
|
| + insert breakpoint or watchpoint packet::).
|
| +
|
| +`bc'
|
| + Backward continue. Execute the target system in reverse. No
|
| + parameter. *Note Reverse Execution::, for more information.
|
| +
|
| + Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +
|
| +`bs'
|
| + Backward single step. Execute one instruction in reverse. No
|
| + parameter. *Note Reverse Execution::, for more information.
|
| +
|
| + Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +
|
| +`c [ADDR]'
|
| + Continue. ADDR is address to resume. If ADDR is omitted, resume
|
| + at current address.
|
| +
|
| + This packet is deprecated for multi-threading support. *Note
|
| + vCont packet::.
|
| +
|
| + Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +
|
| +`C SIG[;ADDR]'
|
| + Continue with signal SIG (hex signal number). If `;ADDR' is
|
| + omitted, resume at same address.
|
| +
|
| + This packet is deprecated for multi-threading support. *Note
|
| + vCont packet::.
|
| +
|
| + Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +
|
| +`d'
|
| + Toggle debug flag.
|
| +
|
| + Don't use this packet; instead, define a general set packet (*note
|
| + General Query Packets::).
|
| +
|
| +`D'
|
| +`D;PID'
|
| + The first form of the packet is used to detach GDB from the remote
|
| + system. It is sent to the remote target before GDB disconnects
|
| + via the `detach' command.
|
| +
|
| + The second form, including a process ID, is used when multiprocess
|
| + protocol extensions are enabled (*note multiprocess extensions::),
|
| + to detach only a specific process. The PID is specified as a
|
| + big-endian hex string.
|
| +
|
| + Reply:
|
| + `OK'
|
| + for success
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`F RC,EE,CF;XX'
|
| + A reply from GDB to an `F' packet sent by the target. This is
|
| + part of the File-I/O protocol extension. *Note File-I/O Remote
|
| + Protocol Extension::, for the specification.
|
| +
|
| +`g'
|
| + Read general registers.
|
| +
|
| + Reply:
|
| + `XX...'
|
| + Each byte of register data is described by two hex digits.
|
| + The bytes with the register are transmitted in target byte
|
| + order. The size of each register and their position within
|
| + the `g' packet are determined by the GDB internal gdbarch
|
| + functions `DEPRECATED_REGISTER_RAW_SIZE' and
|
| + `gdbarch_register_name'. The specification of several
|
| + standard `g' packets is specified below.
|
| +
|
| + When reading registers from a trace frame (*note Using the
|
| + Collected Data: Analyze Collected Data.), the stub may also
|
| + return a string of literal `x''s in place of the register
|
| + data digits, to indicate that the corresponding register has
|
| + not been collected, thus its value is unavailable. For
|
| + example, for an architecture with 4 registers of 4 bytes
|
| + each, the following reply indicates to GDB that registers 0
|
| + and 2 have not been collected, while registers 1 and 3 have
|
| + been collected, and both have zero value:
|
| +
|
| + -> `g'
|
| + <- `xxxxxxxx00000000xxxxxxxx00000000'
|
| +
|
| + `E NN'
|
| + for an error.
|
| +
|
| +`G XX...'
|
| + Write general registers. *Note read registers packet::, for a
|
| + description of the XX... data.
|
| +
|
| + Reply:
|
| + `OK'
|
| + for success
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`H OP THREAD-ID'
|
| + Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
|
| + OP depends on the operation to be performed: it should be `c' for
|
| + step and continue operations (note that this is deprecated,
|
| + supporting the `vCont' command is a better option), `g' for other
|
| + operations. The thread designator THREAD-ID has the format and
|
| + interpretation described in *note thread-id syntax::.
|
| +
|
| + Reply:
|
| + `OK'
|
| + for success
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`i [ADDR[,NNN]]'
|
| + Step the remote target by a single clock cycle. If `,NNN' is
|
| + present, cycle step NNN cycles. If ADDR is present, cycle step
|
| + starting at that address.
|
| +
|
| +`I'
|
| + Signal, then cycle step. *Note step with signal packet::. *Note
|
| + cycle step packet::.
|
| +
|
| +`k'
|
| + Kill request.
|
| +
|
| + FIXME: _There is no description of how to operate when a specific
|
| + thread context has been selected (i.e. does 'k' kill only that
|
| + thread?)_.
|
| +
|
| +`m ADDR,LENGTH'
|
| + Read LENGTH bytes of memory starting at address ADDR. Note that
|
| + ADDR may not be aligned to any particular boundary.
|
| +
|
| + The stub need not use any particular size or alignment when
|
| + gathering data from memory for the response; even if ADDR is
|
| + word-aligned and LENGTH is a multiple of the word size, the stub
|
| + is free to use byte accesses, or not. For this reason, this
|
| + packet may not be suitable for accessing memory-mapped I/O devices.
|
| +
|
| + Reply:
|
| + `XX...'
|
| + Memory contents; each byte is transmitted as a two-digit
|
| + hexadecimal number. The reply may contain fewer bytes than
|
| + requested if the server was able to read only part of the
|
| + region of memory.
|
| +
|
| + `E NN'
|
| + NN is errno
|
| +
|
| +`M ADDR,LENGTH:XX...'
|
| + Write LENGTH bytes of memory starting at address ADDR. XX... is
|
| + the data; each byte is transmitted as a two-digit hexadecimal
|
| + number.
|
| +
|
| + Reply:
|
| + `OK'
|
| + for success
|
| +
|
| + `E NN'
|
| + for an error (this includes the case where only part of the
|
| + data was written).
|
| +
|
| +`p N'
|
| + Read the value of register N; N is in hex. *Note read registers
|
| + packet::, for a description of how the returned register value is
|
| + encoded.
|
| +
|
| + Reply:
|
| + `XX...'
|
| + the register's value
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| + `'
|
| + Indicating an unrecognized QUERY.
|
| +
|
| +`P N...=R...'
|
| + Write register N... with value R.... The register number N is in
|
| + hexadecimal, and R... contains two hex digits for each byte in the
|
| + register (target byte order).
|
| +
|
| + Reply:
|
| + `OK'
|
| + for success
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`q NAME PARAMS...'
|
| +`Q NAME PARAMS...'
|
| + General query (`q') and set (`Q'). These packets are described
|
| + fully in *note General Query Packets::.
|
| +
|
| +`r'
|
| + Reset the entire system.
|
| +
|
| + Don't use this packet; use the `R' packet instead.
|
| +
|
| +`R XX'
|
| + Restart the program being debugged. XX, while needed, is ignored.
|
| + This packet is only available in extended mode (*note extended
|
| + mode::).
|
| +
|
| + The `R' packet has no reply.
|
| +
|
| +`s [ADDR]'
|
| + Single step. ADDR is the address at which to resume. If ADDR is
|
| + omitted, resume at same address.
|
| +
|
| + This packet is deprecated for multi-threading support. *Note
|
| + vCont packet::.
|
| +
|
| + Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +
|
| +`S SIG[;ADDR]'
|
| + Step with signal. This is analogous to the `C' packet, but
|
| + requests a single-step, rather than a normal resumption of
|
| + execution.
|
| +
|
| + This packet is deprecated for multi-threading support. *Note
|
| + vCont packet::.
|
| +
|
| + Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +
|
| +`t ADDR:PP,MM'
|
| + Search backwards starting at address ADDR for a match with pattern
|
| + PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3
|
| + digits.
|
| +
|
| +`T THREAD-ID'
|
| + Find out if the thread THREAD-ID is alive. *Note thread-id
|
| + syntax::.
|
| +
|
| + Reply:
|
| + `OK'
|
| + thread is still alive
|
| +
|
| + `E NN'
|
| + thread is dead
|
| +
|
| +`v'
|
| + Packets starting with `v' are identified by a multi-letter name,
|
| + up to the first `;' or `?' (or the end of the packet).
|
| +
|
| +`vAttach;PID'
|
| + Attach to a new process with the specified process ID PID. The
|
| + process ID is a hexadecimal integer identifying the process. In
|
| + all-stop mode, all threads in the attached process are stopped; in
|
| + non-stop mode, it may be attached without being stopped if that is
|
| + supported by the target.
|
| +
|
| + This packet is only available in extended mode (*note extended
|
| + mode::).
|
| +
|
| + Reply:
|
| + `E NN'
|
| + for an error
|
| +
|
| + `Any stop packet'
|
| + for success in all-stop mode (*note Stop Reply Packets::)
|
| +
|
| + `OK'
|
| + for success in non-stop mode (*note Remote Non-Stop::)
|
| +
|
| +`vCont[;ACTION[:THREAD-ID]]...'
|
| + Resume the inferior, specifying different actions for each thread.
|
| + If an action is specified with no THREAD-ID, then it is applied to
|
| + any threads that don't have a specific action specified; if no
|
| + default action is specified then other threads should remain
|
| + stopped in all-stop mode and in their current state in non-stop
|
| + mode. Specifying multiple default actions is an error; specifying
|
| + no actions is also an error. Thread IDs are specified using the
|
| + syntax described in *note thread-id syntax::.
|
| +
|
| + Currently supported actions are:
|
| +
|
| + `c'
|
| + Continue.
|
| +
|
| + `C SIG'
|
| + Continue with signal SIG. The signal SIG should be two hex
|
| + digits.
|
| +
|
| + `s'
|
| + Step.
|
| +
|
| + `S SIG'
|
| + Step with signal SIG. The signal SIG should be two hex
|
| + digits.
|
| +
|
| + `t'
|
| + Stop.
|
| +
|
| + `r START,END'
|
| + Step once, and then keep stepping as long as the thread stops
|
| + at addresses between START (inclusive) and END (exclusive).
|
| + The remote stub reports a stop reply when either the thread
|
| + goes out of the range or is stopped due to an unrelated
|
| + reason, such as hitting a breakpoint. *Note range stepping::.
|
| +
|
| + If the range is empty (START == END), then the action becomes
|
| + equivalent to the `s' action. In other words, single-step
|
| + once, and report the stop (even if the stepped instruction
|
| + jumps to START).
|
| +
|
| + (A stop reply may be sent at any point even if the PC is
|
| + still within the stepping range; for example, it is valid to
|
| + implement this packet in a degenerate way as a single
|
| + instruction step operation.)
|
| +
|
| +
|
| + The optional argument ADDR normally associated with the `c', `C',
|
| + `s', and `S' packets is not supported in `vCont'.
|
| +
|
| + The `t' action is only relevant in non-stop mode (*note Remote
|
| + Non-Stop::) and may be ignored by the stub otherwise. A stop
|
| + reply should be generated for any affected thread not already
|
| + stopped. When a thread is stopped by means of a `t' action, the
|
| + corresponding stop reply should indicate that the thread has
|
| + stopped with signal `0', regardless of whether the target uses
|
| + some other signal as an implementation detail.
|
| +
|
| + The stub must support `vCont' if it reports support for
|
| + multiprocess extensions (*note multiprocess extensions::). Note
|
| + that in this case `vCont' actions can be specified to apply to all
|
| + threads in a process by using the `pPID.-1' form of the THREAD-ID.
|
| +
|
| + Reply: *Note Stop Reply Packets::, for the reply specifications.
|
| +
|
| +`vCont?'
|
| + Request a list of actions supported by the `vCont' packet.
|
| +
|
| + Reply:
|
| + `vCont[;ACTION...]'
|
| + The `vCont' packet is supported. Each ACTION is a supported
|
| + command in the `vCont' packet.
|
| +
|
| + `'
|
| + The `vCont' packet is not supported.
|
| +
|
| +`vFile:OPERATION:PARAMETER...'
|
| + Perform a file operation on the target system. For details, see
|
| + *note Host I/O Packets::.
|
| +
|
| +`vFlashErase:ADDR,LENGTH'
|
| + Direct the stub to erase LENGTH bytes of flash starting at ADDR.
|
| + The region may enclose any number of flash blocks, but its start
|
| + and end must fall on block boundaries, as indicated by the flash
|
| + block size appearing in the memory map (*note Memory Map
|
| + Format::). GDB groups flash memory programming operations
|
| + together, and sends a `vFlashDone' request after each group; the
|
| + stub is allowed to delay erase operation until the `vFlashDone'
|
| + packet is received.
|
| +
|
| + Reply:
|
| + `OK'
|
| + for success
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`vFlashWrite:ADDR:XX...'
|
| + Direct the stub to write data to flash address ADDR. The data is
|
| + passed in binary form using the same encoding as for the `X'
|
| + packet (*note Binary Data::). The memory ranges specified by
|
| + `vFlashWrite' packets preceding a `vFlashDone' packet must not
|
| + overlap, and must appear in order of increasing addresses
|
| + (although `vFlashErase' packets for higher addresses may already
|
| + have been received; the ordering is guaranteed only between
|
| + `vFlashWrite' packets). If a packet writes to an address that was
|
| + neither erased by a preceding `vFlashErase' packet nor by some
|
| + other target-specific method, the results are unpredictable.
|
| +
|
| + Reply:
|
| + `OK'
|
| + for success
|
| +
|
| + `E.memtype'
|
| + for vFlashWrite addressing non-flash memory
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`vFlashDone'
|
| + Indicate to the stub that flash programming operation is finished.
|
| + The stub is permitted to delay or batch the effects of a group of
|
| + `vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
|
| + packet is received. The contents of the affected regions of flash
|
| + memory are unpredictable until the `vFlashDone' request is
|
| + completed.
|
| +
|
| +`vKill;PID'
|
| + Kill the process with the specified process ID. PID is a
|
| + hexadecimal integer identifying the process. This packet is used
|
| + in preference to `k' when multiprocess protocol extensions are
|
| + supported; see *note multiprocess extensions::.
|
| +
|
| + Reply:
|
| + `E NN'
|
| + for an error
|
| +
|
| + `OK'
|
| + for success
|
| +
|
| +`vRun;FILENAME[;ARGUMENT]...'
|
| + Run the program FILENAME, passing it each ARGUMENT on its command
|
| + line. The file and arguments are hex-encoded strings. If
|
| + FILENAME is an empty string, the stub may use a default program
|
| + (e.g. the last program run). The program is created in the stopped
|
| + state.
|
| +
|
| + This packet is only available in extended mode (*note extended
|
| + mode::).
|
| +
|
| + Reply:
|
| + `E NN'
|
| + for an error
|
| +
|
| + `Any stop packet'
|
| + for success (*note Stop Reply Packets::)
|
| +
|
| +`vStopped'
|
| + *Note Notification Packets::.
|
| +
|
| +`X ADDR,LENGTH:XX...'
|
| + Write data to memory, where the data is transmitted in binary.
|
| + ADDR is address, LENGTH is number of bytes, `XX...' is binary data
|
| + (*note Binary Data::).
|
| +
|
| + Reply:
|
| + `OK'
|
| + for success
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`z TYPE,ADDR,KIND'
|
| +`Z TYPE,ADDR,KIND'
|
| + Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
|
| + starting at address ADDRESS of kind KIND.
|
| +
|
| + Each breakpoint and watchpoint packet TYPE is documented
|
| + separately.
|
| +
|
| + _Implementation notes: A remote target shall return an empty string
|
| + for an unrecognized breakpoint or watchpoint packet TYPE. A
|
| + remote target shall support either both or neither of a given
|
| + `ZTYPE...' and `zTYPE...' packet pair. To avoid potential
|
| + problems with duplicate packets, the operations should be
|
| + implemented in an idempotent way._
|
| +
|
| +`z0,ADDR,KIND'
|
| +`Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'
|
| + Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
|
| + of type KIND.
|
| +
|
| + A memory breakpoint is implemented by replacing the instruction at
|
| + ADDR with a software breakpoint or trap instruction. The KIND is
|
| + target-specific and typically indicates the size of the breakpoint
|
| + in bytes that should be inserted. E.g., the ARM and MIPS can
|
| + insert either a 2 or 4 byte breakpoint. Some architectures have
|
| + additional meanings for KIND; COND_LIST is an optional list of
|
| + conditional expressions in bytecode form that should be evaluated
|
| + on the target's side. These are the conditions that should be
|
| + taken into consideration when deciding if the breakpoint trigger
|
| + should be reported back to GDBN.
|
| +
|
| + The COND_LIST parameter is comprised of a series of expressions,
|
| + concatenated without separators. Each expression has the following
|
| + form:
|
| +
|
| + `X LEN,EXPR'
|
| + LEN is the length of the bytecode expression and EXPR is the
|
| + actual conditional expression in bytecode form.
|
| +
|
| +
|
| + The optional CMD_LIST parameter introduces commands that may be
|
| + run on the target, rather than being reported back to GDB. The
|
| + parameter starts with a numeric flag PERSIST; if the flag is
|
| + nonzero, then the breakpoint may remain active and the commands
|
| + continue to be run even when GDB disconnects from the target.
|
| + Following this flag is a series of expressions concatenated with no
|
| + separators. Each expression has the following form:
|
| +
|
| + `X LEN,EXPR'
|
| + LEN is the length of the bytecode expression and EXPR is the
|
| + actual conditional expression in bytecode form.
|
| +
|
| +
|
| + see *note Architecture-Specific Protocol Details::.
|
| +
|
| + _Implementation note: It is possible for a target to copy or move
|
| + code that contains memory breakpoints (e.g., when implementing
|
| + overlays). The behavior of this packet, in the presence of such a
|
| + target, is not defined._
|
| +
|
| + Reply:
|
| + `OK'
|
| + success
|
| +
|
| + `'
|
| + not supported
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`z1,ADDR,KIND'
|
| +`Z1,ADDR,KIND[;COND_LIST...]'
|
| + Insert (`Z1') or remove (`z1') a hardware breakpoint at address
|
| + ADDR.
|
| +
|
| + A hardware breakpoint is implemented using a mechanism that is not
|
| + dependant on being able to modify the target's memory. KIND and
|
| + COND_LIST have the same meaning as in `Z0' packets.
|
| +
|
| + _Implementation note: A hardware breakpoint is not affected by code
|
| + movement._
|
| +
|
| + Reply:
|
| + `OK'
|
| + success
|
| +
|
| + `'
|
| + not supported
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`z2,ADDR,KIND'
|
| +`Z2,ADDR,KIND'
|
| + Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND
|
| + is interpreted as the number of bytes to watch.
|
| +
|
| + Reply:
|
| + `OK'
|
| + success
|
| +
|
| + `'
|
| + not supported
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`z3,ADDR,KIND'
|
| +`Z3,ADDR,KIND'
|
| + Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is
|
| + interpreted as the number of bytes to watch.
|
| +
|
| + Reply:
|
| + `OK'
|
| + success
|
| +
|
| + `'
|
| + not supported
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +`z4,ADDR,KIND'
|
| +`Z4,ADDR,KIND'
|
| + Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND
|
| + is interpreted as the number of bytes to watch.
|
| +
|
| + Reply:
|
| + `OK'
|
| + success
|
| +
|
| + `'
|
| + not supported
|
| +
|
| + `E NN'
|
| + for an error
|
| +
|
| +
|
| +
|
| +File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
|
| +
|
| +E.3 Stop Reply Packets
|
| +======================
|
| +
|
| +The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?'
|
| +packets can receive any of the below as a reply. Except for `?' and
|
| +`vStopped', that reply is only returned when the target halts. In the
|
| +below the exact meaning of "signal number" is defined by the header
|
| +`include/gdb/signals.h' in the GDB source code.
|
| +
|
| + As in the description of request packets, we include spaces in the
|
| +reply templates for clarity; these are not part of the reply packet's
|
| +syntax. No GDB stop reply packet uses spaces to separate its
|
| +components.
|
| +
|
| +`S AA'
|
| + The program received signal number AA (a two-digit hexadecimal
|
| + number). This is equivalent to a `T' response with no N:R pairs.
|
| +
|
| +`T AA N1:R1;N2:R2;...'
|
| + The program received signal number AA (a two-digit hexadecimal
|
| + number). This is equivalent to an `S' response, except that the
|
| + `N:R' pairs can carry values of important registers and other
|
| + information directly in the stop reply packet, reducing round-trip
|
| + latency. Single-step and breakpoint traps are reported this way.
|
| + Each `N:R' pair is interpreted as follows:
|
| +
|
| + * If N is a hexadecimal number, it is a register number, and the
|
| + corresponding R gives that register's value. R is a series
|
| + of bytes in target byte order, with each byte given by a
|
| + two-digit hex number.
|
| +
|
| + * If N is `thread', then R is the THREAD-ID of the stopped
|
| + thread, as specified in *note thread-id syntax::.
|
| +
|
| + * If N is `core', then R is the hexadecimal number of the core
|
| + on which the stop event was detected.
|
| +
|
| + * If N is a recognized "stop reason", it describes a more
|
| + specific event that stopped the target. The currently
|
| + defined stop reasons are listed below. AA should be `05',
|
| + the trap signal. At most one stop reason should be present.
|
| +
|
| + * Otherwise, GDB should ignore this `N:R' pair and go on to the
|
| + next; this allows us to extend the protocol in the future.
|
| +
|
| + The currently defined stop reasons are:
|
| +
|
| + `watch'
|
| + `rwatch'
|
| + `awatch'
|
| + The packet indicates a watchpoint hit, and R is the data
|
| + address, in hex.
|
| +
|
| + `library'
|
| + The packet indicates that the loaded libraries have changed.
|
| + GDB should use `qXfer:libraries:read' to fetch a new list of
|
| + loaded libraries. R is ignored.
|
| +
|
| + `replaylog'
|
| + The packet indicates that the target cannot continue replaying
|
| + logged execution events, because it has reached the end (or
|
| + the beginning when executing backward) of the log. The value
|
| + of R will be either `begin' or `end'. *Note Reverse
|
| + Execution::, for more information.
|
| +
|
| +`W AA'
|
| +`W AA ; process:PID'
|
| + The process exited, and AA is the exit status. This is only
|
| + applicable to certain targets.
|
| +
|
| + The second form of the response, including the process ID of the
|
| + exited process, can be used only when GDB has reported support for
|
| + multiprocess protocol extensions; see *note multiprocess
|
| + extensions::. The PID is formatted as a big-endian hex string.
|
| +
|
| +`X AA'
|
| +`X AA ; process:PID'
|
| + The process terminated with signal AA.
|
| +
|
| + The second form of the response, including the process ID of the
|
| + terminated process, can be used only when GDB has reported support
|
| + for multiprocess protocol extensions; see *note multiprocess
|
| + extensions::. The PID is formatted as a big-endian hex string.
|
| +
|
| +`O XX...'
|
| + `XX...' is hex encoding of ASCII data, to be written as the
|
| + program's console output. This can happen at any time while the
|
| + program is running and the debugger should continue to wait for
|
| + `W', `T', etc. This reply is not permitted in non-stop mode.
|
| +
|
| +`F CALL-ID,PARAMETER...'
|
| + CALL-ID is the identifier which says which host system call should
|
| + be called. This is just the name of the function. Translation
|
| + into the correct system call is only applicable as it's defined in
|
| + GDB. *Note File-I/O Remote Protocol Extension::, for a list of
|
| + implemented system calls.
|
| +
|
| + `PARAMETER...' is a list of parameters as defined for this very
|
| + system call.
|
| +
|
| + The target replies with this packet when it expects GDB to call a
|
| + host system call on behalf of the target. GDB replies with an
|
| + appropriate `F' packet and keeps up waiting for the next reply
|
| + packet from the target. The latest `C', `c', `S' or `s' action is
|
| + expected to be continued. *Note File-I/O Remote Protocol
|
| + Extension::, for more details.
|
| +
|
| +
|
| +
|
| +File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol
|
| +
|
| +E.4 General Query Packets
|
| +=========================
|
| +
|
| +Packets starting with `q' are "general query packets"; packets starting
|
| +with `Q' are "general set packets". General query and set packets are
|
| +a semi-unified form for retrieving and sending information to and from
|
| +the stub.
|
| +
|
| + The initial letter of a query or set packet is followed by a name
|
| +indicating what sort of thing the packet applies to. For example, GDB
|
| +may use a `qSymbol' packet to exchange symbol definitions with the
|
| +stub. These packet names follow some conventions:
|
| +
|
| + * The name must not contain commas, colons or semicolons.
|
| +
|
| + * Most GDB query and set packets have a leading upper case letter.
|
| +
|
| + * The names of custom vendor packets should use a company prefix, in
|
| + lower case, followed by a period. For example, packets designed at
|
| + the Acme Corporation might begin with `qacme.foo' (for querying
|
| + foos) or `Qacme.bar' (for setting bars).
|
| +
|
| + The name of a query or set packet should be separated from any
|
| +parameters by a `:'; the parameters themselves should be separated by
|
| +`,' or `;'. Stubs must be careful to match the full packet name, and
|
| +check for a separator or the end of the packet, in case two packet
|
| +names share a common prefix. New packets should not begin with `qC',
|
| +`qP', or `qL'(1).
|
| +
|
| + Like the descriptions of the other packets, each description here
|
| +has a template showing the packet's overall syntax, followed by an
|
| +explanation of the packet's meaning. We include spaces in some of the
|
| +templates for clarity; these are not part of the packet's syntax. No
|
| +GDB packet uses spaces to separate its components.
|
| +
|
| + Here are the currently defined query and set packets:
|
| +
|
| +`QAgent:1'
|
| +`QAgent:0'
|
| + Turn on or off the agent as a helper to perform some debugging
|
| + operations delegated from GDB (*note Control Agent::).
|
| +
|
| +`QAllow:OP:VAL...'
|
| + Specify which operations GDB expects to request of the target, as
|
| + a semicolon-separated list of operation name and value pairs.
|
| + Possible values for OP include `WriteReg', `WriteMem',
|
| + `InsertBreak', `InsertTrace', `InsertFastTrace', and `Stop'. VAL
|
| + is either 0, indicating that GDB will not request the operation,
|
| + or 1, indicating that it may. (The target can then use this to
|
| + set up its own internals optimally, for instance if the debugger
|
| + never expects to insert breakpoints, it may not need to install
|
| + its own trap handler.)
|
| +
|
| +`qC'
|
| + Return the current thread ID.
|
| +
|
| + Reply:
|
| + `QC THREAD-ID'
|
| + Where THREAD-ID is a thread ID as documented in *note
|
| + thread-id syntax::.
|
| +
|
| + `(anything else)'
|
| + Any other reply implies the old thread ID.
|
| +
|
| +`qCRC:ADDR,LENGTH'
|
| + Compute the CRC checksum of a block of memory using CRC-32 defined
|
| + in IEEE 802.3. The CRC is computed byte at a time, taking the most
|
| + significant bit of each byte first. The initial pattern code
|
| + `0xffffffff' is used to ensure leading zeros affect the CRC.
|
| +
|
| + _Note:_ This is the same CRC used in validating separate debug
|
| + files (*note Debugging Information in Separate Files: Separate
|
| + Debug Files.). However the algorithm is slightly different. When
|
| + validating separate debug files, the CRC is computed taking the
|
| + _least_ significant bit of each byte first, and the final result
|
| + is inverted to detect trailing zeros.
|
| +
|
| + Reply:
|
| + `E NN'
|
| + An error (such as memory fault)
|
| +
|
| + `C CRC32'
|
| + The specified memory region's checksum is CRC32.
|
| +
|
| +`QDisableRandomization:VALUE'
|
| + Some target operating systems will randomize the virtual address
|
| + space of the inferior process as a security feature, but provide a
|
| + feature to disable such randomization, e.g. to allow for a more
|
| + deterministic debugging experience. On such systems, this packet
|
| + with a VALUE of 1 directs the target to disable address space
|
| + randomization for processes subsequently started via `vRun'
|
| + packets, while a packet with a VALUE of 0 tells the target to
|
| + enable address space randomization.
|
| +
|
| + This packet is only available in extended mode (*note extended
|
| + mode::).
|
| +
|
| + Reply:
|
| + `OK'
|
| + The request succeeded.
|
| +
|
| + `E NN'
|
| + An error occurred. NN are hex digits.
|
| +
|
| + `'
|
| + An empty reply indicates that `QDisableRandomization' is not
|
| + supported by the stub.
|
| +
|
| + This packet is not probed by default; the remote stub must request
|
| + it, by supplying an appropriate `qSupported' response (*note
|
| + qSupported::). This should only be done on targets that actually
|
| + support disabling address space randomization.
|
| +
|
| +`qfThreadInfo'
|
| +`qsThreadInfo'
|
| + Obtain a list of all active thread IDs from the target (OS).
|
| + Since there may be too many active threads to fit into one reply
|
| + packet, this query works iteratively: it may require more than one
|
| + query/reply sequence to obtain the entire list of threads. The
|
| + first query of the sequence will be the `qfThreadInfo' query;
|
| + subsequent queries in the sequence will be the `qsThreadInfo'
|
| + query.
|
| +
|
| + NOTE: This packet replaces the `qL' query (see below).
|
| +
|
| + Reply:
|
| + `m THREAD-ID'
|
| + A single thread ID
|
| +
|
| + `m THREAD-ID,THREAD-ID...'
|
| + a comma-separated list of thread IDs
|
| +
|
| + `l'
|
| + (lower case letter `L') denotes end of list.
|
| +
|
| + In response to each query, the target will reply with a list of
|
| + one or more thread IDs, separated by commas. GDB will respond to
|
| + each reply with a request for more thread ids (using the `qs' form
|
| + of the query), until the target responds with `l' (lower-case ell,
|
| + for "last"). Refer to *note thread-id syntax::, for the format of
|
| + the THREAD-ID fields.
|
| +
|
| +`qGetTLSAddr:THREAD-ID,OFFSET,LM'
|
| + Fetch the address associated with thread local storage specified
|
| + by THREAD-ID, OFFSET, and LM.
|
| +
|
| + THREAD-ID is the thread ID associated with the thread for which to
|
| + fetch the TLS address. *Note thread-id syntax::.
|
| +
|
| + OFFSET is the (big endian, hex encoded) offset associated with the
|
| + thread local variable. (This offset is obtained from the debug
|
| + information associated with the variable.)
|
| +
|
| + LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
|
| + load module associated with the thread local storage. For example,
|
| + a GNU/Linux system will pass the link map address of the shared
|
| + object associated with the thread local storage under
|
| + consideration. Other operating environments may choose to
|
| + represent the load module differently, so the precise meaning of
|
| + this parameter will vary.
|
| +
|
| + Reply:
|
| + `XX...'
|
| + Hex encoded (big endian) bytes representing the address of
|
| + the thread local storage requested.
|
| +
|
| + `E NN'
|
| + An error occurred. NN are hex digits.
|
| +
|
| + `'
|
| + An empty reply indicates that `qGetTLSAddr' is not supported
|
| + by the stub.
|
| +
|
| +`qGetTIBAddr:THREAD-ID'
|
| + Fetch address of the Windows OS specific Thread Information Block.
|
| +
|
| + THREAD-ID is the thread ID associated with the thread.
|
| +
|
| + Reply:
|
| + `XX...'
|
| + Hex encoded (big endian) bytes representing the linear
|
| + address of the thread information block.
|
| +
|
| + `E NN'
|
| + An error occured. This means that either the thread was not
|
| + found, or the address could not be retrieved.
|
| +
|
| + `'
|
| + An empty reply indicates that `qGetTIBAddr' is not supported
|
| + by the stub.
|
| +
|
| +`qL STARTFLAG THREADCOUNT NEXTTHREAD'
|
| + Obtain thread information from RTOS. Where: STARTFLAG (one hex
|
| + digit) is one to indicate the first query and zero to indicate a
|
| + subsequent query; THREADCOUNT (two hex digits) is the maximum
|
| + number of threads the response packet can contain; and NEXTTHREAD
|
| + (eight hex digits), for subsequent queries (STARTFLAG is zero), is
|
| + returned in the response as ARGTHREAD.
|
| +
|
| + Don't use this packet; use the `qfThreadInfo' query instead (see
|
| + above).
|
| +
|
| + Reply:
|
| + `qM COUNT DONE ARGTHREAD THREAD...'
|
| + Where: COUNT (two hex digits) is the number of threads being
|
| + returned; DONE (one hex digit) is zero to indicate more
|
| + threads and one indicates no further threads; ARGTHREADID
|
| + (eight hex digits) is NEXTTHREAD from the request packet;
|
| + THREAD... is a sequence of thread IDs from the target.
|
| + THREADID (eight hex digits). See
|
| + `remote.c:parse_threadlist_response()'.
|
| +
|
| +`qOffsets'
|
| + Get section offsets that the target used when relocating the
|
| + downloaded image.
|
| +
|
| + Reply:
|
| + `Text=XXX;Data=YYY[;Bss=ZZZ]'
|
| + Relocate the `Text' section by XXX from its original address.
|
| + Relocate the `Data' section by YYY from its original address.
|
| + If the object file format provides segment information (e.g.
|
| + ELF `PT_LOAD' program headers), GDB will relocate entire
|
| + segments by the supplied offsets.
|
| +
|
| + _Note: while a `Bss' offset may be included in the response,
|
| + GDB ignores this and instead applies the `Data' offset to the
|
| + `Bss' section._
|
| +
|
| + `TextSeg=XXX[;DataSeg=YYY]'
|
| + Relocate the first segment of the object file, which
|
| + conventionally contains program code, to a starting address
|
| + of XXX. If `DataSeg' is specified, relocate the second
|
| + segment, which conventionally contains modifiable data, to a
|
| + starting address of YYY. GDB will report an error if the
|
| + object file does not contain segment information, or does not
|
| + contain at least as many segments as mentioned in the reply.
|
| + Extra segments are kept at fixed offsets relative to the last
|
| + relocated segment.
|
| +
|
| +`qP MODE THREAD-ID'
|
| + Returns information on THREAD-ID. Where: MODE is a hex encoded 32
|
| + bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).
|
| +
|
| + Don't use this packet; use the `qThreadExtraInfo' query instead
|
| + (see below).
|
| +
|
| + Reply: see `remote.c:remote_unpack_thread_info_response()'.
|
| +
|
| +`QNonStop:1'
|
| +`QNonStop:0'
|
| + Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode.
|
| + *Note Remote Non-Stop::, for more information.
|
| +
|
| + Reply:
|
| + `OK'
|
| + The request succeeded.
|
| +
|
| + `E NN'
|
| + An error occurred. NN are hex digits.
|
| +
|
| + `'
|
| + An empty reply indicates that `QNonStop' is not supported by
|
| + the stub.
|
| +
|
| + This packet is not probed by default; the remote stub must request
|
| + it, by supplying an appropriate `qSupported' response (*note
|
| + qSupported::). Use of this packet is controlled by the `set
|
| + non-stop' command; *note Non-Stop Mode::.
|
| +
|
| +`QPassSignals: SIGNAL [;SIGNAL]...'
|
| + Each listed SIGNAL should be passed directly to the inferior
|
| + process. Signals are numbered identically to continue packets and
|
| + stop replies (*note Stop Reply Packets::). Each SIGNAL list item
|
| + should be strictly greater than the previous item. These signals
|
| + do not need to stop the inferior, or be reported to GDB. All
|
| + other signals should be reported to GDB. Multiple `QPassSignals'
|
| + packets do not combine; any earlier `QPassSignals' list is
|
| + completely replaced by the new list. This packet improves
|
| + performance when using `handle SIGNAL nostop noprint pass'.
|
| +
|
| + Reply:
|
| + `OK'
|
| + The request succeeded.
|
| +
|
| + `E NN'
|
| + An error occurred. NN are hex digits.
|
| +
|
| + `'
|
| + An empty reply indicates that `QPassSignals' is not supported
|
| + by the stub.
|
| +
|
| + Use of this packet is controlled by the `set remote pass-signals'
|
| + command (*note set remote pass-signals: Remote Configuration.).
|
| + This packet is not probed by default; the remote stub must request
|
| + it, by supplying an appropriate `qSupported' response (*note
|
| + qSupported::).
|
| +
|
| +`QProgramSignals: SIGNAL [;SIGNAL]...'
|
| + Each listed SIGNAL may be delivered to the inferior process.
|
| + Others should be silently discarded.
|
| +
|
| + In some cases, the remote stub may need to decide whether to
|
| + deliver a signal to the program or not without GDB involvement.
|
| + One example of that is while detaching -- the program's threads
|
| + may have stopped for signals that haven't yet had a chance of
|
| + being reported to GDB, and so the remote stub can use the signal
|
| + list specified by this packet to know whether to deliver or ignore
|
| + those pending signals.
|
| +
|
| + This does not influence whether to deliver a signal as requested
|
| + by a resumption packet (*note vCont packet::).
|
| +
|
| + Signals are numbered identically to continue packets and stop
|
| + replies (*note Stop Reply Packets::). Each SIGNAL list item
|
| + should be strictly greater than the previous item. Multiple
|
| + `QProgramSignals' packets do not combine; any earlier
|
| + `QProgramSignals' list is completely replaced by the new list.
|
| +
|
| + Reply:
|
| + `OK'
|
| + The request succeeded.
|
| +
|
| + `E NN'
|
| + An error occurred. NN are hex digits.
|
| +
|
| + `'
|
| + An empty reply indicates that `QProgramSignals' is not
|
| + supported by the stub.
|
| +
|
| + Use of this packet is controlled by the `set remote
|
| + program-signals' command (*note set remote program-signals: Remote
|
| + Configuration.). This packet is not probed by default; the remote
|
| + stub must request it, by supplying an appropriate `qSupported'
|
| + response (*note qSupported::).
|
| +
|
| +`qRcmd,COMMAND'
|
| + COMMAND (hex encoded) is passed to the local interpreter for
|
| + execution. Invalid commands should be reported using the output
|
| + string. Before the final result packet, the target may also
|
| + respond with a number of intermediate `OOUTPUT' console output
|
| + packets. _Implementors should note that providing access to a
|
| + stubs's interpreter may have security implications_.
|
| +
|
| + Reply:
|
| + `OK'
|
| + A command response with no output.
|
| +
|
| + `OUTPUT'
|
| + A command response with the hex encoded output string OUTPUT.
|
| +
|
| + `E NN'
|
| + Indicate a badly formed request.
|
| +
|
| + `'
|
| + An empty reply indicates that `qRcmd' is not recognized.
|
| +
|
| + (Note that the `qRcmd' packet's name is separated from the command
|
| + by a `,', not a `:', contrary to the naming conventions above.
|
| + Please don't use this packet as a model for new packets.)
|
|
|
| - The Host I/O request packets all encode a single operation along with
|
| -its arguments. They have this format:
|
| +`qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'
|
| + Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and
|
| + LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes,
|
| + hex encoded.
|
|
|
| -`vFile:OPERATION: PARAMETER...'
|
| - OPERATION is the name of the particular request; the target should
|
| - compare the entire packet name up to the second colon when checking
|
| - for a supported operation. The format of PARAMETER depends on the
|
| - operation. Numbers are always passed in hexadecimal. Negative
|
| - numbers have an explicit minus sign (i.e. two's complement is not
|
| - used). Strings (e.g. filenames) are encoded as a series of
|
| - hexadecimal bytes. The last argument to a system call may be a
|
| - buffer of escaped binary data (*note Binary Data::).
|
| + Reply:
|
| + `0'
|
| + The pattern was not found.
|
| +
|
| + `1,address'
|
| + The pattern was found at ADDRESS.
|
| +
|
| + `E NN'
|
| + A badly formed request or an error was encountered while
|
| + searching memory.
|
| +
|
| + `'
|
| + An empty reply indicates that `qSearch:memory' is not
|
| + recognized.
|
| +
|
| +`QStartNoAckMode'
|
| + Request that the remote stub disable the normal `+'/`-' protocol
|
| + acknowledgments (*note Packet Acknowledgment::).
|
| +
|
| + Reply:
|
| + `OK'
|
| + The stub has switched to no-acknowledgment mode. GDB
|
| + acknowledges this reponse, but neither the stub nor GDB shall
|
| + send or expect further `+'/`-' acknowledgments in the current
|
| + connection.
|
| +
|
| + `'
|
| + An empty reply indicates that the stub does not support
|
| + no-acknowledgment mode.
|
| +
|
| +`qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
|
| + Tell the remote stub about features supported by GDB, and query
|
| + the stub for features it supports. This packet allows GDB and the
|
| + remote stub to take advantage of each others' features.
|
| + `qSupported' also consolidates multiple feature probes at startup,
|
| + to improve GDB performance--a single larger packet performs better
|
| + than multiple smaller probe packets on high-latency links. Some
|
| + features may enable behavior which must not be on by default, e.g.
|
| + because it would confuse older clients or stubs. Other features
|
| + may describe packets which could be automatically probed for, but
|
| + are not. These features must be reported before GDB will use
|
| + them. This "default unsupported" behavior is not appropriate for
|
| + all packets, but it helps to keep the initial connection time
|
| + under control with new versions of GDB which support increasing
|
| + numbers of packets.
|
| +
|
| + Reply:
|
| + `STUBFEATURE [;STUBFEATURE]...'
|
| + The stub supports or does not support each returned
|
| + STUBFEATURE, depending on the form of each STUBFEATURE (see
|
| + below for the possible forms).
|
| +
|
| + `'
|
| + An empty reply indicates that `qSupported' is not recognized,
|
| + or that no features needed to be reported to GDB.
|
| +
|
| + The allowed forms for each feature (either a GDBFEATURE in the
|
| + `qSupported' packet, or a STUBFEATURE in the response) are:
|
| +
|
| + `NAME=VALUE'
|
| + The remote protocol feature NAME is supported, and associated
|
| + with the specified VALUE. The format of VALUE depends on the
|
| + feature, but it must not include a semicolon.
|
| +
|
| + `NAME+'
|
| + The remote protocol feature NAME is supported, and does not
|
| + need an associated value.
|
| +
|
| + `NAME-'
|
| + The remote protocol feature NAME is not supported.
|
| +
|
| + `NAME?'
|
| + The remote protocol feature NAME may be supported, and GDB
|
| + should auto-detect support in some other way when it is
|
| + needed. This form will not be used for GDBFEATURE
|
| + notifications, but may be used for STUBFEATURE responses.
|
| +
|
| + Whenever the stub receives a `qSupported' request, the supplied
|
| + set of GDB features should override any previous request. This
|
| + allows GDB to put the stub in a known state, even if the stub had
|
| + previously been communicating with a different version of GDB.
|
| +
|
| + The following values of GDBFEATURE (for the packet sent by GDB)
|
| + are defined:
|
| +
|
| + `multiprocess'
|
| + This feature indicates whether GDB supports multiprocess
|
| + extensions to the remote protocol. GDB does not use such
|
| + extensions unless the stub also reports that it supports them
|
| + by including `multiprocess+' in its `qSupported' reply.
|
| + *Note multiprocess extensions::, for details.
|
| +
|
| + `xmlRegisters'
|
| + This feature indicates that GDB supports the XML target
|
| + description. If the stub sees `xmlRegisters=' with target
|
| + specific strings separated by a comma, it will report register
|
| + description.
|
| +
|
| + `qRelocInsn'
|
| + This feature indicates whether GDB supports the `qRelocInsn'
|
| + packet (*note Relocate instruction reply packet: Tracepoint
|
| + Packets.).
|
| +
|
| + Stubs should ignore any unknown values for GDBFEATURE. Any GDB
|
| + which sends a `qSupported' packet supports receiving packets of
|
| + unlimited length (earlier versions of GDB may reject overly long
|
| + responses). Additional values for GDBFEATURE may be defined in
|
| + the future to let the stub take advantage of new features in GDB,
|
| + e.g. incompatible improvements in the remote protocol--the
|
| + `multiprocess' feature is an example of such a feature. The
|
| + stub's reply should be independent of the GDBFEATURE entries sent
|
| + by GDB; first GDB describes all the features it supports, and then
|
| + the stub replies with all the features it supports.
|
| +
|
| + Similarly, GDB will silently ignore unrecognized stub feature
|
| + responses, as long as each response uses one of the standard forms.
|
| +
|
| + Some features are flags. A stub which supports a flag feature
|
| + should respond with a `+' form response. Other features require
|
| + values, and the stub should respond with an `=' form response.
|
| +
|
| + Each feature has a default value, which GDB will use if
|
| + `qSupported' is not available or if the feature is not mentioned
|
| + in the `qSupported' response. The default values are fixed; a
|
| + stub is free to omit any feature responses that match the defaults.
|
| +
|
| + Not all features can be probed, but for those which can, the
|
| + probing mechanism is useful: in some cases, a stub's internal
|
| + architecture may not allow the protocol layer to know some
|
| + information about the underlying target in advance. This is
|
| + especially common in stubs which may be configured for multiple
|
| + targets.
|
| +
|
| + These are the currently defined stub features and their properties:
|
| +
|
| + Feature Name Value Default Probe Allowed
|
| + Required
|
| + `PacketSize' Yes `-' No
|
| + `qXfer:auxv:read' No `-' Yes
|
| + `qXfer:btrace:read' No `-' Yes
|
| + `qXfer:features:read' No `-' Yes
|
| + `qXfer:libraries:read' No `-' Yes
|
| + `qXfer:libraries-svr4:read'No `-' Yes
|
| + `augmented-libraries-svr4-read'No `-' No
|
| + `qXfer:memory-map:read' No `-' Yes
|
| + `qXfer:sdata:read' No `-' Yes
|
| + `qXfer:spu:read' No `-' Yes
|
| + `qXfer:spu:write' No `-' Yes
|
| + `qXfer:siginfo:read' No `-' Yes
|
| + `qXfer:siginfo:write' No `-' Yes
|
| + `qXfer:threads:read' No `-' Yes
|
| + `qXfer:traceframe-info:read'No `-' Yes
|
| + `qXfer:uib:read' No `-' Yes
|
| + `qXfer:fdpic:read' No `-' Yes
|
| + `Qbtrace:off' Yes `-' Yes
|
| + `Qbtrace:bts' Yes `-' Yes
|
| + `QNonStop' No `-' Yes
|
| + `QPassSignals' No `-' Yes
|
| + `QStartNoAckMode' No `-' Yes
|
| + `multiprocess' No `-' No
|
| + `ConditionalBreakpoints'No `-' No
|
| + `ConditionalTracepoints'No `-' No
|
| + `ReverseContinue' No `-' No
|
| + `ReverseStep' No `-' No
|
| + `TracepointSource' No `-' No
|
| + `QAgent' No `-' No
|
| + `QAllow' No `-' No
|
| + `QDisableRandomization' No `-' No
|
| + `EnableDisableTracepoints'No `-' No
|
| + `QTBuffer:size' No `-' No
|
| + `tracenz' No `-' No
|
| + `BreakpointCommands' No `-' No
|
| +
|
| + These are the currently defined stub features, in more detail:
|
| +
|
| + `PacketSize=BYTES'
|
| + The remote stub can accept packets up to at least BYTES in
|
| + length. GDB will send packets up to this size for bulk
|
| + transfers, and will never send larger packets. This is a
|
| + limit on the data characters in the packet, including the
|
| + frame and checksum. There is no trailing NUL byte in a
|
| + remote protocol packet; if the stub stores packets in a
|
| + NUL-terminated format, it should allow an extra byte in its
|
| + buffer for the NUL. If this stub feature is not supported,
|
| + GDB guesses based on the size of the `g' packet response.
|
| +
|
| + `qXfer:auxv:read'
|
| + The remote stub understands the `qXfer:auxv:read' packet
|
| + (*note qXfer auxiliary vector read::).
|
| +
|
| + `qXfer:btrace:read'
|
| + The remote stub understands the `qXfer:btrace:read' packet
|
| + (*note qXfer btrace read::).
|
| +
|
| + `qXfer:features:read'
|
| + The remote stub understands the `qXfer:features:read' packet
|
| + (*note qXfer target description read::).
|
| +
|
| + `qXfer:libraries:read'
|
| + The remote stub understands the `qXfer:libraries:read' packet
|
| + (*note qXfer library list read::).
|
| +
|
| + `qXfer:libraries-svr4:read'
|
| + The remote stub understands the `qXfer:libraries-svr4:read'
|
| + packet (*note qXfer svr4 library list read::).
|
| +
|
| + `augmented-libraries-svr4-read'
|
| + The remote stub understands the augmented form of the
|
| + `qXfer:libraries-svr4:read' packet (*note qXfer svr4 library
|
| + list read::).
|
| +
|
| + `qXfer:memory-map:read'
|
| + The remote stub understands the `qXfer:memory-map:read' packet
|
| + (*note qXfer memory map read::).
|
| +
|
| + `qXfer:sdata:read'
|
| + The remote stub understands the `qXfer:sdata:read' packet
|
| + (*note qXfer sdata read::).
|
| +
|
| + `qXfer:spu:read'
|
| + The remote stub understands the `qXfer:spu:read' packet
|
| + (*note qXfer spu read::).
|
| +
|
| + `qXfer:spu:write'
|
| + The remote stub understands the `qXfer:spu:write' packet
|
| + (*note qXfer spu write::).
|
| +
|
| + `qXfer:siginfo:read'
|
| + The remote stub understands the `qXfer:siginfo:read' packet
|
| + (*note qXfer siginfo read::).
|
| +
|
| + `qXfer:siginfo:write'
|
| + The remote stub understands the `qXfer:siginfo:write' packet
|
| + (*note qXfer siginfo write::).
|
| +
|
| + `qXfer:threads:read'
|
| + The remote stub understands the `qXfer:threads:read' packet
|
| + (*note qXfer threads read::).
|
| +
|
| + `qXfer:traceframe-info:read'
|
| + The remote stub understands the `qXfer:traceframe-info:read'
|
| + packet (*note qXfer traceframe info read::).
|
| +
|
| + `qXfer:uib:read'
|
| + The remote stub understands the `qXfer:uib:read' packet
|
| + (*note qXfer unwind info block::).
|
| +
|
| + `qXfer:fdpic:read'
|
| + The remote stub understands the `qXfer:fdpic:read' packet
|
| + (*note qXfer fdpic loadmap read::).
|
|
|
| + `QNonStop'
|
| + The remote stub understands the `QNonStop' packet (*note
|
| + QNonStop::).
|
|
|
| - The valid responses to Host I/O packets are:
|
| + `QPassSignals'
|
| + The remote stub understands the `QPassSignals' packet (*note
|
| + QPassSignals::).
|
|
|
| -`F RESULT [, ERRNO] [; ATTACHMENT]'
|
| - RESULT is the integer value returned by this operation, usually
|
| - non-negative for success and -1 for errors. If an error has
|
| - occured, ERRNO will be included in the result. ERRNO will have a
|
| - value defined by the File-I/O protocol (*note Errno Values::). For
|
| - operations which return data, ATTACHMENT supplies the data as a
|
| - binary buffer. Binary buffers in response packets are escaped in
|
| - the normal way (*note Binary Data::). See the individual packet
|
| - documentation for the interpretation of RESULT and ATTACHMENT.
|
| + `QStartNoAckMode'
|
| + The remote stub understands the `QStartNoAckMode' packet and
|
| + prefers to operate in no-acknowledgment mode. *Note Packet
|
| + Acknowledgment::.
|
|
|
| -`'
|
| - An empty response indicates that this operation is not recognized.
|
| + `multiprocess'
|
| + The remote stub understands the multiprocess extensions to
|
| + the remote protocol syntax. The multiprocess extensions
|
| + affect the syntax of thread IDs in both packets and replies
|
| + (*note thread-id syntax::), and add process IDs to the `D'
|
| + packet and `W' and `X' replies. Note that reporting this
|
| + feature indicates support for the syntactic extensions only,
|
| + not that the stub necessarily supports debugging of more than
|
| + one process at a time. The stub must not use multiprocess
|
| + extensions in packet replies unless GDB has also indicated it
|
| + supports them in its `qSupported' request.
|
|
|
| + `qXfer:osdata:read'
|
| + The remote stub understands the `qXfer:osdata:read' packet
|
| + ((*note qXfer osdata read::).
|
|
|
| - These are the supported Host I/O operations:
|
| + `ConditionalBreakpoints'
|
| + The target accepts and implements evaluation of conditional
|
| + expressions defined for breakpoints. The target will only
|
| + report breakpoint triggers when such conditions are true
|
| + (*note Break Conditions: Conditions.).
|
|
|
| -`vFile:open: PATHNAME, FLAGS, MODE'
|
| - Open a file at PATHNAME and return a file descriptor for it, or
|
| - return -1 if an error occurs. PATHNAME is a string, FLAGS is an
|
| - integer indicating a mask of open flags (*note Open Flags::), and
|
| - MODE is an integer indicating a mask of mode bits to use if the
|
| - file is created (*note mode_t Values::). *Note open::, for
|
| - details of the open flags and mode values.
|
| + `ConditionalTracepoints'
|
| + The remote stub accepts and implements conditional
|
| + expressions defined for tracepoints (*note Tracepoint
|
| + Conditions::).
|
|
|
| -`vFile:close: FD'
|
| - Close the open file corresponding to FD and return 0, or -1 if an
|
| - error occurs.
|
| + `ReverseContinue'
|
| + The remote stub accepts and implements the reverse continue
|
| + packet (*note bc::).
|
|
|
| -`vFile:pread: FD, COUNT, OFFSET'
|
| - Read data from the open file corresponding to FD. Up to COUNT
|
| - bytes will be read from the file, starting at OFFSET relative to
|
| - the start of the file. The target may read fewer bytes; common
|
| - reasons include packet size limits and an end-of-file condition.
|
| - The number of bytes read is returned. Zero should only be
|
| - returned for a successful read at the end of the file, or if COUNT
|
| - was zero.
|
| + `ReverseStep'
|
| + The remote stub accepts and implements the reverse step packet
|
| + (*note bs::).
|
|
|
| - The data read should be returned as a binary attachment on success.
|
| - If zero bytes were read, the response should include an empty
|
| - binary attachment (i.e. a trailing semicolon). The return value
|
| - is the number of target bytes read; the binary attachment may be
|
| - longer if some characters were escaped.
|
| + `TracepointSource'
|
| + The remote stub understands the `QTDPsrc' packet that supplies
|
| + the source form of tracepoint definitions.
|
|
|
| -`vFile:pwrite: FD, OFFSET, DATA'
|
| - Write DATA (a binary buffer) to the open file corresponding to FD.
|
| - Start the write at OFFSET from the start of the file. Unlike
|
| - many `write' system calls, there is no separate COUNT argument;
|
| - the length of DATA in the packet is used. `vFile:write' returns
|
| - the number of bytes written, which may be shorter than the length
|
| - of DATA, or -1 if an error occurred.
|
| + `QAgent'
|
| + The remote stub understands the `QAgent' packet.
|
|
|
| -`vFile:unlink: PATHNAME'
|
| - Delete the file at PATHNAME on the target. Return 0, or -1 if an
|
| - error occurs. PATHNAME is a string.
|
| + `QAllow'
|
| + The remote stub understands the `QAllow' packet.
|
|
|
| -`vFile:readlink: FILENAME'
|
| - Read value of symbolic link FILENAME on the target. Return the
|
| - number of bytes read, or -1 if an error occurs.
|
| + `QDisableRandomization'
|
| + The remote stub understands the `QDisableRandomization'
|
| + packet.
|
|
|
| - The data read should be returned as a binary attachment on success.
|
| - If zero bytes were read, the response should include an empty
|
| - binary attachment (i.e. a trailing semicolon). The return value
|
| - is the number of target bytes read; the binary attachment may be
|
| - longer if some characters were escaped.
|
| + `StaticTracepoint'
|
| + The remote stub supports static tracepoints.
|
|
|
| + `InstallInTrace'
|
| + The remote stub supports installing tracepoint in tracing.
|
|
|
| -
|
| -File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol
|
| + `EnableDisableTracepoints'
|
| + The remote stub supports the `QTEnable' (*note QTEnable::) and
|
| + `QTDisable' (*note QTDisable::) packets that allow tracepoints
|
| + to be enabled and disabled while a trace experiment is
|
| + running.
|
|
|
| -E.8 Interrupts
|
| -==============
|
| + `QTBuffer:size'
|
| + The remote stub supports the `QTBuffer:size' (*note
|
| + QTBuffer-size::) packet that allows to change the size of the
|
| + trace buffer.
|
|
|
| -When a program on the remote target is running, GDB may attempt to
|
| -interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by
|
| -`g', control of which is specified via GDB's `interrupt-sequence'.
|
| + `tracenz'
|
| + The remote stub supports the `tracenz' bytecode for
|
| + collecting strings. See *note Bytecode Descriptions:: for
|
| + details about the bytecode.
|
|
|
| - The precise meaning of `BREAK' is defined by the transport mechanism
|
| -and may, in fact, be undefined. GDB does not currently define a
|
| -`BREAK' mechanism for any of the network interfaces except for TCP, in
|
| -which case GDB sends the `telnet' BREAK sequence.
|
| + `BreakpointCommands'
|
| + The remote stub supports running a breakpoint's command list
|
| + itself, rather than reporting the hit to GDB.
|
|
|
| - `Ctrl-C', on the other hand, is defined and implemented for all
|
| -transport mechanisms. It is represented by sending the single byte
|
| -`0x03' without any of the usual packet overhead described in the
|
| -Overview section (*note Overview::). When a `0x03' byte is transmitted
|
| -as part of a packet, it is considered to be packet data and does _not_
|
| -represent an interrupt. E.g., an `X' packet (*note X packet::), used
|
| -for binary downloads, may include an unescaped `0x03' as part of its
|
| -packet.
|
| + `Qbtrace:off'
|
| + The remote stub understands the `Qbtrace:off' packet.
|
|
|
| - `BREAK' followed by `g' is also known as Magic SysRq g. When Linux
|
| -kernel receives this sequence from serial port, it stops execution and
|
| -connects to gdb.
|
| + `Qbtrace:bts'
|
| + The remote stub understands the `Qbtrace:bts' packet.
|
|
|
| - Stubs are not required to recognize these interrupt mechanisms and
|
| -the precise meaning associated with receipt of the interrupt is
|
| -implementation defined. If the target supports debugging of multiple
|
| -threads and/or processes, it should attempt to interrupt all
|
| -currently-executing threads and processes. If the stub is successful
|
| -at interrupting the running program, it should send one of the stop
|
| -reply packets (*note Stop Reply Packets::) to GDB as a result of
|
| -successfully stopping the program in all-stop mode, and a stop reply
|
| -for each stopped thread in non-stop mode. Interrupts received while the
|
| -program is stopped are discarded.
|
|
|
| -
|
| -File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol
|
| +`qSymbol::'
|
| + Notify the target that GDB is prepared to serve symbol lookup
|
| + requests. Accept requests from the target for the values of
|
| + symbols.
|
|
|
| -E.9 Notification Packets
|
| -========================
|
| + Reply:
|
| + `OK'
|
| + The target does not need to look up any (more) symbols.
|
|
|
| -The GDB remote serial protocol includes "notifications", packets that
|
| -require no acknowledgment. Both the GDB and the stub may send
|
| -notifications (although the only notifications defined at present are
|
| -sent by the stub). Notifications carry information without incurring
|
| -the round-trip latency of an acknowledgment, and so are useful for
|
| -low-impact communications where occasional packet loss is not a problem.
|
| + `qSymbol:SYM_NAME'
|
| + The target requests the value of symbol SYM_NAME (hex
|
| + encoded). GDB may provide the value by using the
|
| + `qSymbol:SYM_VALUE:SYM_NAME' message, described below.
|
|
|
| - A notification packet has the form `% DATA # CHECKSUM', where DATA
|
| -is the content of the notification, and CHECKSUM is a checksum of DATA,
|
| -computed and formatted as for ordinary GDB packets. A notification's
|
| -DATA never contains `$', `%' or `#' characters. Upon receiving a
|
| -notification, the recipient sends no `+' or `-' to acknowledge the
|
| -notification's receipt or to report its corruption.
|
| +`qSymbol:SYM_VALUE:SYM_NAME'
|
| + Set the value of SYM_NAME to SYM_VALUE.
|
|
|
| - Every notification's DATA begins with a name, which contains no
|
| -colon characters, followed by a colon character.
|
| + SYM_NAME (hex encoded) is the name of a symbol whose value the
|
| + target has previously requested.
|
|
|
| - Recipients should silently ignore corrupted notifications and
|
| -notifications they do not understand. Recipients should restart
|
| -timeout periods on receipt of a well-formed notification, whether or
|
| -not they understand it.
|
| + SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot
|
| + supply a value for SYM_NAME, then this field will be empty.
|
|
|
| - Senders should only send the notifications described here when this
|
| -protocol description specifies that they are permitted. In the future,
|
| -we may extend the protocol to permit existing notifications in new
|
| -contexts; this rule helps older senders avoid confusing newer
|
| -recipients.
|
| + Reply:
|
| + `OK'
|
| + The target does not need to look up any (more) symbols.
|
|
|
| - (Older versions of GDB ignore bytes received until they see the `$'
|
| -byte that begins an ordinary packet, so new stubs may transmit
|
| -notifications without fear of confusing older clients. There are no
|
| -notifications defined for GDB to send at the moment, but we assume that
|
| -most older stubs would ignore them, as well.)
|
| + `qSymbol:SYM_NAME'
|
| + The target requests the value of a new symbol SYM_NAME (hex
|
| + encoded). GDB will continue to supply the values of symbols
|
| + (if available), until the target ceases to request them.
|
|
|
| - The following notification packets from the stub to GDB are defined:
|
| +`qTBuffer'
|
| +`QTBuffer'
|
| +`QTDisconnected'
|
| +`QTDP'
|
| +`QTDPsrc'
|
| +`QTDV'
|
| +`qTfP'
|
| +`qTfV'
|
| +`QTFrame'
|
| +`qTMinFTPILen'
|
| + *Note Tracepoint Packets::.
|
|
|
| -`Stop: REPLY'
|
| - Report an asynchronous stop event in non-stop mode. The REPLY has
|
| - the form of a stop reply, as described in *Note Stop Reply
|
| - Packets::. Refer to *Note Remote Non-Stop::, for information on
|
| - how these notifications are acknowledged by GDB.
|
| +`qThreadExtraInfo,THREAD-ID'
|
| + Obtain a printable string description of a thread's attributes from
|
| + the target OS. THREAD-ID is a thread ID; see *note thread-id
|
| + syntax::. This string may contain anything that the target OS
|
| + thinks is interesting for GDB to tell the user about the thread.
|
| + The string is displayed in GDB's `info threads' display. Some
|
| + examples of possible thread extra info strings are `Runnable', or
|
| + `Blocked on Mutex'.
|
|
|
| -
|
| -File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol
|
| + Reply:
|
| + `XX...'
|
| + Where `XX...' is a hex encoding of ASCII data, comprising the
|
| + printable string containing the extra information about the
|
| + thread's attributes.
|
|
|
| -E.10 Remote Protocol Support for Non-Stop Mode
|
| -==============================================
|
| + (Note that the `qThreadExtraInfo' packet's name is separated from
|
| + the command by a `,', not a `:', contrary to the naming
|
| + conventions above. Please don't use this packet as a model for new
|
| + packets.)
|
|
|
| -GDB's remote protocol supports non-stop debugging of multi-threaded
|
| -programs, as described in *Note Non-Stop Mode::. If the stub supports
|
| -non-stop mode, it should report that to GDB by including `QNonStop+' in
|
| -its `qSupported' response (*note qSupported::).
|
| +`QTNotes'
|
| +`qTP'
|
| +`QTSave'
|
| +`qTsP'
|
| +`qTsV'
|
| +`QTStart'
|
| +`QTStop'
|
| +`QTEnable'
|
| +`QTDisable'
|
| +`QTinit'
|
| +`QTro'
|
| +`qTStatus'
|
| +`qTV'
|
| +`qTfSTM'
|
| +`qTsSTM'
|
| +`qTSTMat'
|
| + *Note Tracepoint Packets::.
|
|
|
| - GDB typically sends a `QNonStop' packet only when establishing a new
|
| -connection with the stub. Entering non-stop mode does not alter the
|
| -state of any currently-running threads, but targets must stop all
|
| -threads in any already-attached processes when entering all-stop mode.
|
| -GDB uses the `?' packet as necessary to probe the target state after a
|
| -mode change.
|
| +`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
|
| + Read uninterpreted bytes from the target's special data area
|
| + identified by the keyword OBJECT. Request LENGTH bytes starting
|
| + at OFFSET bytes into the data. The content and encoding of ANNEX
|
| + is specific to OBJECT; it can supply additional details about what
|
| + data to access.
|
|
|
| - In non-stop mode, when an attached process encounters an event that
|
| -would otherwise be reported with a stop reply, it uses the asynchronous
|
| -notification mechanism (*note Notification Packets::) to inform GDB.
|
| -In contrast to all-stop mode, where all threads in all processes are
|
| -stopped when a stop reply is sent, in non-stop mode only the thread
|
| -reporting the stop event is stopped. That is, when reporting a `S' or
|
| -`T' response to indicate completion of a step operation, hitting a
|
| -breakpoint, or a fault, only the affected thread is stopped; any other
|
| -still-running threads continue to run. When reporting a `W' or `X'
|
| -response, all running threads belonging to other attached processes
|
| -continue to run.
|
| + Here are the specific requests of this form defined so far. All
|
| + `qXfer:OBJECT:read:...' requests use the same reply formats,
|
| + listed below.
|
|
|
| - Only one stop reply notification at a time may be pending; if
|
| -additional stop events occur before GDB has acknowledged the previous
|
| -notification, they must be queued by the stub for later synchronous
|
| -transmission in response to `vStopped' packets from GDB. Because the
|
| -notification mechanism is unreliable, the stub is permitted to resend a
|
| -stop reply notification if it believes GDB may not have received it.
|
| -GDB ignores additional stop reply notifications received before it has
|
| -finished processing a previous notification and the stub has completed
|
| -sending any queued stop events.
|
| -
|
| - Otherwise, GDB must be prepared to receive a stop reply notification
|
| -at any time. Specifically, they may appear when GDB is not otherwise
|
| -reading input from the stub, or when GDB is expecting to read a normal
|
| -synchronous response or a `+'/`-' acknowledgment to a packet it has
|
| -sent. Notification packets are distinct from any other communication
|
| -from the stub so there is no ambiguity.
|
| + `qXfer:auxv:read::OFFSET,LENGTH'
|
| + Access the target's "auxiliary vector". *Note auxiliary
|
| + vector: OS Information. Note ANNEX must be empty.
|
|
|
| - After receiving a stop reply notification, GDB shall acknowledge it
|
| -by sending a `vStopped' packet (*note vStopped packet::) as a regular,
|
| -synchronous request to the stub. Such acknowledgment is not required
|
| -to happen immediately, as GDB is permitted to send other, unrelated
|
| -packets to the stub first, which the stub should process normally.
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - Upon receiving a `vStopped' packet, if the stub has other queued
|
| -stop events to report to GDB, it shall respond by sending a normal stop
|
| -reply response. GDB shall then send another `vStopped' packet to
|
| -solicit further responses; again, it is permitted to send other,
|
| -unrelated packets as well which the stub should process normally.
|
| + `qXfer:btrace:read:ANNEX:OFFSET,LENGTH'
|
| + Return a description of the current branch trace. *Note
|
| + Branch Trace Format::. The annex part of the generic `qXfer'
|
| + packet may have one of the following values:
|
|
|
| - If the stub receives a `vStopped' packet and there are no additional
|
| -stop events to report, the stub shall return an `OK' response. At this
|
| -point, if further stop events occur, the stub shall send a new stop
|
| -reply notification, GDB shall accept the notification, and the process
|
| -shall be repeated.
|
| + `all'
|
| + Returns all available branch trace.
|
|
|
| - In non-stop mode, the target shall respond to the `?' packet as
|
| -follows. First, any incomplete stop reply notification/`vStopped'
|
| -sequence in progress is abandoned. The target must begin a new
|
| -sequence reporting stop events for all stopped threads, whether or not
|
| -it has previously reported those events to GDB. The first stop reply
|
| -is sent as a synchronous reply to the `?' packet, and subsequent stop
|
| -replies are sent as responses to `vStopped' packets using the mechanism
|
| -described above. The target must not send asynchronous stop reply
|
| -notifications until the sequence is complete. If all threads are
|
| -running when the target receives the `?' packet, or if the target is
|
| -not attached to any process, it shall respond `OK'.
|
| + `new'
|
| + Returns all available branch trace if the branch trace
|
| + changed since the last read request.
|
|
|
| -
|
| -File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol
|
| + This packet is not probed by default; the remote stub must
|
| + request it by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| -E.11 Packet Acknowledgment
|
| -==========================
|
| + `qXfer:features:read:ANNEX:OFFSET,LENGTH'
|
| + Access the "target description". *Note Target
|
| + Descriptions::. The annex specifies which XML document to
|
| + access. The main description is always loaded from the
|
| + `target.xml' annex.
|
|
|
| -By default, when either the host or the target machine receives a
|
| -packet, the first response expected is an acknowledgment: either `+'
|
| -(to indicate the package was received correctly) or `-' (to request
|
| -retransmission). This mechanism allows the GDB remote protocol to
|
| -operate over unreliable transport mechanisms, such as a serial line.
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - In cases where the transport mechanism is itself reliable (such as a
|
| -pipe or TCP connection), the `+'/`-' acknowledgments are redundant. It
|
| -may be desirable to disable them in that case to reduce communication
|
| -overhead, or for other reasons. This can be accomplished by means of
|
| -the `QStartNoAckMode' packet; *note QStartNoAckMode::.
|
| + `qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
|
| + Access the target's list of loaded libraries. *Note Library
|
| + List Format::. The annex part of the generic `qXfer' packet
|
| + must be empty (*note qXfer read::).
|
|
|
| - When in no-acknowledgment mode, neither the stub nor GDB shall send
|
| -or expect `+'/`-' protocol acknowledgments. The packet and response
|
| -format still includes the normal checksum, as described in *Note
|
| -Overview::, but the checksum may be ignored by the receiver.
|
| + Targets which maintain a list of libraries in the program's
|
| + memory do not need to implement this packet; it is designed
|
| + for platforms where the operating system manages the list of
|
| + loaded libraries.
|
|
|
| - If the stub supports `QStartNoAckMode' and prefers to operate in
|
| -no-acknowledgment mode, it should report that to GDB by including
|
| -`QStartNoAckMode+' in its response to `qSupported'; *note qSupported::.
|
| -If GDB also supports `QStartNoAckMode' and it has not been disabled via
|
| -the `set remote noack-packet off' command (*note Remote
|
| -Configuration::), GDB may then send a `QStartNoAckMode' packet to the
|
| -stub. Only then may the stub actually turn off packet acknowledgments.
|
| -GDB sends a final `+' acknowledgment of the stub's `OK' response, which
|
| -can be safely ignored by the stub.
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - Note that `set remote noack-packet' command only affects negotiation
|
| -between GDB and the stub when subsequent connections are made; it does
|
| -not affect the protocol acknowledgment state for any current connection.
|
| -Since `+'/`-' acknowledgments are enabled by default when a new
|
| -connection is established, there is also no protocol request to
|
| -re-enable the acknowledgments for the current connection, once disabled.
|
| + `qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH'
|
| + Access the target's list of loaded libraries when the target
|
| + is an SVR4 platform. *Note Library List Format for SVR4
|
| + Targets::. The annex part of the generic `qXfer' packet must
|
| + be empty unless the remote stub indicated it supports the
|
| + augmented form of this packet by supplying an appropriate
|
| + `qSupported' response (*note qXfer read::, *note
|
| + qSupported::).
|
|
|
| -
|
| -File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol
|
| + This packet is optional for better performance on SVR4
|
| + targets. GDB uses memory read packets to read the SVR4
|
| + library list otherwise.
|
|
|
| -E.12 Examples
|
| -=============
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| -Example sequence of a target being re-started. Notice how the restart
|
| -does not get any direct output:
|
| + If the remote stub indicates it supports the augmented form
|
| + of this packet then the annex part of the generic `qXfer'
|
| + packet may contain a semicolon-separated list of `NAME=VALUE'
|
| + arguments. The currently supported arguments are:
|
|
|
| - -> `R00'
|
| - <- `+'
|
| - _target restarts_
|
| - -> `?'
|
| - <- `+'
|
| - <- `T001:1234123412341234'
|
| - -> `+'
|
| + `start=ADDRESS'
|
| + A hexadecimal number specifying the address of the
|
| + `struct link_map' to start reading the library list
|
| + from. If unset or zero then the first `struct link_map'
|
| + in the library list will be chosen as the starting point.
|
|
|
| - Example sequence of a target being stepped by a single instruction:
|
| + `prev=ADDRESS'
|
| + A hexadecimal number specifying the address of the
|
| + `struct link_map' immediately preceding the `struct
|
| + link_map' specified by the `start' argument. If unset
|
| + or zero then the remote stub will expect that no `struct
|
| + link_map' exists prior to the starting point.
|
|
|
| - -> `G1445...'
|
| - <- `+'
|
| - -> `s'
|
| - <- `+'
|
| - _time passes_
|
| - <- `T001:1234123412341234'
|
| - -> `+'
|
| - -> `g'
|
| - <- `+'
|
| - <- `1455...'
|
| - -> `+'
|
|
|
| -
|
| -File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
|
| + Arguments that are not understood by the remote stub will be
|
| + silently ignored.
|
|
|
| -E.13 File-I/O Remote Protocol Extension
|
| -=======================================
|
| + `qXfer:memory-map:read::OFFSET,LENGTH'
|
| + Access the target's "memory-map". *Note Memory Map Format::.
|
| + The annex part of the generic `qXfer' packet must be empty
|
| + (*note qXfer read::).
|
|
|
| -* Menu:
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| -* File-I/O Overview::
|
| -* Protocol Basics::
|
| -* The F Request Packet::
|
| -* The F Reply Packet::
|
| -* The Ctrl-C Message::
|
| -* Console I/O::
|
| -* List of Supported Calls::
|
| -* Protocol-specific Representation of Datatypes::
|
| -* Constants::
|
| -* File-I/O Examples::
|
| + `qXfer:sdata:read::OFFSET,LENGTH'
|
| + Read contents of the extra collected static tracepoint marker
|
| + information. The annex part of the generic `qXfer' packet
|
| + must be empty (*note qXfer read::). *Note Tracepoint Action
|
| + Lists: Tracepoint Actions.
|
|
|
| -
|
| -File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| -E.13.1 File-I/O Overview
|
| -------------------------
|
| + `qXfer:siginfo:read::OFFSET,LENGTH'
|
| + Read contents of the extra signal information on the target
|
| + system. The annex part of the generic `qXfer' packet must be
|
| + empty (*note qXfer read::).
|
|
|
| -The "File I/O remote protocol extension" (short: File-I/O) allows the
|
| -target to use the host's file system and console I/O to perform various
|
| -system calls. System calls on the target system are translated into a
|
| -remote protocol packet to the host system, which then performs the
|
| -needed actions and returns a response packet to the target system.
|
| -This simulates file system operations even on targets that lack file
|
| -systems.
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - The protocol is defined to be independent of both the host and
|
| -target systems. It uses its own internal representation of datatypes
|
| -and values. Both GDB and the target's GDB stub are responsible for
|
| -translating the system-dependent value representations into the internal
|
| -protocol representations when data is transmitted.
|
| + `qXfer:spu:read:ANNEX:OFFSET,LENGTH'
|
| + Read contents of an `spufs' file on the target system. The
|
| + annex specifies which file to read; it must be of the form
|
| + `ID/NAME', where ID specifies an SPU context ID in the target
|
| + process, and NAME identifes the `spufs' file in that context
|
| + to be accessed.
|
|
|
| - The communication is synchronous. A system call is possible only
|
| -when GDB is waiting for a response from the `C', `c', `S' or `s'
|
| -packets. While GDB handles the request for a system call, the target
|
| -is stopped to allow deterministic access to the target's memory.
|
| -Therefore File-I/O is not interruptible by target signals. On the
|
| -other hand, it is possible to interrupt File-I/O by a user interrupt
|
| -(`Ctrl-C') within GDB.
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - The target's request to perform a host system call does not finish
|
| -the latest `C', `c', `S' or `s' action. That means, after finishing
|
| -the system call, the target returns to continuing the previous activity
|
| -(continue, step). No additional continue or step request from GDB is
|
| -required.
|
| + `qXfer:threads:read::OFFSET,LENGTH'
|
| + Access the list of threads on target. *Note Thread List
|
| + Format::. The annex part of the generic `qXfer' packet must
|
| + be empty (*note qXfer read::).
|
|
|
| - (gdb) continue
|
| - <- target requests 'system call X'
|
| - target is stopped, GDB executes system call
|
| - -> GDB returns result
|
| - ... target continues, GDB returns to wait for the target
|
| - <- target hits breakpoint and sends a Txx packet
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - The protocol only supports I/O on the console and to regular files on
|
| -the host file system. Character or block special devices, pipes, named
|
| -pipes, sockets or any other communication method on the host system are
|
| -not supported by this protocol.
|
| + `qXfer:traceframe-info:read::OFFSET,LENGTH'
|
| + Return a description of the current traceframe's contents.
|
| + *Note Traceframe Info Format::. The annex part of the generic
|
| + `qXfer' packet must be empty (*note qXfer read::).
|
|
|
| - File I/O is not supported in non-stop mode.
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| -
|
| -File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
|
| + `qXfer:uib:read:PC:OFFSET,LENGTH'
|
| + Return the unwind information block for PC. This packet is
|
| + used on OpenVMS/ia64 to ask the kernel unwind information.
|
|
|
| -E.13.2 Protocol Basics
|
| -----------------------
|
| + This packet is not probed by default.
|
|
|
| -The File-I/O protocol uses the `F' packet as the request as well as
|
| -reply packet. Since a File-I/O system call can only occur when GDB is
|
| -waiting for a response from the continuing or stepping target, the
|
| -File-I/O request is a reply that GDB has to expect as a result of a
|
| -previous `C', `c', `S' or `s' packet. This `F' packet contains all
|
| -information needed to allow GDB to call the appropriate host system
|
| -call:
|
| + `qXfer:fdpic:read:ANNEX:OFFSET,LENGTH'
|
| + Read contents of `loadmap's on the target system. The annex,
|
| + either `exec' or `interp', specifies which `loadmap',
|
| + executable `loadmap' or interpreter `loadmap' to read.
|
|
|
| - * A unique identifier for the requested system call.
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - * All parameters to the system call. Pointers are given as addresses
|
| - in the target memory address space. Pointers to strings are given
|
| - as pointer/length pair. Numerical values are given as they are.
|
| - Numerical control flags are given in a protocol-specific
|
| - representation.
|
| + `qXfer:osdata:read::OFFSET,LENGTH'
|
| + Access the target's "operating system information". *Note
|
| + Operating System Information::.
|
|
|
|
|
| - At this point, GDB has to perform the following actions.
|
| + Reply:
|
| + `m DATA'
|
| + Data DATA (*note Binary Data::) has been read from the
|
| + target. There may be more data at a higher address (although
|
| + it is permitted to return `m' even for the last valid block
|
| + of data, as long as at least one byte of data was read).
|
| + DATA may have fewer bytes than the LENGTH in the request.
|
|
|
| - * If the parameters include pointer values to data needed as input
|
| - to a system call, GDB requests this data from the target with a
|
| - standard `m' packet request. This additional communication has to
|
| - be expected by the target implementation and is handled as any
|
| - other `m' packet.
|
| + `l DATA'
|
| + Data DATA (*note Binary Data::) has been read from the target.
|
| + There is no more data to be read. DATA may have fewer bytes
|
| + than the LENGTH in the request.
|
|
|
| - * GDB translates all value from protocol representation to host
|
| - representation as needed. Datatypes are coerced into the host
|
| - types.
|
| + `l'
|
| + The OFFSET in the request is at the end of the data. There
|
| + is no more data to be read.
|
|
|
| - * GDB calls the system call.
|
| + `E00'
|
| + The request was malformed, or ANNEX was invalid.
|
|
|
| - * It then coerces datatypes back to protocol representation.
|
| + `E NN'
|
| + The offset was invalid, or there was an error encountered
|
| + reading the data. NN is a hex-encoded `errno' value.
|
|
|
| - * If the system call is expected to return data in buffer space
|
| - specified by pointer parameters to the call, the data is
|
| - transmitted to the target using a `M' or `X' packet. This packet
|
| - has to be expected by the target implementation and is handled as
|
| - any other `M' or `X' packet.
|
| + `'
|
| + An empty reply indicates the OBJECT string was not recognized
|
| + by the stub, or that the object does not support reading.
|
|
|
| +`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
|
| + Write uninterpreted bytes into the target's special data area
|
| + identified by the keyword OBJECT, starting at OFFSET bytes into
|
| + the data. DATA... is the binary-encoded data (*note Binary
|
| + Data::) to be written. The content and encoding of ANNEX is
|
| + specific to OBJECT; it can supply additional details about what
|
| + data to access.
|
|
|
| - Eventually GDB replies with another `F' packet which contains all
|
| -necessary information for the target to continue. This at least
|
| -contains
|
| + Here are the specific requests of this form defined so far. All
|
| + `qXfer:OBJECT:write:...' requests use the same reply formats,
|
| + listed below.
|
|
|
| - * Return value.
|
| + `qXfer:siginfo:write::OFFSET:DATA...'
|
| + Write DATA to the extra signal information on the target
|
| + system. The annex part of the generic `qXfer' packet must be
|
| + empty (*note qXfer write::).
|
|
|
| - * `errno', if has been changed by the system call.
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - * "Ctrl-C" flag.
|
| + `qXfer:spu:write:ANNEX:OFFSET:DATA...'
|
| + Write DATA to an `spufs' file on the target system. The
|
| + annex specifies which file to write; it must be of the form
|
| + `ID/NAME', where ID specifies an SPU context ID in the target
|
| + process, and NAME identifes the `spufs' file in that context
|
| + to be accessed.
|
|
|
| + This packet is not probed by default; the remote stub must
|
| + request it, by supplying an appropriate `qSupported' response
|
| + (*note qSupported::).
|
|
|
| - After having done the needed type and value coercion, the target
|
| -continues the latest continue or step action.
|
| + Reply:
|
| + `NN'
|
| + NN (hex encoded) is the number of bytes written. This may be
|
| + fewer bytes than supplied in the request.
|
|
|
| -
|
| -File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
| + `E00'
|
| + The request was malformed, or ANNEX was invalid.
|
|
|
| -E.13.3 The `F' Request Packet
|
| ------------------------------
|
| + `E NN'
|
| + The offset was invalid, or there was an error encountered
|
| + writing the data. NN is a hex-encoded `errno' value.
|
|
|
| -The `F' request packet has the following format:
|
| + `'
|
| + An empty reply indicates the OBJECT string was not recognized
|
| + by the stub, or that the object does not support writing.
|
|
|
| -`FCALL-ID,PARAMETER...'
|
| - CALL-ID is the identifier to indicate the host system call to be
|
| - called. This is just the name of the function.
|
| +`qXfer:OBJECT:OPERATION:...'
|
| + Requests of this form may be added in the future. When a stub does
|
| + not recognize the OBJECT keyword, or its support for OBJECT does
|
| + not recognize the OPERATION keyword, the stub must respond with an
|
| + empty packet.
|
|
|
| - PARAMETER... are the parameters to the system call. Parameters
|
| - are hexadecimal integer values, either the actual values in case
|
| - of scalar datatypes, pointers to target buffer space in case of
|
| - compound datatypes and unspecified memory areas, or pointer/length
|
| - pairs in case of string parameters. These are appended to the
|
| - CALL-ID as a comma-delimited list. All values are transmitted in
|
| - ASCII string representation, pointer/length pairs separated by a
|
| - slash.
|
| +`qAttached:PID'
|
| + Return an indication of whether the remote server attached to an
|
| + existing process or created a new process. When the multiprocess
|
| + protocol extensions are supported (*note multiprocess
|
| + extensions::), PID is an integer in hexadecimal format identifying
|
| + the target process. Otherwise, GDB will omit the PID field and
|
| + the query packet will be simplified as `qAttached'.
|
|
|
| + This query is used, for example, to know whether the remote process
|
| + should be detached or killed when a GDB session is ended with the
|
| + `quit' command.
|
|
|
| -
|
| -File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension
|
| + Reply:
|
| + `1'
|
| + The remote server attached to an existing process.
|
|
|
| -E.13.4 The `F' Reply Packet
|
| ----------------------------
|
| + `0'
|
| + The remote server created a new process.
|
|
|
| -The `F' reply packet has the following format:
|
| + `E NN'
|
| + A badly formed request or an error was encountered.
|
|
|
| -`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
|
| - RETCODE is the return code of the system call as hexadecimal value.
|
| +`Qbtrace:bts'
|
| + Enable branch tracing for the current thread using bts tracing.
|
|
|
| - ERRNO is the `errno' set by the call, in protocol-specific
|
| - representation. This parameter can be omitted if the call was
|
| - successful.
|
| + Reply:
|
| + `OK'
|
| + Branch tracing has been enabled.
|
|
|
| - CTRL-C FLAG is only sent if the user requested a break. In this
|
| - case, ERRNO must be sent as well, even if the call was successful.
|
| - The CTRL-C FLAG itself consists of the character `C':
|
| + `E.errtext'
|
| + A badly formed request or an error was encountered.
|
|
|
| - F0,0,C
|
| +`Qbtrace:off'
|
| + Disable branch tracing for the current thread.
|
|
|
| - or, if the call was interrupted before the host call has been
|
| - performed:
|
| + Reply:
|
| + `OK'
|
| + Branch tracing has been disabled.
|
|
|
| - F-1,4,C
|
| + `E.errtext'
|
| + A badly formed request or an error was encountered.
|
|
|
| - assuming 4 is the protocol-specific representation of `EINTR'.
|
|
|
| + ---------- Footnotes ----------
|
| +
|
| + (1) The `qP' and `qL' packets predate these conventions, and have
|
| +arguments without any terminator for the packet name; we suspect they
|
| +are in widespread use in places that are difficult to upgrade. The
|
| +`qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
|
| +are known to not check for the end of the packet.
|
|
|
|
|
| -File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
|
| +File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
|
|
|
| -E.13.5 The `Ctrl-C' Message
|
| ----------------------------
|
| +E.5 Architecture-Specific Protocol Details
|
| +==========================================
|
|
|
| -If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
|
| -Packet::), the target should behave as if it had gotten a break
|
| -message. The meaning for the target is "system call interrupted by
|
| -`SIGINT'". Consequentially, the target should actually stop (as with a
|
| -break message) and return to GDB with a `T02' packet.
|
| +This section describes how the remote protocol is applied to specific
|
| +target architectures. Also see *note Standard Target Features::, for
|
| +details of XML target descriptions for each architecture.
|
|
|
| - It's important for the target to know in which state the system call
|
| -was interrupted. There are two possible cases:
|
| +* Menu:
|
|
|
| - * The system call hasn't been performed on the host yet.
|
| +* ARM-Specific Protocol Details::
|
| +* MIPS-Specific Protocol Details::
|
|
|
| - * The system call on the host has been finished.
|
| +
|
| +File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details
|
|
|
| +E.5.1 ARM-specific Protocol Details
|
| +-----------------------------------
|
|
|
| - These two states can be distinguished by the target by the value of
|
| -the returned `errno'. If it's the protocol representation of `EINTR',
|
| -the system call hasn't been performed. This is equivalent to the
|
| -`EINTR' handling on POSIX systems. In any other case, the target may
|
| -presume that the system call has been finished -- successfully or not
|
| --- and should behave as if the break message arrived right after the
|
| -system call.
|
| +* Menu:
|
|
|
| - GDB must behave reliably. If the system call has not been called
|
| -yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
|
| -in the packet. If the system call on the host has been finished before
|
| -the user requests a break, the full action must be finished by GDB.
|
| -This requires sending `M' or `X' packets as necessary. The `F' packet
|
| -may only be sent when either nothing has happened or the full action
|
| -has been completed.
|
| +* ARM Breakpoint Kinds::
|
|
|
|
|
| -File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
|
| -
|
| -E.13.6 Console I/O
|
| -------------------
|
| +File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details
|
|
|
| -By default and if not explicitly closed by the target system, the file
|
| -descriptors 0, 1 and 2 are connected to the GDB console. Output on the
|
| -GDB console is handled as any other file output operation (`write(1,
|
| -...)' or `write(2, ...)'). Console input is handled by GDB so that
|
| -after the target read request from file descriptor 0 all following
|
| -typing is buffered until either one of the following conditions is met:
|
| +E.5.1.1 ARM Breakpoint Kinds
|
| +............................
|
|
|
| - * The user types `Ctrl-c'. The behaviour is as explained above, and
|
| - the `read' system call is treated as finished.
|
| +These breakpoint kinds are defined for the `Z0' and `Z1' packets.
|
|
|
| - * The user presses <RET>. This is treated as end of input with a
|
| - trailing newline.
|
| +2
|
| + 16-bit Thumb mode breakpoint.
|
|
|
| - * The user types `Ctrl-d'. This is treated as end of input. No
|
| - trailing character (neither newline nor `Ctrl-D') is appended to
|
| - the input.
|
| +3
|
| + 32-bit Thumb mode (Thumb-2) breakpoint.
|
|
|
| +4
|
| + 32-bit ARM mode breakpoint.
|
|
|
| - If the user has typed more characters than fit in the buffer given to
|
| -the `read' call, the trailing characters are buffered in GDB until
|
| -either another `read(0, ...)' is requested by the target, or debugging
|
| -is stopped at the user's request.
|
|
|
|
|
| -File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension
|
| +File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details
|
|
|
| -E.13.7 List of Supported Calls
|
| -------------------------------
|
| +E.5.2 MIPS-specific Protocol Details
|
| +------------------------------------
|
|
|
| * Menu:
|
|
|
| -* open::
|
| -* close::
|
| -* read::
|
| -* write::
|
| -* lseek::
|
| -* rename::
|
| -* unlink::
|
| -* stat/fstat::
|
| -* gettimeofday::
|
| -* isatty::
|
| -* system::
|
| +* MIPS Register packet Format::
|
| +* MIPS Breakpoint Kinds::
|
|
|
|
|
| -File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
|
| -
|
| -open
|
| -....
|
| -
|
| -Synopsis:
|
| - int open(const char *pathname, int flags);
|
| - int open(const char *pathname, int flags, mode_t mode);
|
| -
|
| -Request:
|
| - `Fopen,PATHPTR/LEN,FLAGS,MODE'
|
| +File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details
|
|
|
| - FLAGS is the bitwise `OR' of the following values:
|
| +E.5.2.1 MIPS Register Packet Format
|
| +...................................
|
|
|
| - `O_CREAT'
|
| - If the file does not exist it will be created. The host
|
| - rules apply as far as file ownership and time stamps are
|
| - concerned.
|
| +The following `g'/`G' packets have previously been defined. In the
|
| +below, some thirty-two bit registers are transferred as sixty-four
|
| +bits. Those registers should be zero/sign extended (which?) to fill
|
| +the space allocated. Register bytes are transferred in target byte
|
| +order. The two nibbles within a register byte are transferred
|
| +most-significant - least-significant.
|
|
|
| - `O_EXCL'
|
| - When used with `O_CREAT', if the file already exists it is an
|
| - error and open() fails.
|
| +MIPS32
|
| + All registers are transferred as thirty-two bit quantities in the
|
| + order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
|
| + floating-point registers; fsr; fir; fp.
|
|
|
| - `O_TRUNC'
|
| - If the file already exists and the open mode allows writing
|
| - (`O_RDWR' or `O_WRONLY' is given) it will be truncated to
|
| - zero length.
|
| +MIPS64
|
| + All registers are transferred as sixty-four bit quantities
|
| + (including thirty-two bit registers such as `sr'). The ordering
|
| + is the same as `MIPS32'.
|
|
|
| - `O_APPEND'
|
| - The file is opened in append mode.
|
|
|
| - `O_RDONLY'
|
| - The file is opened for reading only.
|
| +
|
| +File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details
|
|
|
| - `O_WRONLY'
|
| - The file is opened for writing only.
|
| +E.5.2.2 MIPS Breakpoint Kinds
|
| +.............................
|
|
|
| - `O_RDWR'
|
| - The file is opened for reading and writing.
|
| +These breakpoint kinds are defined for the `Z0' and `Z1' packets.
|
|
|
| - Other bits are silently ignored.
|
| +2
|
| + 16-bit MIPS16 mode breakpoint.
|
|
|
| - MODE is the bitwise `OR' of the following values:
|
| +3
|
| + 16-bit microMIPS mode breakpoint.
|
|
|
| - `S_IRUSR'
|
| - User has read permission.
|
| +4
|
| + 32-bit standard MIPS mode breakpoint.
|
|
|
| - `S_IWUSR'
|
| - User has write permission.
|
| +5
|
| + 32-bit microMIPS mode breakpoint.
|
|
|
| - `S_IRGRP'
|
| - Group has read permission.
|
|
|
| - `S_IWGRP'
|
| - Group has write permission.
|
| +
|
| +File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol
|
|
|
| - `S_IROTH'
|
| - Others have read permission.
|
| +E.6 Tracepoint Packets
|
| +======================
|
|
|
| - `S_IWOTH'
|
| - Others have write permission.
|
| +Here we describe the packets GDB uses to implement tracepoints (*note
|
| +Tracepoints::).
|
|
|
| - Other bits are silently ignored.
|
| +`QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
|
| + Create a new tracepoint, number N, at ADDR. If ENA is `E', then
|
| + the tracepoint is enabled; if it is `D', then the tracepoint is
|
| + disabled. STEP is the tracepoint's step count, and PASS is its
|
| + pass count. If an `F' is present, then the tracepoint is to be a
|
| + fast tracepoint, and the FLEN is the number of bytes that the
|
| + target should copy elsewhere to make room for the tracepoint. If
|
| + an `X' is present, it introduces a tracepoint condition, which
|
| + consists of a hexadecimal length, followed by a comma and
|
| + hex-encoded bytes, in a manner similar to action encodings as
|
| + described below. If the trailing `-' is present, further `QTDP'
|
| + packets will follow to specify this tracepoint's actions.
|
|
|
| -Return value:
|
| - `open' returns the new file descriptor or -1 if an error occurred.
|
| + Replies:
|
| + `OK'
|
| + The packet was understood and carried out.
|
|
|
| -Errors:
|
| + `qRelocInsn'
|
| + *Note Relocate instruction reply packet: Tracepoint Packets.
|
|
|
| - `EEXIST'
|
| - PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
|
| + `'
|
| + The packet was not recognized.
|
|
|
| - `EISDIR'
|
| - PATHNAME refers to a directory.
|
| +`QTDP:-N:ADDR:[S]ACTION...[-]'
|
| + Define actions to be taken when a tracepoint is hit. N and ADDR
|
| + must be the same as in the initial `QTDP' packet for this
|
| + tracepoint. This packet may only be sent immediately after
|
| + another `QTDP' packet that ended with a `-'. If the trailing `-'
|
| + is present, further `QTDP' packets will follow, specifying more
|
| + actions for this tracepoint.
|
|
|
| - `EACCES'
|
| - The requested access is not allowed.
|
| + In the series of action packets for a given tracepoint, at most one
|
| + can have an `S' before its first ACTION. If such a packet is
|
| + sent, it and the following packets define "while-stepping"
|
| + actions. Any prior packets define ordinary actions -- that is,
|
| + those taken when the tracepoint is first hit. If no action packet
|
| + has an `S', then all the packets in the series specify ordinary
|
| + tracepoint actions.
|
|
|
| - `ENAMETOOLONG'
|
| - PATHNAME was too long.
|
| + The `ACTION...' portion of the packet is a series of actions,
|
| + concatenated without separators. Each action has one of the
|
| + following forms:
|
|
|
| - `ENOENT'
|
| - A directory component in PATHNAME does not exist.
|
| + `R MASK'
|
| + Collect the registers whose bits are set in MASK. MASK is a
|
| + hexadecimal number whose I'th bit is set if register number I
|
| + should be collected. (The least significant bit is numbered
|
| + zero.) Note that MASK may be any number of digits long; it
|
| + may not fit in a 32-bit word.
|
|
|
| - `ENODEV'
|
| - PATHNAME refers to a device, pipe, named pipe or socket.
|
| + `M BASEREG,OFFSET,LEN'
|
| + Collect LEN bytes of memory starting at the address in
|
| + register number BASEREG, plus OFFSET. If BASEREG is `-1',
|
| + then the range has a fixed address: OFFSET is the address of
|
| + the lowest byte to collect. The BASEREG, OFFSET, and LEN
|
| + parameters are all unsigned hexadecimal values (the `-1'
|
| + value for BASEREG is a special case).
|
|
|
| - `EROFS'
|
| - PATHNAME refers to a file on a read-only filesystem and write
|
| - access was requested.
|
| + `X LEN,EXPR'
|
| + Evaluate EXPR, whose length is LEN, and collect memory as it
|
| + directs. EXPR is an agent expression, as described in *note
|
| + Agent Expressions::. Each byte of the expression is encoded
|
| + as a two-digit hex number in the packet; LEN is the number of
|
| + bytes in the expression (and thus one-half the number of hex
|
| + digits in the packet).
|
|
|
| - `EFAULT'
|
| - PATHNAME is an invalid pointer value.
|
|
|
| - `ENOSPC'
|
| - No space on device to create the file.
|
| + Any number of actions may be packed together in a single `QTDP'
|
| + packet, as long as the packet does not exceed the maximum packet
|
| + length (400 bytes, for many stubs). There may be only one `R'
|
| + action per tracepoint, and it must precede any `M' or `X' actions.
|
| + Any registers referred to by `M' and `X' actions must be collected
|
| + by a preceding `R' action. (The "while-stepping" actions are
|
| + treated as if they were attached to a separate tracepoint, as far
|
| + as these restrictions are concerned.)
|
|
|
| - `EMFILE'
|
| - The process already has the maximum number of files open.
|
| + Replies:
|
| + `OK'
|
| + The packet was understood and carried out.
|
|
|
| - `ENFILE'
|
| - The limit on the total number of files open on the system has
|
| - been reached.
|
| + `qRelocInsn'
|
| + *Note Relocate instruction reply packet: Tracepoint Packets.
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| + `'
|
| + The packet was not recognized.
|
|
|
| +`QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES'
|
| + Specify a source string of tracepoint N at address ADDR. This is
|
| + useful to get accurate reproduction of the tracepoints originally
|
| + downloaded at the beginning of the trace run. TYPE is the name of
|
| + the tracepoint part, such as `cond' for the tracepoint's
|
| + conditional expression (see below for a list of types), while
|
| + BYTES is the string, encoded in hexadecimal.
|
|
|
| -
|
| -File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
|
| + START is the offset of the BYTES within the overall source string,
|
| + while SLEN is the total length of the source string. This is
|
| + intended for handling source strings that are longer than will fit
|
| + in a single packet.
|
|
|
| -close
|
| -.....
|
| + The available string types are `at' for the location, `cond' for
|
| + the conditional, and `cmd' for an action command. GDB sends a
|
| + separate packet for each command in the action list, in the same
|
| + order in which the commands are stored in the list.
|
|
|
| -Synopsis:
|
| - int close(int fd);
|
| + The target does not need to do anything with source strings except
|
| + report them back as part of the replies to the `qTfP'/`qTsP' query
|
| + packets.
|
|
|
| -Request:
|
| - `Fclose,FD'
|
| + Although this packet is optional, and GDB will only send it if the
|
| + target replies with `TracepointSource' *Note General Query
|
| + Packets::, it makes both disconnected tracing and trace files much
|
| + easier to use. Otherwise the user must be careful that the
|
| + tracepoints in effect while looking at trace frames are identical
|
| + to the ones in effect during the trace run; even a small
|
| + discrepancy could cause `tdump' not to work, or a particular trace
|
| + frame not be found.
|
|
|
| -Return value:
|
| - `close' returns zero on success, or -1 if an error occurred.
|
| +`QTDV:N:VALUE'
|
| + Create a new trace state variable, number N, with an initial value
|
| + of VALUE, which is a 64-bit signed integer. Both N and VALUE are
|
| + encoded as hexadecimal values. GDB has the option of not using
|
| + this packet for initial values of zero; the target should simply
|
| + create the trace state variables as they are mentioned in
|
| + expressions.
|
|
|
| -Errors:
|
| +`QTFrame:N'
|
| + Select the N'th tracepoint frame from the buffer, and use the
|
| + register and memory contents recorded there to answer subsequent
|
| + request packets from GDB.
|
|
|
| - `EBADF'
|
| - FD isn't a valid open file descriptor.
|
| + A successful reply from the stub indicates that the stub has found
|
| + the requested frame. The response is a series of parts,
|
| + concatenated without separators, describing the frame we selected.
|
| + Each part has one of the following forms:
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| + `F F'
|
| + The selected frame is number N in the trace frame buffer; F
|
| + is a hexadecimal number. If F is `-1', then there was no
|
| + frame matching the criteria in the request packet.
|
|
|
| + `T T'
|
| + The selected trace frame records a hit of tracepoint number T;
|
| + T is a hexadecimal number.
|
|
|
| -
|
| -File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
|
|
|
| -read
|
| -....
|
| +`QTFrame:pc:ADDR'
|
| + Like `QTFrame:N', but select the first tracepoint frame after the
|
| + currently selected frame whose PC is ADDR; ADDR is a hexadecimal
|
| + number.
|
|
|
| -Synopsis:
|
| - int read(int fd, void *buf, unsigned int count);
|
| +`QTFrame:tdp:T'
|
| + Like `QTFrame:N', but select the first tracepoint frame after the
|
| + currently selected frame that is a hit of tracepoint T; T is a
|
| + hexadecimal number.
|
|
|
| -Request:
|
| - `Fread,FD,BUFPTR,COUNT'
|
| +`QTFrame:range:START:END'
|
| + Like `QTFrame:N', but select the first tracepoint frame after the
|
| + currently selected frame whose PC is between START (inclusive) and
|
| + END (inclusive); START and END are hexadecimal numbers.
|
|
|
| -Return value:
|
| - On success, the number of bytes read is returned. Zero indicates
|
| - end of file. If count is zero, read returns zero as well. On
|
| - error, -1 is returned.
|
| +`QTFrame:outside:START:END'
|
| + Like `QTFrame:range:START:END', but select the first frame
|
| + _outside_ the given range of addresses (exclusive).
|
|
|
| -Errors:
|
| +`qTMinFTPILen'
|
| + This packet requests the minimum length of instruction at which a
|
| + fast tracepoint (*note Set Tracepoints::) may be placed. For
|
| + instance, on the 32-bit x86 architecture, it is possible to use a
|
| + 4-byte jump, but it depends on the target system being able to
|
| + create trampolines in the first 64K of memory, which might or
|
| + might not be possible for that system. So the reply to this
|
| + packet will be 4 if it is able to arrange for that.
|
|
|
| - `EBADF'
|
| - FD is not a valid file descriptor or is not open for reading.
|
| + Replies:
|
|
|
| - `EFAULT'
|
| - BUFPTR is an invalid pointer value.
|
| + `0'
|
| + The minimum instruction length is currently unknown.
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| + `LENGTH'
|
| + The minimum instruction length is LENGTH, where LENGTH is
|
| + greater or equal to 1. LENGTH is a hexadecimal number. A
|
| + reply of 1 means that a fast tracepoint may be placed on any
|
| + instruction regardless of size.
|
|
|
| + `E'
|
| + An error has occurred.
|
|
|
| -
|
| -File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
|
| + `'
|
| + An empty reply indicates that the request is not supported by
|
| + the stub.
|
|
|
| -write
|
| -.....
|
| +`QTStart'
|
| + Begin the tracepoint experiment. Begin collecting data from
|
| + tracepoint hits in the trace frame buffer. This packet supports
|
| + the `qRelocInsn' reply (*note Relocate instruction reply packet:
|
| + Tracepoint Packets.).
|
|
|
| -Synopsis:
|
| - int write(int fd, const void *buf, unsigned int count);
|
| +`QTStop'
|
| + End the tracepoint experiment. Stop collecting trace frames.
|
|
|
| -Request:
|
| - `Fwrite,FD,BUFPTR,COUNT'
|
| +`QTEnable:N:ADDR'
|
| + Enable tracepoint N at address ADDR in a started tracepoint
|
| + experiment. If the tracepoint was previously disabled, then
|
| + collection of data from it will resume.
|
|
|
| -Return value:
|
| - On success, the number of bytes written are returned. Zero
|
| - indicates nothing was written. On error, -1 is returned.
|
| +`QTDisable:N:ADDR'
|
| + Disable tracepoint N at address ADDR in a started tracepoint
|
| + experiment. No more data will be collected from the tracepoint
|
| + unless `QTEnable:N:ADDR' is subsequently issued.
|
|
|
| -Errors:
|
| +`QTinit'
|
| + Clear the table of tracepoints, and empty the trace frame buffer.
|
|
|
| - `EBADF'
|
| - FD is not a valid file descriptor or is not open for writing.
|
| +`QTro:START1,END1:START2,END2:...'
|
| + Establish the given ranges of memory as "transparent". The stub
|
| + will answer requests for these ranges from memory's current
|
| + contents, if they were not collected as part of the tracepoint hit.
|
|
|
| - `EFAULT'
|
| - BUFPTR is an invalid pointer value.
|
| + GDB uses this to mark read-only regions of memory, like those
|
| + containing program code. Since these areas never change, they
|
| + should still have the same contents they did when the tracepoint
|
| + was hit, so there's no reason for the stub to refuse to provide
|
| + their contents.
|
|
|
| - `EFBIG'
|
| - An attempt was made to write a file that exceeds the
|
| - host-specific maximum file size allowed.
|
| +`QTDisconnected:VALUE'
|
| + Set the choice to what to do with the tracing run when GDB
|
| + disconnects from the target. A VALUE of 1 directs the target to
|
| + continue the tracing run, while 0 tells the target to stop tracing
|
| + if GDB is no longer in the picture.
|
|
|
| - `ENOSPC'
|
| - No space on device to write the data.
|
| +`qTStatus'
|
| + Ask the stub if there is a trace experiment running right now.
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| + The reply has the form:
|
|
|
| + `TRUNNING[;FIELD]...'
|
| + RUNNING is a single digit `1' if the trace is presently
|
| + running, or `0' if not. It is followed by semicolon-separated
|
| + optional fields that an agent may use to report additional
|
| + status.
|
|
|
| -
|
| -File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
|
|
|
| -lseek
|
| -.....
|
| + If the trace is not running, the agent may report any of several
|
| + explanations as one of the optional fields:
|
|
|
| -Synopsis:
|
| - long lseek (int fd, long offset, int flag);
|
| + `tnotrun:0'
|
| + No trace has been run yet.
|
|
|
| -Request:
|
| - `Flseek,FD,OFFSET,FLAG'
|
| + `tstop[:TEXT]:0'
|
| + The trace was stopped by a user-originated stop command. The
|
| + optional TEXT field is a user-supplied string supplied as
|
| + part of the stop command (for instance, an explanation of why
|
| + the trace was stopped manually). It is hex-encoded.
|
|
|
| - FLAG is one of:
|
| + `tfull:0'
|
| + The trace stopped because the trace buffer filled up.
|
|
|
| - `SEEK_SET'
|
| - The offset is set to OFFSET bytes.
|
| + `tdisconnected:0'
|
| + The trace stopped because GDB disconnected from the target.
|
|
|
| - `SEEK_CUR'
|
| - The offset is set to its current location plus OFFSET bytes.
|
| + `tpasscount:TPNUM'
|
| + The trace stopped because tracepoint TPNUM exceeded its pass
|
| + count.
|
|
|
| - `SEEK_END'
|
| - The offset is set to the size of the file plus OFFSET bytes.
|
| + `terror:TEXT:TPNUM'
|
| + The trace stopped because tracepoint TPNUM had an error. The
|
| + string TEXT is available to describe the nature of the error
|
| + (for instance, a divide by zero in the condition expression).
|
| + TEXT is hex encoded.
|
|
|
| -Return value:
|
| - On success, the resulting unsigned offset in bytes from the
|
| - beginning of the file is returned. Otherwise, a value of -1 is
|
| - returned.
|
| + `tunknown:0'
|
| + The trace stopped for some other reason.
|
|
|
| -Errors:
|
|
|
| - `EBADF'
|
| - FD is not a valid open file descriptor.
|
| + Additional optional fields supply statistical and other
|
| + information. Although not required, they are extremely useful for
|
| + users monitoring the progress of a trace run. If a trace has
|
| + stopped, and these numbers are reported, they must reflect the
|
| + state of the just-stopped trace.
|
|
|
| - `ESPIPE'
|
| - FD is associated with the GDB console.
|
| + `tframes:N'
|
| + The number of trace frames in the buffer.
|
|
|
| - `EINVAL'
|
| - FLAG is not a proper value.
|
| + `tcreated:N'
|
| + The total number of trace frames created during the run. This
|
| + may be larger than the trace frame count, if the buffer is
|
| + circular.
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| + `tsize:N'
|
| + The total size of the trace buffer, in bytes.
|
|
|
| + `tfree:N'
|
| + The number of bytes still unused in the buffer.
|
|
|
| -
|
| -File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
|
| + `circular:N'
|
| + The value of the circular trace buffer flag. `1' means that
|
| + the trace buffer is circular and old trace frames will be
|
| + discarded if necessary to make room, `0' means that the trace
|
| + buffer is linear and may fill up.
|
|
|
| -rename
|
| -......
|
| + `disconn:N'
|
| + The value of the disconnected tracing flag. `1' means that
|
| + tracing will continue after GDB disconnects, `0' means that
|
| + the trace run will stop.
|
|
|
| -Synopsis:
|
| - int rename(const char *oldpath, const char *newpath);
|
|
|
| -Request:
|
| - `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
|
| +`qTP:TP:ADDR'
|
| + Ask the stub for the current state of tracepoint number TP at
|
| + address ADDR.
|
|
|
| -Return value:
|
| - On success, zero is returned. On error, -1 is returned.
|
| + Replies:
|
| + `VHITS:USAGE'
|
| + The tracepoint has been hit HITS times so far during the trace
|
| + run, and accounts for USAGE in the trace buffer. Note that
|
| + `while-stepping' steps are not counted as separate hits, but
|
| + the steps' space consumption is added into the usage number.
|
|
|
| -Errors:
|
|
|
| - `EISDIR'
|
| - NEWPATH is an existing directory, but OLDPATH is not a
|
| - directory.
|
| +`qTV:VAR'
|
| + Ask the stub for the value of the trace state variable number VAR.
|
|
|
| - `EEXIST'
|
| - NEWPATH is a non-empty directory.
|
| + Replies:
|
| + `VVALUE'
|
| + The value of the variable is VALUE. This will be the current
|
| + value of the variable if the user is examining a running
|
| + target, or a saved value if the variable was collected in the
|
| + trace frame that the user is looking at. Note that multiple
|
| + requests may result in different reply values, such as when
|
| + requesting values while the program is running.
|
|
|
| - `EBUSY'
|
| - OLDPATH or NEWPATH is a directory that is in use by some
|
| - process.
|
| + `U'
|
| + The value of the variable is unknown. This would occur, for
|
| + example, if the user is examining a trace frame in which the
|
| + requested variable was not collected.
|
|
|
| - `EINVAL'
|
| - An attempt was made to make a directory a subdirectory of
|
| - itself.
|
| +`qTfP'
|
| +`qTsP'
|
| + These packets request data about tracepoints that are being used by
|
| + the target. GDB sends `qTfP' to get the first piece of data, and
|
| + multiple `qTsP' to get additional pieces. Replies to these
|
| + packets generally take the form of the `QTDP' packets that define
|
| + tracepoints. (FIXME add detailed syntax)
|
|
|
| - `ENOTDIR'
|
| - A component used as a directory in OLDPATH or new path is
|
| - not a directory. Or OLDPATH is a directory and NEWPATH
|
| - exists but is not a directory.
|
| +`qTfV'
|
| +`qTsV'
|
| + These packets request data about trace state variables that are on
|
| + the target. GDB sends `qTfV' to get the first vari of data, and
|
| + multiple `qTsV' to get additional variables. Replies to these
|
| + packets follow the syntax of the `QTDV' packets that define trace
|
| + state variables.
|
|
|
| - `EFAULT'
|
| - OLDPATHPTR or NEWPATHPTR are invalid pointer values.
|
| +`qTfSTM'
|
| +`qTsSTM'
|
| + These packets request data about static tracepoint markers that
|
| + exist in the target program. GDB sends `qTfSTM' to get the first
|
| + piece of data, and multiple `qTsSTM' to get additional pieces.
|
| + Replies to these packets take the following form:
|
|
|
| - `EACCES'
|
| - No access to the file or the path of the file.
|
| + Reply:
|
| + `m ADDRESS:ID:EXTRA'
|
| + A single marker
|
|
|
| - `ENAMETOOLONG'
|
| - OLDPATH or NEWPATH was too long.
|
| + `m ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...'
|
| + a comma-separated list of markers
|
|
|
| - `ENOENT'
|
| - A directory component in OLDPATH or NEWPATH does not exist.
|
| + `l'
|
| + (lower case letter `L') denotes end of list.
|
|
|
| - `EROFS'
|
| - The file is on a read-only filesystem.
|
| + `E NN'
|
| + An error occurred. NN are hex digits.
|
| +
|
| + `'
|
| + An empty reply indicates that the request is not supported by
|
| + the stub.
|
|
|
| - `ENOSPC'
|
| - The device containing the file has no room for the new
|
| - directory entry.
|
| + ADDRESS is encoded in hex. ID and EXTRA are strings encoded in
|
| + hex.
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| + In response to each query, the target will reply with a list of
|
| + one or more markers, separated by commas. GDB will respond to each
|
| + reply with a request for more markers (using the `qs' form of the
|
| + query), until the target responds with `l' (lower-case ell, for
|
| + "last").
|
|
|
| +`qTSTMat:ADDRESS'
|
| + This packets requests data about static tracepoint markers in the
|
| + target program at ADDRESS. Replies to this packet follow the
|
| + syntax of the `qTfSTM' and `qTsSTM' packets that list static
|
| + tracepoint markers.
|
|
|
| -
|
| -File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
|
| +`QTSave:FILENAME'
|
| + This packet directs the target to save trace data to the file name
|
| + FILENAME in the target's filesystem. FILENAME is encoded as a hex
|
| + string; the interpretation of the file name (relative vs absolute,
|
| + wild cards, etc) is up to the target.
|
|
|
| -unlink
|
| -......
|
| +`qTBuffer:OFFSET,LEN'
|
| + Return up to LEN bytes of the current contents of trace buffer,
|
| + starting at OFFSET. The trace buffer is treated as if it were a
|
| + contiguous collection of traceframes, as per the trace file format.
|
| + The reply consists as many hex-encoded bytes as the target can
|
| + deliver in a packet; it is not an error to return fewer than were
|
| + asked for. A reply consisting of just `l' indicates that no bytes
|
| + are available.
|
|
|
| -Synopsis:
|
| - int unlink(const char *pathname);
|
| +`QTBuffer:circular:VALUE'
|
| + This packet directs the target to use a circular trace buffer if
|
| + VALUE is 1, or a linear buffer if the value is 0.
|
|
|
| -Request:
|
| - `Funlink,PATHNAMEPTR/LEN'
|
| +`QTBuffer:size:SIZE'
|
| + This packet directs the target to make the trace buffer be of size
|
| + SIZE if possible. A value of `-1' tells the target to use
|
| + whatever size it prefers.
|
|
|
| -Return value:
|
| - On success, zero is returned. On error, -1 is returned.
|
| +`QTNotes:[TYPE:TEXT][;TYPE:TEXT]...'
|
| + This packet adds optional textual notes to the trace run.
|
| + Allowable types include `user', `notes', and `tstop', the TEXT
|
| + fields are arbitrary strings, hex-encoded.
|
|
|
| -Errors:
|
|
|
| - `EACCES'
|
| - No access to the file or the path of the file.
|
| +E.6.1 Relocate instruction reply packet
|
| +---------------------------------------
|
|
|
| - `EPERM'
|
| - The system does not allow unlinking of directories.
|
| +When installing fast tracepoints in memory, the target may need to
|
| +relocate the instruction currently at the tracepoint address to a
|
| +different address in memory. For most instructions, a simple copy is
|
| +enough, but, for example, call instructions that implicitly push the
|
| +return address on the stack, and relative branches or other PC-relative
|
| +instructions require offset adjustment, so that the effect of executing
|
| +the instruction at a different address is the same as if it had
|
| +executed in the original location.
|
|
|
| - `EBUSY'
|
| - The file PATHNAME cannot be unlinked because it's being used
|
| - by another process.
|
| + In response to several of the tracepoint packets, the target may also
|
| +respond with a number of intermediate `qRelocInsn' request packets
|
| +before the final result packet, to have GDB handle this relocation
|
| +operation. If a packet supports this mechanism, its documentation will
|
| +explicitly say so. See for example the above descriptions for the
|
| +`QTStart' and `QTDP' packets. The format of the request is:
|
|
|
| - `EFAULT'
|
| - PATHNAMEPTR is an invalid pointer value.
|
| +`qRelocInsn:FROM;TO'
|
| + This requests GDB to copy instruction at address FROM to address
|
| + TO, possibly adjusted so that executing the instruction at TO has
|
| + the same effect as executing it at FROM. GDB writes the adjusted
|
| + instruction to target memory starting at TO.
|
|
|
| - `ENAMETOOLONG'
|
| - PATHNAME was too long.
|
| + Replies:
|
| +`qRelocInsn:ADJUSTED_SIZE'
|
| + Informs the stub the relocation is complete. ADJUSTED_SIZE is the
|
| + length in bytes of resulting relocated instruction sequence.
|
|
|
| - `ENOENT'
|
| - A directory component in PATHNAME does not exist.
|
| +`E NN'
|
| + A badly formed request was detected, or an error was encountered
|
| + while relocating the instruction.
|
|
|
| - `ENOTDIR'
|
| - A component of the path is not a directory.
|
| +
|
| +File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
|
|
|
| - `EROFS'
|
| - The file is on a read-only filesystem.
|
| +E.7 Host I/O Packets
|
| +====================
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| +The "Host I/O" packets allow GDB to perform I/O operations on the far
|
| +side of a remote link. For example, Host I/O is used to upload and
|
| +download files to a remote target with its own filesystem. Host I/O
|
| +uses the same constant values and data structure layout as the
|
| +target-initiated File-I/O protocol. However, the Host I/O packets are
|
| +structured differently. The target-initiated protocol relies on target
|
| +memory to store parameters and buffers. Host I/O requests are
|
| +initiated by GDB, and the target's memory is not involved. *Note
|
| +File-I/O Remote Protocol Extension::, for more details on the
|
| +target-initiated protocol.
|
|
|
| + The Host I/O request packets all encode a single operation along with
|
| +its arguments. They have this format:
|
|
|
| -
|
| -File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
|
| +`vFile:OPERATION: PARAMETER...'
|
| + OPERATION is the name of the particular request; the target should
|
| + compare the entire packet name up to the second colon when checking
|
| + for a supported operation. The format of PARAMETER depends on the
|
| + operation. Numbers are always passed in hexadecimal. Negative
|
| + numbers have an explicit minus sign (i.e. two's complement is not
|
| + used). Strings (e.g. filenames) are encoded as a series of
|
| + hexadecimal bytes. The last argument to a system call may be a
|
| + buffer of escaped binary data (*note Binary Data::).
|
|
|
| -stat/fstat
|
| -..........
|
|
|
| -Synopsis:
|
| - int stat(const char *pathname, struct stat *buf);
|
| - int fstat(int fd, struct stat *buf);
|
| + The valid responses to Host I/O packets are:
|
|
|
| -Request:
|
| - `Fstat,PATHNAMEPTR/LEN,BUFPTR'
|
| - `Ffstat,FD,BUFPTR'
|
| +`F RESULT [, ERRNO] [; ATTACHMENT]'
|
| + RESULT is the integer value returned by this operation, usually
|
| + non-negative for success and -1 for errors. If an error has
|
| + occured, ERRNO will be included in the result. ERRNO will have a
|
| + value defined by the File-I/O protocol (*note Errno Values::). For
|
| + operations which return data, ATTACHMENT supplies the data as a
|
| + binary buffer. Binary buffers in response packets are escaped in
|
| + the normal way (*note Binary Data::). See the individual packet
|
| + documentation for the interpretation of RESULT and ATTACHMENT.
|
|
|
| -Return value:
|
| - On success, zero is returned. On error, -1 is returned.
|
| +`'
|
| + An empty response indicates that this operation is not recognized.
|
|
|
| -Errors:
|
|
|
| - `EBADF'
|
| - FD is not a valid open file.
|
| + These are the supported Host I/O operations:
|
|
|
| - `ENOENT'
|
| - A directory component in PATHNAME does not exist or the path
|
| - is an empty string.
|
| +`vFile:open: PATHNAME, FLAGS, MODE'
|
| + Open a file at PATHNAME and return a file descriptor for it, or
|
| + return -1 if an error occurs. PATHNAME is a string, FLAGS is an
|
| + integer indicating a mask of open flags (*note Open Flags::), and
|
| + MODE is an integer indicating a mask of mode bits to use if the
|
| + file is created (*note mode_t Values::). *Note open::, for
|
| + details of the open flags and mode values.
|
|
|
| - `ENOTDIR'
|
| - A component of the path is not a directory.
|
| +`vFile:close: FD'
|
| + Close the open file corresponding to FD and return 0, or -1 if an
|
| + error occurs.
|
|
|
| - `EFAULT'
|
| - PATHNAMEPTR is an invalid pointer value.
|
| +`vFile:pread: FD, COUNT, OFFSET'
|
| + Read data from the open file corresponding to FD. Up to COUNT
|
| + bytes will be read from the file, starting at OFFSET relative to
|
| + the start of the file. The target may read fewer bytes; common
|
| + reasons include packet size limits and an end-of-file condition.
|
| + The number of bytes read is returned. Zero should only be
|
| + returned for a successful read at the end of the file, or if COUNT
|
| + was zero.
|
|
|
| - `EACCES'
|
| - No access to the file or the path of the file.
|
| + The data read should be returned as a binary attachment on success.
|
| + If zero bytes were read, the response should include an empty
|
| + binary attachment (i.e. a trailing semicolon). The return value
|
| + is the number of target bytes read; the binary attachment may be
|
| + longer if some characters were escaped.
|
|
|
| - `ENAMETOOLONG'
|
| - PATHNAME was too long.
|
| +`vFile:pwrite: FD, OFFSET, DATA'
|
| + Write DATA (a binary buffer) to the open file corresponding to FD.
|
| + Start the write at OFFSET from the start of the file. Unlike many
|
| + `write' system calls, there is no separate COUNT argument; the
|
| + length of DATA in the packet is used. `vFile:write' returns the
|
| + number of bytes written, which may be shorter than the length of
|
| + DATA, or -1 if an error occurred.
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| +`vFile:unlink: PATHNAME'
|
| + Delete the file at PATHNAME on the target. Return 0, or -1 if an
|
| + error occurs. PATHNAME is a string.
|
|
|
| +`vFile:readlink: FILENAME'
|
| + Read value of symbolic link FILENAME on the target. Return the
|
| + number of bytes read, or -1 if an error occurs.
|
|
|
| -
|
| -File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
|
| + The data read should be returned as a binary attachment on success.
|
| + If zero bytes were read, the response should include an empty
|
| + binary attachment (i.e. a trailing semicolon). The return value
|
| + is the number of target bytes read; the binary attachment may be
|
| + longer if some characters were escaped.
|
|
|
| -gettimeofday
|
| -............
|
|
|
| -Synopsis:
|
| - int gettimeofday(struct timeval *tv, void *tz);
|
| +
|
| +File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol
|
|
|
| -Request:
|
| - `Fgettimeofday,TVPTR,TZPTR'
|
| +E.8 Interrupts
|
| +==============
|
|
|
| -Return value:
|
| - On success, 0 is returned, -1 otherwise.
|
| +When a program on the remote target is running, GDB may attempt to
|
| +interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by
|
| +`g', control of which is specified via GDB's `interrupt-sequence'.
|
|
|
| -Errors:
|
| + The precise meaning of `BREAK' is defined by the transport mechanism
|
| +and may, in fact, be undefined. GDB does not currently define a
|
| +`BREAK' mechanism for any of the network interfaces except for TCP, in
|
| +which case GDB sends the `telnet' BREAK sequence.
|
|
|
| - `EINVAL'
|
| - TZ is a non-NULL pointer.
|
| + `Ctrl-C', on the other hand, is defined and implemented for all
|
| +transport mechanisms. It is represented by sending the single byte
|
| +`0x03' without any of the usual packet overhead described in the
|
| +Overview section (*note Overview::). When a `0x03' byte is transmitted
|
| +as part of a packet, it is considered to be packet data and does _not_
|
| +represent an interrupt. E.g., an `X' packet (*note X packet::), used
|
| +for binary downloads, may include an unescaped `0x03' as part of its
|
| +packet.
|
|
|
| - `EFAULT'
|
| - TVPTR and/or TZPTR is an invalid pointer value.
|
| + `BREAK' followed by `g' is also known as Magic SysRq g. When Linux
|
| +kernel receives this sequence from serial port, it stops execution and
|
| +connects to gdb.
|
|
|
| + Stubs are not required to recognize these interrupt mechanisms and
|
| +the precise meaning associated with receipt of the interrupt is
|
| +implementation defined. If the target supports debugging of multiple
|
| +threads and/or processes, it should attempt to interrupt all
|
| +currently-executing threads and processes. If the stub is successful
|
| +at interrupting the running program, it should send one of the stop
|
| +reply packets (*note Stop Reply Packets::) to GDB as a result of
|
| +successfully stopping the program in all-stop mode, and a stop reply
|
| +for each stopped thread in non-stop mode. Interrupts received while the
|
| +program is stopped are discarded.
|
|
|
|
|
| -File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
|
| +File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol
|
|
|
| -isatty
|
| -......
|
| +E.9 Notification Packets
|
| +========================
|
| +
|
| +The GDB remote serial protocol includes "notifications", packets that
|
| +require no acknowledgment. Both the GDB and the stub may send
|
| +notifications (although the only notifications defined at present are
|
| +sent by the stub). Notifications carry information without incurring
|
| +the round-trip latency of an acknowledgment, and so are useful for
|
| +low-impact communications where occasional packet loss is not a problem.
|
|
|
| -Synopsis:
|
| - int isatty(int fd);
|
| + A notification packet has the form `% DATA # CHECKSUM', where DATA
|
| +is the content of the notification, and CHECKSUM is a checksum of DATA,
|
| +computed and formatted as for ordinary GDB packets. A notification's
|
| +DATA never contains `$', `%' or `#' characters. Upon receiving a
|
| +notification, the recipient sends no `+' or `-' to acknowledge the
|
| +notification's receipt or to report its corruption.
|
|
|
| -Request:
|
| - `Fisatty,FD'
|
| + Every notification's DATA begins with a name, which contains no
|
| +colon characters, followed by a colon character.
|
|
|
| -Return value:
|
| - Returns 1 if FD refers to the GDB console, 0 otherwise.
|
| + Recipients should silently ignore corrupted notifications and
|
| +notifications they do not understand. Recipients should restart
|
| +timeout periods on receipt of a well-formed notification, whether or
|
| +not they understand it.
|
|
|
| -Errors:
|
| + Senders should only send the notifications described here when this
|
| +protocol description specifies that they are permitted. In the future,
|
| +we may extend the protocol to permit existing notifications in new
|
| +contexts; this rule helps older senders avoid confusing newer
|
| +recipients.
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| + (Older versions of GDB ignore bytes received until they see the `$'
|
| +byte that begins an ordinary packet, so new stubs may transmit
|
| +notifications without fear of confusing older clients. There are no
|
| +notifications defined for GDB to send at the moment, but we assume that
|
| +most older stubs would ignore them, as well.)
|
|
|
| + Each notification is comprised of three parts:
|
| +`NAME:EVENT'
|
| + The notification packet is sent by the side that initiates the
|
| + exchange (currently, only the stub does that), with EVENT carrying
|
| + the specific information about the notification. NAME is the name
|
| + of the notification.
|
| +
|
| +`ACK'
|
| + The acknowledge sent by the other side, usually GDB, to
|
| + acknowledge the exchange and request the event.
|
| +
|
| + The purpose of an asynchronous notification mechanism is to report to
|
| +GDB that something interesting happened in the remote stub.
|
| +
|
| + The remote stub may send notification NAME:EVENT at any time, but
|
| +GDB acknowledges the notification when appropriate. The notification
|
| +event is pending before GDB acknowledges. Only one notification at a
|
| +time may be pending; if additional events occur before GDB has
|
| +acknowledged the previous notification, they must be queued by the stub
|
| +for later synchronous transmission in response to ACK packets from GDB.
|
| +Because the notification mechanism is unreliable, the stub is permitted
|
| +to resend a notification if it believes GDB may not have received it.
|
| +
|
| + Specifically, notifications may appear when GDB is not otherwise
|
| +reading input from the stub, or when GDB is expecting to read a normal
|
| +synchronous response or a `+'/`-' acknowledgment to a packet it has
|
| +sent. Notification packets are distinct from any other communication
|
| +from the stub so there is no ambiguity.
|
|
|
| - Note that the `isatty' call is treated as a special case: it returns
|
| -1 to the target if the file descriptor is attached to the GDB console,
|
| -0 otherwise. Implementing through system calls would require
|
| -implementing `ioctl' and would be more complex than needed.
|
| + After receiving a notification, GDB shall acknowledge it by sending
|
| +a ACK packet as a regular, synchronous request to the stub. Such
|
| +acknowledgment is not required to happen immediately, as GDB is
|
| +permitted to send other, unrelated packets to the stub first, which the
|
| +stub should process normally.
|
| +
|
| + Upon receiving a ACK packet, if the stub has other queued events to
|
| +report to GDB, it shall respond by sending a normal EVENT. GDB shall
|
| +then send another ACK packet to solicit further responses; again, it is
|
| +permitted to send other, unrelated packets as well which the stub
|
| +should process normally.
|
| +
|
| + If the stub receives a ACK packet and there are no additional EVENT
|
| +to report, the stub shall return an `OK' response. At this point, GDB
|
| +has finished processing a notification and the stub has completed
|
| +sending any queued events. GDB won't accept any new notifications
|
| +until the final `OK' is received . If further notification events
|
| +occur, the stub shall send a new notification, GDB shall accept the
|
| +notification, and the process shall be repeated.
|
| +
|
| + The process of asynchronous notification can be illustrated by the
|
| +following example:
|
| + <- `%%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;'
|
| + `...'
|
| + -> `vStopped'
|
| + <- `T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;'
|
| + -> `vStopped'
|
| + <- `T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;'
|
| + -> `vStopped'
|
| + <- `OK'
|
| +
|
| + The following notifications are defined:
|
| +NotificationAck Event Description
|
| +Stop vStopped REPLY. The REPLY has the Report an asynchronous
|
| + form of a stop reply, as stop event in non-stop
|
| + described in *note Stop mode.
|
| + Reply Packets::. Refer to
|
| + *note Remote Non-Stop::,
|
| + for information on how
|
| + these notifications are
|
| + acknowledged by GDB.
|
|
|
|
|
| -File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
|
| -
|
| -system
|
| -......
|
| +File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol
|
|
|
| -Synopsis:
|
| - int system(const char *command);
|
| +E.10 Remote Protocol Support for Non-Stop Mode
|
| +==============================================
|
|
|
| -Request:
|
| - `Fsystem,COMMANDPTR/LEN'
|
| +GDB's remote protocol supports non-stop debugging of multi-threaded
|
| +programs, as described in *note Non-Stop Mode::. If the stub supports
|
| +non-stop mode, it should report that to GDB by including `QNonStop+' in
|
| +its `qSupported' response (*note qSupported::).
|
|
|
| -Return value:
|
| - If LEN is zero, the return value indicates whether a shell is
|
| - available. A zero return value indicates a shell is not available.
|
| - For non-zero LEN, the value returned is -1 on error and the return
|
| - status of the command otherwise. Only the exit status of the
|
| - command is returned, which is extracted from the host's `system'
|
| - return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh'
|
| - could not be executed, 127 is returned.
|
| + GDB typically sends a `QNonStop' packet only when establishing a new
|
| +connection with the stub. Entering non-stop mode does not alter the
|
| +state of any currently-running threads, but targets must stop all
|
| +threads in any already-attached processes when entering all-stop mode.
|
| +GDB uses the `?' packet as necessary to probe the target state after a
|
| +mode change.
|
|
|
| -Errors:
|
| + In non-stop mode, when an attached process encounters an event that
|
| +would otherwise be reported with a stop reply, it uses the asynchronous
|
| +notification mechanism (*note Notification Packets::) to inform GDB.
|
| +In contrast to all-stop mode, where all threads in all processes are
|
| +stopped when a stop reply is sent, in non-stop mode only the thread
|
| +reporting the stop event is stopped. That is, when reporting a `S' or
|
| +`T' response to indicate completion of a step operation, hitting a
|
| +breakpoint, or a fault, only the affected thread is stopped; any other
|
| +still-running threads continue to run. When reporting a `W' or `X'
|
| +response, all running threads belonging to other attached processes
|
| +continue to run.
|
|
|
| - `EINTR'
|
| - The call was interrupted by the user.
|
| + In non-stop mode, the target shall respond to the `?' packet as
|
| +follows. First, any incomplete stop reply notification/`vStopped'
|
| +sequence in progress is abandoned. The target must begin a new
|
| +sequence reporting stop events for all stopped threads, whether or not
|
| +it has previously reported those events to GDB. The first stop reply
|
| +is sent as a synchronous reply to the `?' packet, and subsequent stop
|
| +replies are sent as responses to `vStopped' packets using the mechanism
|
| +described above. The target must not send asynchronous stop reply
|
| +notifications until the sequence is complete. If all threads are
|
| +running when the target receives the `?' packet, or if the target is
|
| +not attached to any process, it shall respond `OK'.
|
|
|
| +
|
| +File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol
|
|
|
| - GDB takes over the full task of calling the necessary host calls to
|
| -perform the `system' call. The return value of `system' on the host is
|
| -simplified before it's returned to the target. Any termination signal
|
| -information from the child process is discarded, and the return value
|
| -consists entirely of the exit status of the called command.
|
| +E.11 Packet Acknowledgment
|
| +==========================
|
|
|
| - Due to security concerns, the `system' call is by default refused by
|
| -GDB. The user has to allow this call explicitly with the `set remote
|
| -system-call-allowed 1' command.
|
| +By default, when either the host or the target machine receives a
|
| +packet, the first response expected is an acknowledgment: either `+'
|
| +(to indicate the package was received correctly) or `-' (to request
|
| +retransmission). This mechanism allows the GDB remote protocol to
|
| +operate over unreliable transport mechanisms, such as a serial line.
|
|
|
| -`set remote system-call-allowed'
|
| - Control whether to allow the `system' calls in the File I/O
|
| - protocol for the remote target. The default is zero (disabled).
|
| + In cases where the transport mechanism is itself reliable (such as a
|
| +pipe or TCP connection), the `+'/`-' acknowledgments are redundant. It
|
| +may be desirable to disable them in that case to reduce communication
|
| +overhead, or for other reasons. This can be accomplished by means of
|
| +the `QStartNoAckMode' packet; *note QStartNoAckMode::.
|
|
|
| -`show remote system-call-allowed'
|
| - Show whether the `system' calls are allowed in the File I/O
|
| - protocol.
|
| + When in no-acknowledgment mode, neither the stub nor GDB shall send
|
| +or expect `+'/`-' protocol acknowledgments. The packet and response
|
| +format still includes the normal checksum, as described in *note
|
| +Overview::, but the checksum may be ignored by the receiver.
|
|
|
| -
|
| -File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
|
| + If the stub supports `QStartNoAckMode' and prefers to operate in
|
| +no-acknowledgment mode, it should report that to GDB by including
|
| +`QStartNoAckMode+' in its response to `qSupported'; *note qSupported::.
|
| +If GDB also supports `QStartNoAckMode' and it has not been disabled via
|
| +the `set remote noack-packet off' command (*note Remote
|
| +Configuration::), GDB may then send a `QStartNoAckMode' packet to the
|
| +stub. Only then may the stub actually turn off packet acknowledgments.
|
| +GDB sends a final `+' acknowledgment of the stub's `OK' response, which
|
| +can be safely ignored by the stub.
|
|
|
| -E.13.8 Protocol-specific Representation of Datatypes
|
| -----------------------------------------------------
|
| + Note that `set remote noack-packet' command only affects negotiation
|
| +between GDB and the stub when subsequent connections are made; it does
|
| +not affect the protocol acknowledgment state for any current connection.
|
| +Since `+'/`-' acknowledgments are enabled by default when a new
|
| +connection is established, there is also no protocol request to
|
| +re-enable the acknowledgments for the current connection, once disabled.
|
|
|
| -* Menu:
|
| +
|
| +File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol
|
|
|
| -* Integral Datatypes::
|
| -* Pointer Values::
|
| -* Memory Transfer::
|
| -* struct stat::
|
| -* struct timeval::
|
| +E.12 Examples
|
| +=============
|
|
|
| -
|
| -File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
| +Example sequence of a target being re-started. Notice how the restart
|
| +does not get any direct output:
|
|
|
| -Integral Datatypes
|
| -..................
|
| + -> `R00'
|
| + <- `+'
|
| + _target restarts_
|
| + -> `?'
|
| + <- `+'
|
| + <- `T001:1234123412341234'
|
| + -> `+'
|
|
|
| -The integral datatypes used in the system calls are `int', `unsigned
|
| -int', `long', `unsigned long', `mode_t', and `time_t'.
|
| + Example sequence of a target being stepped by a single instruction:
|
|
|
| - `int', `unsigned int', `mode_t' and `time_t' are implemented as 32
|
| -bit values in this protocol.
|
| + -> `G1445...'
|
| + <- `+'
|
| + -> `s'
|
| + <- `+'
|
| + _time passes_
|
| + <- `T001:1234123412341234'
|
| + -> `+'
|
| + -> `g'
|
| + <- `+'
|
| + <- `1455...'
|
| + -> `+'
|
|
|
| - `long' and `unsigned long' are implemented as 64 bit types.
|
| +
|
| +File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
|
|
|
| - *Note Limits::, for corresponding MIN and MAX values (similar to
|
| -those in `limits.h') to allow range checking on host and target.
|
| +E.13 File-I/O Remote Protocol Extension
|
| +=======================================
|
|
|
| - `time_t' datatypes are defined as seconds since the Epoch.
|
| +* Menu:
|
|
|
| - All integral datatypes transferred as part of a memory read or write
|
| -of a structured datatype e.g. a `struct stat' have to be given in big
|
| -endian byte order.
|
| +* File-I/O Overview::
|
| +* Protocol Basics::
|
| +* The F Request Packet::
|
| +* The F Reply Packet::
|
| +* The Ctrl-C Message::
|
| +* Console I/O::
|
| +* List of Supported Calls::
|
| +* Protocol-specific Representation of Datatypes::
|
| +* Constants::
|
| +* File-I/O Examples::
|
|
|
|
|
| -File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
|
| -
|
| -Pointer Values
|
| -..............
|
| +File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
|
|
| -Pointers to target data are transmitted as they are. An exception is
|
| -made for pointers to buffers for which the length isn't transmitted as
|
| -part of the function call, namely strings. Strings are transmitted as
|
| -a pointer/length pair, both as hex values, e.g.
|
| +E.13.1 File-I/O Overview
|
| +------------------------
|
|
|
| - `1aaf/12'
|
| +The "File I/O remote protocol extension" (short: File-I/O) allows the
|
| +target to use the host's file system and console I/O to perform various
|
| +system calls. System calls on the target system are translated into a
|
| +remote protocol packet to the host system, which then performs the
|
| +needed actions and returns a response packet to the target system.
|
| +This simulates file system operations even on targets that lack file
|
| +systems.
|
|
|
| -which is a pointer to data of length 18 bytes at position 0x1aaf. The
|
| -length is defined as the full string length in bytes, including the
|
| -trailing null byte. For example, the string `"hello world"' at address
|
| -0x123456 is transmitted as
|
| + The protocol is defined to be independent of both the host and
|
| +target systems. It uses its own internal representation of datatypes
|
| +and values. Both GDB and the target's GDB stub are responsible for
|
| +translating the system-dependent value representations into the internal
|
| +protocol representations when data is transmitted.
|
|
|
| - `123456/d'
|
| + The communication is synchronous. A system call is possible only
|
| +when GDB is waiting for a response from the `C', `c', `S' or `s'
|
| +packets. While GDB handles the request for a system call, the target
|
| +is stopped to allow deterministic access to the target's memory.
|
| +Therefore File-I/O is not interruptible by target signals. On the
|
| +other hand, it is possible to interrupt File-I/O by a user interrupt
|
| +(`Ctrl-C') within GDB.
|
|
|
| -
|
| -File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
| + The target's request to perform a host system call does not finish
|
| +the latest `C', `c', `S' or `s' action. That means, after finishing
|
| +the system call, the target returns to continuing the previous activity
|
| +(continue, step). No additional continue or step request from GDB is
|
| +required.
|
|
|
| -Memory Transfer
|
| -...............
|
| + (gdb) continue
|
| + <- target requests 'system call X'
|
| + target is stopped, GDB executes system call
|
| + -> GDB returns result
|
| + ... target continues, GDB returns to wait for the target
|
| + <- target hits breakpoint and sends a Txx packet
|
|
|
| -Structured data which is transferred using a memory read or write (for
|
| -example, a `struct stat') is expected to be in a protocol-specific
|
| -format with all scalar multibyte datatypes being big endian.
|
| -Translation to this representation needs to be done both by the target
|
| -before the `F' packet is sent, and by GDB before it transfers memory to
|
| -the target. Transferred pointers to structured data should point to
|
| -the already-coerced data at any time.
|
| + The protocol only supports I/O on the console and to regular files on
|
| +the host file system. Character or block special devices, pipes, named
|
| +pipes, sockets or any other communication method on the host system are
|
| +not supported by this protocol.
|
| +
|
| + File I/O is not supported in non-stop mode.
|
|
|
|
|
| -File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
|
| +File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
|
|
|
| -struct stat
|
| -...........
|
| +E.13.2 Protocol Basics
|
| +----------------------
|
|
|
| -The buffer of type `struct stat' used by the target and GDB is defined
|
| -as follows:
|
| +The File-I/O protocol uses the `F' packet as the request as well as
|
| +reply packet. Since a File-I/O system call can only occur when GDB is
|
| +waiting for a response from the continuing or stepping target, the
|
| +File-I/O request is a reply that GDB has to expect as a result of a
|
| +previous `C', `c', `S' or `s' packet. This `F' packet contains all
|
| +information needed to allow GDB to call the appropriate host system
|
| +call:
|
|
|
| - struct stat {
|
| - unsigned int st_dev; /* device */
|
| - unsigned int st_ino; /* inode */
|
| - mode_t st_mode; /* protection */
|
| - unsigned int st_nlink; /* number of hard links */
|
| - unsigned int st_uid; /* user ID of owner */
|
| - unsigned int st_gid; /* group ID of owner */
|
| - unsigned int st_rdev; /* device type (if inode device) */
|
| - unsigned long st_size; /* total size, in bytes */
|
| - unsigned long st_blksize; /* blocksize for filesystem I/O */
|
| - unsigned long st_blocks; /* number of blocks allocated */
|
| - time_t st_atime; /* time of last access */
|
| - time_t st_mtime; /* time of last modification */
|
| - time_t st_ctime; /* time of last change */
|
| - };
|
| + * A unique identifier for the requested system call.
|
|
|
| - The integral datatypes conform to the definitions given in the
|
| -appropriate section (see *Note Integral Datatypes::, for details) so
|
| -this structure is of size 64 bytes.
|
| + * All parameters to the system call. Pointers are given as addresses
|
| + in the target memory address space. Pointers to strings are given
|
| + as pointer/length pair. Numerical values are given as they are.
|
| + Numerical control flags are given in a protocol-specific
|
| + representation.
|
|
|
| - The values of several fields have a restricted meaning and/or range
|
| -of values.
|
|
|
| -`st_dev'
|
| - A value of 0 represents a file, 1 the console.
|
| + At this point, GDB has to perform the following actions.
|
|
|
| -`st_ino'
|
| - No valid meaning for the target. Transmitted unchanged.
|
| + * If the parameters include pointer values to data needed as input
|
| + to a system call, GDB requests this data from the target with a
|
| + standard `m' packet request. This additional communication has to
|
| + be expected by the target implementation and is handled as any
|
| + other `m' packet.
|
|
|
| -`st_mode'
|
| - Valid mode bits are described in *Note Constants::. Any other
|
| - bits have currently no meaning for the target.
|
| + * GDB translates all value from protocol representation to host
|
| + representation as needed. Datatypes are coerced into the host
|
| + types.
|
|
|
| -`st_uid'
|
| -`st_gid'
|
| -`st_rdev'
|
| - No valid meaning for the target. Transmitted unchanged.
|
| + * GDB calls the system call.
|
|
|
| -`st_atime'
|
| -`st_mtime'
|
| -`st_ctime'
|
| - These values have a host and file system dependent accuracy.
|
| - Especially on Windows hosts, the file system may not support exact
|
| - timing values.
|
| + * It then coerces datatypes back to protocol representation.
|
|
|
| - The target gets a `struct stat' of the above representation and is
|
| -responsible for coercing it to the target representation before
|
| -continuing.
|
| + * If the system call is expected to return data in buffer space
|
| + specified by pointer parameters to the call, the data is
|
| + transmitted to the target using a `M' or `X' packet. This packet
|
| + has to be expected by the target implementation and is handled as
|
| + any other `M' or `X' packet.
|
|
|
| - Note that due to size differences between the host, target, and
|
| -protocol representations of `struct stat' members, these members could
|
| -eventually get truncated on the target.
|
|
|
| -
|
| -File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
|
| + Eventually GDB replies with another `F' packet which contains all
|
| +necessary information for the target to continue. This at least
|
| +contains
|
|
|
| -struct timeval
|
| -..............
|
| + * Return value.
|
|
|
| -The buffer of type `struct timeval' used by the File-I/O protocol is
|
| -defined as follows:
|
| + * `errno', if has been changed by the system call.
|
|
|
| - struct timeval {
|
| - time_t tv_sec; /* second */
|
| - long tv_usec; /* microsecond */
|
| - };
|
| + * "Ctrl-C" flag.
|
|
|
| - The integral datatypes conform to the definitions given in the
|
| -appropriate section (see *Note Integral Datatypes::, for details) so
|
| -this structure is of size 8 bytes.
|
| +
|
| + After having done the needed type and value coercion, the target
|
| +continues the latest continue or step action.
|
|
|
|
|
| -File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
|
| +File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
|
|
|
| -E.13.9 Constants
|
| -----------------
|
| +E.13.3 The `F' Request Packet
|
| +-----------------------------
|
|
|
| -The following values are used for the constants inside of the protocol.
|
| -GDB and target are responsible for translating these values before and
|
| -after the call as needed.
|
| +The `F' request packet has the following format:
|
|
|
| -* Menu:
|
| +`FCALL-ID,PARAMETER...'
|
| + CALL-ID is the identifier to indicate the host system call to be
|
| + called. This is just the name of the function.
|
| +
|
| + PARAMETER... are the parameters to the system call. Parameters
|
| + are hexadecimal integer values, either the actual values in case
|
| + of scalar datatypes, pointers to target buffer space in case of
|
| + compound datatypes and unspecified memory areas, or pointer/length
|
| + pairs in case of string parameters. These are appended to the
|
| + CALL-ID as a comma-delimited list. All values are transmitted in
|
| + ASCII string representation, pointer/length pairs separated by a
|
| + slash.
|
|
|
| -* Open Flags::
|
| -* mode_t Values::
|
| -* Errno Values::
|
| -* Lseek Flags::
|
| -* Limits::
|
|
|
|
|
| -File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
|
| +File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension
|
|
|
| -Open Flags
|
| -..........
|
| +E.13.4 The `F' Reply Packet
|
| +---------------------------
|
|
|
| -All values are given in hexadecimal representation.
|
| +The `F' reply packet has the following format:
|
|
|
| - O_RDONLY 0x0
|
| - O_WRONLY 0x1
|
| - O_RDWR 0x2
|
| - O_APPEND 0x8
|
| - O_CREAT 0x200
|
| - O_TRUNC 0x400
|
| - O_EXCL 0x800
|
| +`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
|
| + RETCODE is the return code of the system call as hexadecimal value.
|
|
|
| -
|
| -File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
|
| + ERRNO is the `errno' set by the call, in protocol-specific
|
| + representation. This parameter can be omitted if the call was
|
| + successful.
|
|
|
| -mode_t Values
|
| -.............
|
| + CTRL-C FLAG is only sent if the user requested a break. In this
|
| + case, ERRNO must be sent as well, even if the call was successful.
|
| + The CTRL-C FLAG itself consists of the character `C':
|
|
|
| -All values are given in octal representation.
|
| + F0,0,C
|
|
|
| - S_IFREG 0100000
|
| - S_IFDIR 040000
|
| - S_IRUSR 0400
|
| - S_IWUSR 0200
|
| - S_IXUSR 0100
|
| - S_IRGRP 040
|
| - S_IWGRP 020
|
| - S_IXGRP 010
|
| - S_IROTH 04
|
| - S_IWOTH 02
|
| - S_IXOTH 01
|
| + or, if the call was interrupted before the host call has been
|
| + performed:
|
|
|
| -
|
| -File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
|
| + F-1,4,C
|
|
|
| -Errno Values
|
| -............
|
| + assuming 4 is the protocol-specific representation of `EINTR'.
|
|
|
| -All values are given in decimal representation.
|
|
|
| - EPERM 1
|
| - ENOENT 2
|
| - EINTR 4
|
| - EBADF 9
|
| - EACCES 13
|
| - EFAULT 14
|
| - EBUSY 16
|
| - EEXIST 17
|
| - ENODEV 19
|
| - ENOTDIR 20
|
| - EISDIR 21
|
| - EINVAL 22
|
| - ENFILE 23
|
| - EMFILE 24
|
| - EFBIG 27
|
| - ENOSPC 28
|
| - ESPIPE 29
|
| - EROFS 30
|
| - ENAMETOOLONG 91
|
| - EUNKNOWN 9999
|
| +
|
| +File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
|
|
|
| - `EUNKNOWN' is used as a fallback error value if a host system returns
|
| - any error value not in the list of supported error numbers.
|
| +E.13.5 The `Ctrl-C' Message
|
| +---------------------------
|
|
|
| -
|
| -File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
|
| +If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
|
| +Packet::), the target should behave as if it had gotten a break
|
| +message. The meaning for the target is "system call interrupted by
|
| +`SIGINT'". Consequentially, the target should actually stop (as with a
|
| +break message) and return to GDB with a `T02' packet.
|
|
|
| -Lseek Flags
|
| -...........
|
| + It's important for the target to know in which state the system call
|
| +was interrupted. There are two possible cases:
|
|
|
| - SEEK_SET 0
|
| - SEEK_CUR 1
|
| - SEEK_END 2
|
| + * The system call hasn't been performed on the host yet.
|
|
|
| -
|
| -File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
|
| + * The system call on the host has been finished.
|
|
|
| -Limits
|
| -......
|
|
|
| -All values are given in decimal representation.
|
| + These two states can be distinguished by the target by the value of
|
| +the returned `errno'. If it's the protocol representation of `EINTR',
|
| +the system call hasn't been performed. This is equivalent to the
|
| +`EINTR' handling on POSIX systems. In any other case, the target may
|
| +presume that the system call has been finished -- successfully or not
|
| +-- and should behave as if the break message arrived right after the
|
| +system call.
|
|
|
| - INT_MIN -2147483648
|
| - INT_MAX 2147483647
|
| - UINT_MAX 4294967295
|
| - LONG_MIN -9223372036854775808
|
| - LONG_MAX 9223372036854775807
|
| - ULONG_MAX 18446744073709551615
|
| + GDB must behave reliably. If the system call has not been called
|
| +yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
|
| +in the packet. If the system call on the host has been finished before
|
| +the user requests a break, the full action must be finished by GDB.
|
| +This requires sending `M' or `X' packets as necessary. The `F' packet
|
| +may only be sent when either nothing has happened or the full action
|
| +has been completed.
|
|
|
|
|
| -File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
|
| +File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
|
|
|
| -E.13.10 File-I/O Examples
|
| --------------------------
|
| +E.13.6 Console I/O
|
| +------------------
|
|
|
| -Example sequence of a write call, file descriptor 3, buffer is at target
|
| -address 0x1234, 6 bytes should be written:
|
| +By default and if not explicitly closed by the target system, the file
|
| +descriptors 0, 1 and 2 are connected to the GDB console. Output on the
|
| +GDB console is handled as any other file output operation (`write(1,
|
| +...)' or `write(2, ...)'). Console input is handled by GDB so that
|
| +after the target read request from file descriptor 0 all following
|
| +typing is buffered until either one of the following conditions is met:
|
|
|
| - <- `Fwrite,3,1234,6'
|
| - _request memory read from target_
|
| - -> `m1234,6'
|
| - <- XXXXXX
|
| - _return "6 bytes written"_
|
| - -> `F6'
|
| + * The user types `Ctrl-c'. The behaviour is as explained above, and
|
| + the `read' system call is treated as finished.
|
|
|
| - Example sequence of a read call, file descriptor 3, buffer is at
|
| -target address 0x1234, 6 bytes should be read:
|
| + * The user presses <RET>. This is treated as end of input with a
|
| + trailing newline.
|
|
|
| - <- `Fread,3,1234,6'
|
| - _request memory write to target_
|
| - -> `X1234,6:XXXXXX'
|
| - _return "6 bytes read"_
|
| - -> `F6'
|
| + * The user types `Ctrl-d'. This is treated as end of input. No
|
| + trailing character (neither newline nor `Ctrl-D') is appended to
|
| + the input.
|
|
|
| - Example sequence of a read call, call fails on the host due to
|
| -invalid file descriptor (`EBADF'):
|
|
|
| - <- `Fread,3,1234,6'
|
| - -> `F-1,9'
|
| + If the user has typed more characters than fit in the buffer given to
|
| +the `read' call, the trailing characters are buffered in GDB until
|
| +either another `read(0, ...)' is requested by the target, or debugging
|
| +is stopped at the user's request.
|
|
|
| - Example sequence of a read call, user presses `Ctrl-c' before
|
| -syscall on host is called:
|
| +
|
| +File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension
|
|
|
| - <- `Fread,3,1234,6'
|
| - -> `F-1,4,C'
|
| - <- `T02'
|
| +E.13.7 List of Supported Calls
|
| +------------------------------
|
|
|
| - Example sequence of a read call, user presses `Ctrl-c' after syscall
|
| -on host is called:
|
| +* Menu:
|
|
|
| - <- `Fread,3,1234,6'
|
| - -> `X1234,6:XXXXXX'
|
| - <- `T02'
|
| +* open::
|
| +* close::
|
| +* read::
|
| +* write::
|
| +* lseek::
|
| +* rename::
|
| +* unlink::
|
| +* stat/fstat::
|
| +* gettimeofday::
|
| +* isatty::
|
| +* system::
|
|
|
|
|
| -File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
|
| +File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
|
|
|
| -E.14 Library List Format
|
| -========================
|
| +open
|
| +....
|
|
|
| -On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
|
| -process as your application to manage libraries. In this case, GDB can
|
| -use the loader's symbol table and normal memory operations to maintain
|
| -a list of shared libraries. On other platforms, the operating system
|
| -manages loaded libraries. GDB can not retrieve the list of currently
|
| -loaded libraries through memory operations, so it uses the
|
| -`qXfer:libraries:read' packet (*note qXfer library list read::)
|
| -instead. The remote stub queries the target's operating system and
|
| -reports which libraries are loaded.
|
| +Synopsis:
|
| + int open(const char *pathname, int flags);
|
| + int open(const char *pathname, int flags, mode_t mode);
|
|
|
| - The `qXfer:libraries:read' packet returns an XML document which
|
| -lists loaded libraries and their offsets. Each library has an
|
| -associated name and one or more segment or section base addresses,
|
| -which report where the library was loaded in memory.
|
| +Request:
|
| + `Fopen,PATHPTR/LEN,FLAGS,MODE'
|
|
|
| - For the common case of libraries that are fully linked binaries, the
|
| -library should have a list of segments. If the target supports dynamic
|
| -linking of a relocatable object file, its library XML element should
|
| -instead include a list of allocated sections. The segment or section
|
| -bases are start addresses, not relocation offsets; they do not depend
|
| -on the library's link-time base addresses.
|
| + FLAGS is the bitwise `OR' of the following values:
|
|
|
| - GDB must be linked with the Expat library to support XML library
|
| -lists. *Note Expat::.
|
| + `O_CREAT'
|
| + If the file does not exist it will be created. The host
|
| + rules apply as far as file ownership and time stamps are
|
| + concerned.
|
|
|
| - A simple memory map, with one loaded library relocated by a single
|
| -offset, looks like this:
|
| + `O_EXCL'
|
| + When used with `O_CREAT', if the file already exists it is an
|
| + error and open() fails.
|
|
|
| - <library-list>
|
| - <library name="/lib/libc.so.6">
|
| - <segment address="0x10000000"/>
|
| - </library>
|
| - </library-list>
|
| + `O_TRUNC'
|
| + If the file already exists and the open mode allows writing
|
| + (`O_RDWR' or `O_WRONLY' is given) it will be truncated to
|
| + zero length.
|
|
|
| - Another simple memory map, with one loaded library with three
|
| -allocated sections (.text, .data, .bss), looks like this:
|
| + `O_APPEND'
|
| + The file is opened in append mode.
|
|
|
| - <library-list>
|
| - <library name="sharedlib.o">
|
| - <section address="0x10000000"/>
|
| - <section address="0x20000000"/>
|
| - <section address="0x30000000"/>
|
| - </library>
|
| - </library-list>
|
| + `O_RDONLY'
|
| + The file is opened for reading only.
|
|
|
| - The format of a library list is described by this DTD:
|
| + `O_WRONLY'
|
| + The file is opened for writing only.
|
|
|
| - <!-- library-list: Root element with versioning -->
|
| - <!ELEMENT library-list (library)*>
|
| - <!ATTLIST library-list version CDATA #FIXED "1.0">
|
| - <!ELEMENT library (segment*, section*)>
|
| - <!ATTLIST library name CDATA #REQUIRED>
|
| - <!ELEMENT segment EMPTY>
|
| - <!ATTLIST segment address CDATA #REQUIRED>
|
| - <!ELEMENT section EMPTY>
|
| - <!ATTLIST section address CDATA #REQUIRED>
|
| + `O_RDWR'
|
| + The file is opened for reading and writing.
|
|
|
| - In addition, segments and section descriptors cannot be mixed within
|
| -a single library element, and you must supply at least one segment or
|
| -section for each library.
|
| + Other bits are silently ignored.
|
|
|
| -
|
| -File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol
|
| + MODE is the bitwise `OR' of the following values:
|
|
|
| -E.15 Library List Format for SVR4 Targets
|
| -=========================================
|
| + `S_IRUSR'
|
| + User has read permission.
|
|
|
| -On SVR4 platforms GDB can use the symbol table of a dynamic loader
|
| -(e.g. `ld.so') and normal memory operations to maintain a list of
|
| -shared libraries. Still a special library list provided by this packet
|
| -is more efficient for the GDB remote protocol.
|
| + `S_IWUSR'
|
| + User has write permission.
|
|
|
| - The `qXfer:libraries-svr4:read' packet returns an XML document which
|
| -lists loaded libraries and their SVR4 linker parameters. For each
|
| -library on SVR4 target, the following parameters are reported:
|
| + `S_IRGRP'
|
| + Group has read permission.
|
|
|
| - - `name', the absolute file name from the `l_name' field of `struct
|
| - link_map'.
|
| + `S_IWGRP'
|
| + Group has write permission.
|
|
|
| - - `lm' with address of `struct link_map' used for TLS (Thread Local
|
| - Storage) access.
|
| + `S_IROTH'
|
| + Others have read permission.
|
|
|
| - - `l_addr', the displacement as read from the field `l_addr' of
|
| - `struct link_map'. For prelinked libraries this is not an absolute
|
| - memory address. It is a displacement of absolute memory address
|
| - against address the file was prelinked to during the library load.
|
| + `S_IWOTH'
|
| + Others have write permission.
|
|
|
| - - `l_ld', which is memory address of the `PT_DYNAMIC' segment
|
| + Other bits are silently ignored.
|
|
|
| - Additionally the single `main-lm' attribute specifies address of
|
| -`struct link_map' used for the main executable. This parameter is used
|
| -for TLS access and its presence is optional.
|
| +Return value:
|
| + `open' returns the new file descriptor or -1 if an error occurred.
|
|
|
| - GDB must be linked with the Expat library to support XML SVR4
|
| -library lists. *Note Expat::.
|
| +Errors:
|
|
|
| - A simple memory map, with two loaded libraries (which do not use
|
| -prelink), looks like this:
|
| + `EEXIST'
|
| + PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
|
|
|
| - <library-list-svr4 version="1.0" main-lm="0xe4f8f8">
|
| - <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
|
| - l_ld="0xe4eefc"/>
|
| - <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
|
| - l_ld="0x152350"/>
|
| - </library-list-svr>
|
| + `EISDIR'
|
| + PATHNAME refers to a directory.
|
|
|
| - The format of an SVR4 library list is described by this DTD:
|
| + `EACCES'
|
| + The requested access is not allowed.
|
|
|
| - <!-- library-list-svr4: Root element with versioning -->
|
| - <!ELEMENT library-list-svr4 (library)*>
|
| - <!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
|
| - <!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
|
| - <!ELEMENT library EMPTY>
|
| - <!ATTLIST library name CDATA #REQUIRED>
|
| - <!ATTLIST library lm CDATA #REQUIRED>
|
| - <!ATTLIST library l_addr CDATA #REQUIRED>
|
| - <!ATTLIST library l_ld CDATA #REQUIRED>
|
| + `ENAMETOOLONG'
|
| + PATHNAME was too long.
|
|
|
| -
|
| -File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol
|
| + `ENOENT'
|
| + A directory component in PATHNAME does not exist.
|
|
|
| -E.16 Memory Map Format
|
| -======================
|
| + `ENODEV'
|
| + PATHNAME refers to a device, pipe, named pipe or socket.
|
|
|
| -To be able to write into flash memory, GDB needs to obtain a memory map
|
| -from the target. This section describes the format of the memory map.
|
| + `EROFS'
|
| + PATHNAME refers to a file on a read-only filesystem and write
|
| + access was requested.
|
|
|
| - The memory map is obtained using the `qXfer:memory-map:read' (*note
|
| -qXfer memory map read::) packet and is an XML document that lists
|
| -memory regions.
|
| + `EFAULT'
|
| + PATHNAME is an invalid pointer value.
|
|
|
| - GDB must be linked with the Expat library to support XML memory
|
| -maps. *Note Expat::.
|
| + `ENOSPC'
|
| + No space on device to create the file.
|
|
|
| - The top-level structure of the document is shown below:
|
| + `EMFILE'
|
| + The process already has the maximum number of files open.
|
|
|
| - <?xml version="1.0"?>
|
| - <!DOCTYPE memory-map
|
| - PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
|
| - "http://sourceware.org/gdb/gdb-memory-map.dtd">
|
| - <memory-map>
|
| - region...
|
| - </memory-map>
|
| + `ENFILE'
|
| + The limit on the total number of files open on the system has
|
| + been reached.
|
|
|
| - Each region can be either:
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| - * A region of RAM starting at ADDR and extending for LENGTH bytes
|
| - from there:
|
|
|
| - <memory type="ram" start="ADDR" length="LENGTH"/>
|
| +
|
| +File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
|
|
|
| - * A region of read-only memory:
|
| +close
|
| +.....
|
|
|
| - <memory type="rom" start="ADDR" length="LENGTH"/>
|
| +Synopsis:
|
| + int close(int fd);
|
|
|
| - * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
|
| - length:
|
| +Request:
|
| + `Fclose,FD'
|
|
|
| - <memory type="flash" start="ADDR" length="LENGTH">
|
| - <property name="blocksize">BLOCKSIZE</property>
|
| - </memory>
|
| +Return value:
|
| + `close' returns zero on success, or -1 if an error occurred.
|
|
|
| +Errors:
|
|
|
| - Regions must not overlap. GDB assumes that areas of memory not
|
| -covered by the memory map are RAM, and uses the ordinary `M' and `X'
|
| -packets to write to addresses in such ranges.
|
| + `EBADF'
|
| + FD isn't a valid open file descriptor.
|
|
|
| - The formal DTD for memory map format is given below:
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| - <!-- ................................................... -->
|
| - <!-- Memory Map XML DTD ................................ -->
|
| - <!-- File: memory-map.dtd .............................. -->
|
| - <!-- .................................... .............. -->
|
| - <!-- memory-map.dtd -->
|
| - <!-- memory-map: Root element with versioning -->
|
| - <!ELEMENT memory-map (memory | property)>
|
| - <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
|
| - <!ELEMENT memory (property)>
|
| - <!-- memory: Specifies a memory region,
|
| - and its type, or device. -->
|
| - <!ATTLIST memory type CDATA #REQUIRED
|
| - start CDATA #REQUIRED
|
| - length CDATA #REQUIRED
|
| - device CDATA #IMPLIED>
|
| - <!-- property: Generic attribute tag -->
|
| - <!ELEMENT property (#PCDATA | property)*>
|
| - <!ATTLIST property name CDATA #REQUIRED>
|
|
|
|
|
| -File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol
|
| -
|
| -E.17 Thread List Format
|
| -=======================
|
| -
|
| -To efficiently update the list of threads and their attributes, GDB
|
| -issues the `qXfer:threads:read' packet (*note qXfer threads read::) and
|
| -obtains the XML document with the following structure:
|
| -
|
| - <?xml version="1.0"?>
|
| - <threads>
|
| - <thread id="id" core="0">
|
| - ... description ...
|
| - </thread>
|
| - </threads>
|
| +File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
|
|
|
| - Each `thread' element must have the `id' attribute that identifies
|
| -the thread (*note thread-id syntax::). The `core' attribute, if
|
| -present, specifies which processor core the thread was last executing
|
| -on. The content of the of `thread' element is interpreted as
|
| -human-readable auxilliary information.
|
| +read
|
| +....
|
|
|
| -
|
| -File: gdb.info, Node: Traceframe Info Format, Prev: Thread List Format, Up: Remote Protocol
|
| +Synopsis:
|
| + int read(int fd, void *buf, unsigned int count);
|
|
|
| -E.18 Traceframe Info Format
|
| -===========================
|
| +Request:
|
| + `Fread,FD,BUFPTR,COUNT'
|
|
|
| -To be able to know which objects in the inferior can be examined when
|
| -inspecting a tracepoint hit, GDB needs to obtain the list of memory
|
| -ranges, registers and trace state variables that have been collected in
|
| -a traceframe.
|
| +Return value:
|
| + On success, the number of bytes read is returned. Zero indicates
|
| + end of file. If count is zero, read returns zero as well. On
|
| + error, -1 is returned.
|
|
|
| - This list is obtained using the `qXfer:traceframe-info:read' (*note
|
| -qXfer traceframe info read::) packet and is an XML document.
|
| +Errors:
|
|
|
| - GDB must be linked with the Expat library to support XML traceframe
|
| -info discovery. *Note Expat::.
|
| + `EBADF'
|
| + FD is not a valid file descriptor or is not open for reading.
|
|
|
| - The top-level structure of the document is shown below:
|
| + `EFAULT'
|
| + BUFPTR is an invalid pointer value.
|
|
|
| - <?xml version="1.0"?>
|
| - <!DOCTYPE traceframe-info
|
| - PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
|
| - "http://sourceware.org/gdb/gdb-traceframe-info.dtd">
|
| - <traceframe-info>
|
| - block...
|
| - </traceframe-info>
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| - Each traceframe block can be either:
|
|
|
| - * A region of collected memory starting at ADDR and extending for
|
| - LENGTH bytes from there:
|
| +
|
| +File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
|
|
|
| - <memory start="ADDR" length="LENGTH"/>
|
| +write
|
| +.....
|
|
|
| +Synopsis:
|
| + int write(int fd, const void *buf, unsigned int count);
|
|
|
| - The formal DTD for the traceframe info format is given below:
|
| +Request:
|
| + `Fwrite,FD,BUFPTR,COUNT'
|
|
|
| - <!ELEMENT traceframe-info (memory)* >
|
| - <!ATTLIST traceframe-info version CDATA #FIXED "1.0">
|
| +Return value:
|
| + On success, the number of bytes written are returned. Zero
|
| + indicates nothing was written. On error, -1 is returned.
|
|
|
| - <!ELEMENT memory EMPTY>
|
| - <!ATTLIST memory start CDATA #REQUIRED
|
| - length CDATA #REQUIRED>
|
| +Errors:
|
|
|
| -
|
| -File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top
|
| + `EBADF'
|
| + FD is not a valid file descriptor or is not open for writing.
|
|
|
| -Appendix F The GDB Agent Expression Mechanism
|
| -*********************************************
|
| + `EFAULT'
|
| + BUFPTR is an invalid pointer value.
|
|
|
| -In some applications, it is not feasible for the debugger to interrupt
|
| -the program's execution long enough for the developer to learn anything
|
| -helpful about its behavior. If the program's correctness depends on its
|
| -real-time behavior, delays introduced by a debugger might cause the
|
| -program to fail, even when the code itself is correct. It is useful to
|
| -be able to observe the program's behavior without interrupting it.
|
| + `EFBIG'
|
| + An attempt was made to write a file that exceeds the
|
| + host-specific maximum file size allowed.
|
|
|
| - Using GDB's `trace' and `collect' commands, the user can specify
|
| -locations in the program, and arbitrary expressions to evaluate when
|
| -those locations are reached. Later, using the `tfind' command, she can
|
| -examine the values those expressions had when the program hit the trace
|
| -points. The expressions may also denote objects in memory --
|
| -structures or arrays, for example -- whose values GDB should record;
|
| -while visiting a particular tracepoint, the user may inspect those
|
| -objects as if they were in memory at that moment. However, because GDB
|
| -records these values without interacting with the user, it can do so
|
| -quickly and unobtrusively, hopefully not disturbing the program's
|
| -behavior.
|
| -
|
| - When GDB is debugging a remote target, the GDB "agent" code running
|
| -on the target computes the values of the expressions itself. To avoid
|
| -having a full symbolic expression evaluator on the agent, GDB translates
|
| -expressions in the source language into a simpler bytecode language, and
|
| -then sends the bytecode to the agent; the agent then executes the
|
| -bytecode, and records the values for GDB to retrieve later.
|
| -
|
| - The bytecode language is simple; there are forty-odd opcodes, the
|
| -bulk of which are the usual vocabulary of C operands (addition,
|
| -subtraction, shifts, and so on) and various sizes of literals and
|
| -memory reference operations. The bytecode interpreter operates
|
| -strictly on machine-level values -- various sizes of integers and
|
| -floating point numbers -- and requires no information about types or
|
| -symbols; thus, the interpreter's internal data structures are simple,
|
| -and each bytecode requires only a few native machine instructions to
|
| -implement it. The interpreter is small, and strict limits on the
|
| -memory and time required to evaluate an expression are easy to
|
| -determine, making it suitable for use by the debugging agent in
|
| -real-time applications.
|
| + `ENOSPC'
|
| + No space on device to write the data.
|
|
|
| -* Menu:
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| -* General Bytecode Design:: Overview of the interpreter.
|
| -* Bytecode Descriptions:: What each one does.
|
| -* Using Agent Expressions:: How agent expressions fit into the big picture.
|
| -* Varying Target Capabilities:: How to discover what the target can do.
|
| -* Rationale:: Why we did it this way.
|
|
|
|
|
| -File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions
|
| +File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
|
|
|
| -F.1 General Bytecode Design
|
| -===========================
|
| +lseek
|
| +.....
|
|
|
| -The agent represents bytecode expressions as an array of bytes. Each
|
| -instruction is one byte long (thus the term "bytecode"). Some
|
| -instructions are followed by operand bytes; for example, the `goto'
|
| -instruction is followed by a destination for the jump.
|
| -
|
| - The bytecode interpreter is a stack-based machine; most instructions
|
| -pop their operands off the stack, perform some operation, and push the
|
| -result back on the stack for the next instruction to consume. Each
|
| -element of the stack may contain either a integer or a floating point
|
| -value; these values are as many bits wide as the largest integer that
|
| -can be directly manipulated in the source language. Stack elements
|
| -carry no record of their type; bytecode could push a value as an
|
| -integer, then pop it as a floating point value. However, GDB will not
|
| -generate code which does this. In C, one might define the type of a
|
| -stack element as follows:
|
| - union agent_val {
|
| - LONGEST l;
|
| - DOUBLEST d;
|
| - };
|
| - where `LONGEST' and `DOUBLEST' are `typedef' names for the largest
|
| -integer and floating point types on the machine.
|
| -
|
| - By the time the bytecode interpreter reaches the end of the
|
| -expression, the value of the expression should be the only value left
|
| -on the stack. For tracing applications, `trace' bytecodes in the
|
| -expression will have recorded the necessary data, and the value on the
|
| -stack may be discarded. For other applications, like conditional
|
| -breakpoints, the value may be useful.
|
| -
|
| - Separate from the stack, the interpreter has two registers:
|
| -`pc'
|
| - The address of the next bytecode to execute.
|
| -
|
| -`start'
|
| - The address of the start of the bytecode expression, necessary for
|
| - interpreting the `goto' and `if_goto' instructions.
|
| -
|
| - Neither of these registers is directly visible to the bytecode
|
| -language itself, but they are useful for defining the meanings of the
|
| -bytecode operations.
|
| -
|
| - There are no instructions to perform side effects on the running
|
| -program, or call the program's functions; we assume that these
|
| -expressions are only used for unobtrusive debugging, not for patching
|
| -the running code.
|
| -
|
| - Most bytecode instructions do not distinguish between the various
|
| -sizes of values, and operate on full-width values; the upper bits of the
|
| -values are simply ignored, since they do not usually make a difference
|
| -to the value computed. The exceptions to this rule are:
|
| -memory reference instructions (`ref'N)
|
| - There are distinct instructions to fetch different word sizes from
|
| - memory. Once on the stack, however, the values are treated as
|
| - full-size integers. They may need to be sign-extended; the `ext'
|
| - instruction exists for this purpose.
|
| -
|
| -the sign-extension instruction (`ext' N)
|
| - These clearly need to know which portion of their operand is to be
|
| - extended to occupy the full length of the word.
|
| -
|
| -
|
| - If the interpreter is unable to evaluate an expression completely for
|
| -some reason (a memory location is inaccessible, or a divisor is zero,
|
| -for example), we say that interpretation "terminates with an error".
|
| -This means that the problem is reported back to the interpreter's caller
|
| -in some helpful way. In general, code using agent expressions should
|
| -assume that they may attempt to divide by zero, fetch arbitrary memory
|
| -locations, and misbehave in other ways.
|
| -
|
| - Even complicated C expressions compile to a few bytecode
|
| -instructions; for example, the expression `x + y * z' would typically
|
| -produce code like the following, assuming that `x' and `y' live in
|
| -registers, and `z' is a global variable holding a 32-bit `int':
|
| - reg 1
|
| - reg 2
|
| - const32 address of z
|
| - ref32
|
| - ext 32
|
| - mul
|
| - add
|
| - end
|
| -
|
| - In detail, these mean:
|
| -`reg 1'
|
| - Push the value of register 1 (presumably holding `x') onto the
|
| - stack.
|
| -
|
| -`reg 2'
|
| - Push the value of register 2 (holding `y').
|
| -
|
| -`const32 address of z'
|
| - Push the address of `z' onto the stack.
|
| -
|
| -`ref32'
|
| - Fetch a 32-bit word from the address at the top of the stack;
|
| - replace the address on the stack with the value. Thus, we replace
|
| - the address of `z' with `z''s value.
|
| -
|
| -`ext 32'
|
| - Sign-extend the value on the top of the stack from 32 bits to full
|
| - length. This is necessary because `z' is a signed integer.
|
| -
|
| -`mul'
|
| - Pop the top two numbers on the stack, multiply them, and push their
|
| - product. Now the top of the stack contains the value of the
|
| - expression `y * z'.
|
| -
|
| -`add'
|
| - Pop the top two numbers, add them, and push the sum. Now the top
|
| - of the stack contains the value of `x + y * z'.
|
| -
|
| -`end'
|
| - Stop executing; the value left on the stack top is the value to be
|
| - recorded.
|
| +Synopsis:
|
| + long lseek (int fd, long offset, int flag);
|
|
|
| +Request:
|
| + `Flseek,FD,OFFSET,FLAG'
|
|
|
| -
|
| -File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions
|
| + FLAG is one of:
|
|
|
| -F.2 Bytecode Descriptions
|
| -=========================
|
| + `SEEK_SET'
|
| + The offset is set to OFFSET bytes.
|
|
|
| -Each bytecode description has the following form:
|
| + `SEEK_CUR'
|
| + The offset is set to its current location plus OFFSET bytes.
|
|
|
| -`add' (0x02): A B => A+B
|
| - Pop the top two stack items, A and B, as integers; push their sum,
|
| - as an integer.
|
| + `SEEK_END'
|
| + The offset is set to the size of the file plus OFFSET bytes.
|
|
|
| +Return value:
|
| + On success, the resulting unsigned offset in bytes from the
|
| + beginning of the file is returned. Otherwise, a value of -1 is
|
| + returned.
|
|
|
| - In this example, `add' is the name of the bytecode, and `(0x02)' is
|
| -the one-byte value used to encode the bytecode, in hexadecimal. The
|
| -phrase "A B => A+B" shows the stack before and after the bytecode
|
| -executes. Beforehand, the stack must contain at least two values, A
|
| -and B; since the top of the stack is to the right, B is on the top of
|
| -the stack, and A is underneath it. After execution, the bytecode will
|
| -have popped A and B from the stack, and replaced them with a single
|
| -value, A+B. There may be other values on the stack below those shown,
|
| -but the bytecode affects only those shown.
|
| -
|
| - Here is another example:
|
| -
|
| -`const8' (0x22) N: => N
|
| - Push the 8-bit integer constant N on the stack, without sign
|
| - extension.
|
| -
|
| -
|
| - In this example, the bytecode `const8' takes an operand N directly
|
| -from the bytecode stream; the operand follows the `const8' bytecode
|
| -itself. We write any such operands immediately after the name of the
|
| -bytecode, before the colon, and describe the exact encoding of the
|
| -operand in the bytecode stream in the body of the bytecode description.
|
| -
|
| - For the `const8' bytecode, there are no stack items given before the
|
| -=>; this simply means that the bytecode consumes no values from the
|
| -stack. If a bytecode consumes no values, or produces no values, the
|
| -list on either side of the => may be empty.
|
| -
|
| - If a value is written as A, B, or N, then the bytecode treats it as
|
| -an integer. If a value is written is ADDR, then the bytecode treats it
|
| -as an address.
|
| -
|
| - We do not fully describe the floating point operations here; although
|
| -this design can be extended in a clean way to handle floating point
|
| -values, they are not of immediate interest to the customer, so we avoid
|
| -describing them, to save time.
|
| -
|
| -`float' (0x01): =>
|
| - Prefix for floating-point bytecodes. Not implemented yet.
|
| -
|
| -`add' (0x02): A B => A+B
|
| - Pop two integers from the stack, and push their sum, as an integer.
|
| -
|
| -`sub' (0x03): A B => A-B
|
| - Pop two integers from the stack, subtract the top value from the
|
| - next-to-top value, and push the difference.
|
| -
|
| -`mul' (0x04): A B => A*B
|
| - Pop two integers from the stack, multiply them, and push the
|
| - product on the stack. Note that, when one multiplies two N-bit
|
| - numbers yielding another N-bit number, it is irrelevant whether the
|
| - numbers are signed or not; the results are the same.
|
| -
|
| -`div_signed' (0x05): A B => A/B
|
| - Pop two signed integers from the stack; divide the next-to-top
|
| - value by the top value, and push the quotient. If the divisor is
|
| - zero, terminate with an error.
|
| -
|
| -`div_unsigned' (0x06): A B => A/B
|
| - Pop two unsigned integers from the stack; divide the next-to-top
|
| - value by the top value, and push the quotient. If the divisor is
|
| - zero, terminate with an error.
|
| -
|
| -`rem_signed' (0x07): A B => A MODULO B
|
| - Pop two signed integers from the stack; divide the next-to-top
|
| - value by the top value, and push the remainder. If the divisor is
|
| - zero, terminate with an error.
|
| -
|
| -`rem_unsigned' (0x08): A B => A MODULO B
|
| - Pop two unsigned integers from the stack; divide the next-to-top
|
| - value by the top value, and push the remainder. If the divisor is
|
| - zero, terminate with an error.
|
| -
|
| -`lsh' (0x09): A B => A<<B
|
| - Pop two integers from the stack; let A be the next-to-top value,
|
| - and B be the top value. Shift A left by B bits, and push the
|
| - result.
|
| -
|
| -`rsh_signed' (0x0a): A B => `(signed)'A>>B
|
| - Pop two integers from the stack; let A be the next-to-top value,
|
| - and B be the top value. Shift A right by B bits, inserting copies
|
| - of the top bit at the high end, and push the result.
|
| -
|
| -`rsh_unsigned' (0x0b): A B => A>>B
|
| - Pop two integers from the stack; let A be the next-to-top value,
|
| - and B be the top value. Shift A right by B bits, inserting zero
|
| - bits at the high end, and push the result.
|
| -
|
| -`log_not' (0x0e): A => !A
|
| - Pop an integer from the stack; if it is zero, push the value one;
|
| - otherwise, push the value zero.
|
| -
|
| -`bit_and' (0x0f): A B => A&B
|
| - Pop two integers from the stack, and push their bitwise `and'.
|
| -
|
| -`bit_or' (0x10): A B => A|B
|
| - Pop two integers from the stack, and push their bitwise `or'.
|
| -
|
| -`bit_xor' (0x11): A B => A^B
|
| - Pop two integers from the stack, and push their bitwise
|
| - exclusive-`or'.
|
| -
|
| -`bit_not' (0x12): A => ~A
|
| - Pop an integer from the stack, and push its bitwise complement.
|
| -
|
| -`equal' (0x13): A B => A=B
|
| - Pop two integers from the stack; if they are equal, push the value
|
| - one; otherwise, push the value zero.
|
| -
|
| -`less_signed' (0x14): A B => A<B
|
| - Pop two signed integers from the stack; if the next-to-top value
|
| - is less than the top value, push the value one; otherwise, push
|
| - the value zero.
|
| -
|
| -`less_unsigned' (0x15): A B => A<B
|
| - Pop two unsigned integers from the stack; if the next-to-top value
|
| - is less than the top value, push the value one; otherwise, push
|
| - the value zero.
|
| -
|
| -`ext' (0x16) N: A => A, sign-extended from N bits
|
| - Pop an unsigned value from the stack; treating it as an N-bit
|
| - twos-complement value, extend it to full length. This means that
|
| - all bits to the left of bit N-1 (where the least significant bit
|
| - is bit 0) are set to the value of bit N-1. Note that N may be
|
| - larger than or equal to the width of the stack elements of the
|
| - bytecode engine; in this case, the bytecode should have no effect.
|
| -
|
| - The number of source bits to preserve, N, is encoded as a single
|
| - byte unsigned integer following the `ext' bytecode.
|
| -
|
| -`zero_ext' (0x2a) N: A => A, zero-extended from N bits
|
| - Pop an unsigned value from the stack; zero all but the bottom N
|
| - bits. This means that all bits to the left of bit N-1 (where the
|
| - least significant bit is bit 0) are set to the value of bit N-1.
|
| -
|
| - The number of source bits to preserve, N, is encoded as a single
|
| - byte unsigned integer following the `zero_ext' bytecode.
|
| -
|
| -`ref8' (0x17): ADDR => A
|
| -`ref16' (0x18): ADDR => A
|
| -`ref32' (0x19): ADDR => A
|
| -`ref64' (0x1a): ADDR => A
|
| - Pop an address ADDR from the stack. For bytecode `ref'N, fetch an
|
| - N-bit value from ADDR, using the natural target endianness. Push
|
| - the fetched value as an unsigned integer.
|
| -
|
| - Note that ADDR may not be aligned in any particular way; the
|
| - `refN' bytecodes should operate correctly for any address.
|
| -
|
| - If attempting to access memory at ADDR would cause a processor
|
| - exception of some sort, terminate with an error.
|
| -
|
| -`ref_float' (0x1b): ADDR => D
|
| -`ref_double' (0x1c): ADDR => D
|
| -`ref_long_double' (0x1d): ADDR => D
|
| -`l_to_d' (0x1e): A => D
|
| -`d_to_l' (0x1f): D => A
|
| - Not implemented yet.
|
| -
|
| -`dup' (0x28): A => A A
|
| - Push another copy of the stack's top element.
|
| -
|
| -`swap' (0x2b): A B => B A
|
| - Exchange the top two items on the stack.
|
| -
|
| -`pop' (0x29): A =>
|
| - Discard the top value on the stack.
|
| -
|
| -`pick' (0x32) N: A ... B => A ... B A
|
| - Duplicate an item from the stack and push it on the top of the
|
| - stack. N, a single byte, indicates the stack item to copy. If N
|
| - is zero, this is the same as `dup'; if N is one, it copies the
|
| - item under the top item, etc. If N exceeds the number of items on
|
| - the stack, terminate with an error.
|
| -
|
| -`rot' (0x33): A B C => C B A
|
| - Rotate the top three items on the stack.
|
| -
|
| -`if_goto' (0x20) OFFSET: A =>
|
| - Pop an integer off the stack; if it is non-zero, branch to the
|
| - given offset in the bytecode string. Otherwise, continue to the
|
| - next instruction in the bytecode stream. In other words, if A is
|
| - non-zero, set the `pc' register to `start' + OFFSET. Thus, an
|
| - offset of zero denotes the beginning of the expression.
|
| -
|
| - The OFFSET is stored as a sixteen-bit unsigned value, stored
|
| - immediately following the `if_goto' bytecode. It is always stored
|
| - most significant byte first, regardless of the target's normal
|
| - endianness. The offset is not guaranteed to fall at any particular
|
| - alignment within the bytecode stream; thus, on machines where
|
| - fetching a 16-bit on an unaligned address raises an exception, you
|
| - should fetch the offset one byte at a time.
|
| -
|
| -`goto' (0x21) OFFSET: =>
|
| - Branch unconditionally to OFFSET; in other words, set the `pc'
|
| - register to `start' + OFFSET.
|
| -
|
| - The offset is stored in the same way as for the `if_goto' bytecode.
|
| -
|
| -`const8' (0x22) N: => N
|
| -`const16' (0x23) N: => N
|
| -`const32' (0x24) N: => N
|
| -`const64' (0x25) N: => N
|
| - Push the integer constant N on the stack, without sign extension.
|
| - To produce a small negative value, push a small twos-complement
|
| - value, and then sign-extend it using the `ext' bytecode.
|
| -
|
| - The constant N is stored in the appropriate number of bytes
|
| - following the `const'B bytecode. The constant N is always stored
|
| - most significant byte first, regardless of the target's normal
|
| - endianness. The constant is not guaranteed to fall at any
|
| - particular alignment within the bytecode stream; thus, on machines
|
| - where fetching a 16-bit on an unaligned address raises an
|
| - exception, you should fetch N one byte at a time.
|
| -
|
| -`reg' (0x26) N: => A
|
| - Push the value of register number N, without sign extension. The
|
| - registers are numbered following GDB's conventions.
|
| -
|
| - The register number N is encoded as a 16-bit unsigned integer
|
| - immediately following the `reg' bytecode. It is always stored most
|
| - significant byte first, regardless of the target's normal
|
| - endianness. The register number is not guaranteed to fall at any
|
| - particular alignment within the bytecode stream; thus, on machines
|
| - where fetching a 16-bit on an unaligned address raises an
|
| - exception, you should fetch the register number one byte at a time.
|
| -
|
| -`getv' (0x2c) N: => V
|
| - Push the value of trace state variable number N, without sign
|
| - extension.
|
| -
|
| - The variable number N is encoded as a 16-bit unsigned integer
|
| - immediately following the `getv' bytecode. It is always stored
|
| - most significant byte first, regardless of the target's normal
|
| - endianness. The variable number is not guaranteed to fall at any
|
| - particular alignment within the bytecode stream; thus, on machines
|
| - where fetching a 16-bit on an unaligned address raises an
|
| - exception, you should fetch the register number one byte at a time.
|
| -
|
| -`setv' (0x2d) N: => V
|
| - Set trace state variable number N to the value found on the top of
|
| - the stack. The stack is unchanged, so that the value is readily
|
| - available if the assignment is part of a larger expression. The
|
| - handling of N is as described for `getv'.
|
| -
|
| -`trace' (0x0c): ADDR SIZE =>
|
| - Record the contents of the SIZE bytes at ADDR in a trace buffer,
|
| - for later retrieval by GDB.
|
| -
|
| -`trace_quick' (0x0d) SIZE: ADDR => ADDR
|
| - Record the contents of the SIZE bytes at ADDR in a trace buffer,
|
| - for later retrieval by GDB. SIZE is a single byte unsigned
|
| - integer following the `trace' opcode.
|
| -
|
| - This bytecode is equivalent to the sequence `dup const8 SIZE
|
| - trace', but we provide it anyway to save space in bytecode strings.
|
| -
|
| -`trace16' (0x30) SIZE: ADDR => ADDR
|
| - Identical to trace_quick, except that SIZE is a 16-bit big-endian
|
| - unsigned integer, not a single byte. This should probably have
|
| - been named `trace_quick16', for consistency.
|
| -
|
| -`tracev' (0x2e) N: => A
|
| - Record the value of trace state variable number N in the trace
|
| - buffer. The handling of N is as described for `getv'.
|
| -
|
| -`tracenz' (0x2f) ADDR SIZE =>
|
| - Record the bytes at ADDR in a trace buffer, for later retrieval by
|
| - GDB. Stop at either the first zero byte, or when SIZE bytes have
|
| - been recorded, whichever occurs first.
|
| -
|
| -`printf' (0x34) NUMARGS STRING =>
|
| - Do a formatted print, in the style of the C function `printf').
|
| - The value of NUMARGS is the number of arguments to expect on the
|
| - stack, while STRING is the format string, prefixed with a two-byte
|
| - length. The last byte of the string must be zero, and is included
|
| - in the length. The format string includes escaped sequences just
|
| - as it appears in C source, so for instance the format string
|
| - `"\t%d\n"' is six characters long, and the output will consist of
|
| - a tab character, a decimal number, and a newline. At the top of
|
| - the stack, above the values to be printed, this bytecode will pop a
|
| - "function" and "channel". If the function is nonzero, then the
|
| - target may treat it as a function and call it, passing the channel
|
| - as a first argument, as with the C function `fprintf'. If the
|
| - function is zero, then the target may simply call a standard
|
| - formatted print function of its choice. In all, this bytecode
|
| - pops 2 + NUMARGS stack elements, and pushes nothing.
|
| -
|
| -`end' (0x27): =>
|
| - Stop executing bytecode; the result should be the top element of
|
| - the stack. If the purpose of the expression was to compute an
|
| - lvalue or a range of memory, then the next-to-top of the stack is
|
| - the lvalue's address, and the top of the stack is the lvalue's
|
| - size, in bytes.
|
| +Errors:
|
|
|
| + `EBADF'
|
| + FD is not a valid open file descriptor.
|
|
|
| -
|
| -File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions
|
| + `ESPIPE'
|
| + FD is associated with the GDB console.
|
|
|
| -F.3 Using Agent Expressions
|
| -===========================
|
| + `EINVAL'
|
| + FLAG is not a proper value.
|
|
|
| -Agent expressions can be used in several different ways by GDB, and the
|
| -debugger can generate different bytecode sequences as appropriate.
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| - One possibility is to do expression evaluation on the target rather
|
| -than the host, such as for the conditional of a conditional tracepoint.
|
| -In such a case, GDB compiles the source expression into a bytecode
|
| -sequence that simply gets values from registers or memory, does
|
| -arithmetic, and returns a result.
|
|
|
| - Another way to use agent expressions is for tracepoint data
|
| -collection. GDB generates a different bytecode sequence for
|
| -collection; in addition to bytecodes that do the calculation, GDB adds
|
| -`trace' bytecodes to save the pieces of memory that were used.
|
| +
|
| +File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
|
|
|
| - * The user selects trace points in the program's code at which GDB
|
| - should collect data.
|
| +rename
|
| +......
|
|
|
| - * The user specifies expressions to evaluate at each trace point.
|
| - These expressions may denote objects in memory, in which case
|
| - those objects' contents are recorded as the program runs, or
|
| - computed values, in which case the values themselves are recorded.
|
| +Synopsis:
|
| + int rename(const char *oldpath, const char *newpath);
|
|
|
| - * GDB transmits the tracepoints and their associated expressions to
|
| - the GDB agent, running on the debugging target.
|
| +Request:
|
| + `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
|
|
|
| - * The agent arranges to be notified when a trace point is hit.
|
| +Return value:
|
| + On success, zero is returned. On error, -1 is returned.
|
|
|
| - * When execution on the target reaches a trace point, the agent
|
| - evaluates the expressions associated with that trace point, and
|
| - records the resulting values and memory ranges.
|
| +Errors:
|
|
|
| - * Later, when the user selects a given trace event and inspects the
|
| - objects and expression values recorded, GDB talks to the agent to
|
| - retrieve recorded data as necessary to meet the user's requests.
|
| - If the user asks to see an object whose contents have not been
|
| - recorded, GDB reports an error.
|
| + `EISDIR'
|
| + NEWPATH is an existing directory, but OLDPATH is not a
|
| + directory.
|
|
|
| + `EEXIST'
|
| + NEWPATH is a non-empty directory.
|
|
|
| -
|
| -File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions
|
| + `EBUSY'
|
| + OLDPATH or NEWPATH is a directory that is in use by some
|
| + process.
|
|
|
| -F.4 Varying Target Capabilities
|
| -===============================
|
| + `EINVAL'
|
| + An attempt was made to make a directory a subdirectory of
|
| + itself.
|
|
|
| -Some targets don't support floating-point, and some would rather not
|
| -have to deal with `long long' operations. Also, different targets will
|
| -have different stack sizes, and different bytecode buffer lengths.
|
| + `ENOTDIR'
|
| + A component used as a directory in OLDPATH or new path is
|
| + not a directory. Or OLDPATH is a directory and NEWPATH
|
| + exists but is not a directory.
|
|
|
| - Thus, GDB needs a way to ask the target about itself. We haven't
|
| -worked out the details yet, but in general, GDB should be able to send
|
| -the target a packet asking it to describe itself. The reply should be a
|
| -packet whose length is explicit, so we can add new information to the
|
| -packet in future revisions of the agent, without confusing old versions
|
| -of GDB, and it should contain a version number. It should contain at
|
| -least the following information:
|
| + `EFAULT'
|
| + OLDPATHPTR or NEWPATHPTR are invalid pointer values.
|
|
|
| - * whether floating point is supported
|
| + `EACCES'
|
| + No access to the file or the path of the file.
|
|
|
| - * whether `long long' is supported
|
| + `ENAMETOOLONG'
|
| + OLDPATH or NEWPATH was too long.
|
|
|
| - * maximum acceptable size of bytecode stack
|
| + `ENOENT'
|
| + A directory component in OLDPATH or NEWPATH does not exist.
|
|
|
| - * maximum acceptable length of bytecode expressions
|
| + `EROFS'
|
| + The file is on a read-only filesystem.
|
|
|
| - * which registers are actually available for collection
|
| + `ENOSPC'
|
| + The device containing the file has no room for the new
|
| + directory entry.
|
|
|
| - * whether the target supports disabled tracepoints
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
|
|
|
|
| -File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions
|
| +File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
|
|
|
| -F.5 Rationale
|
| -=============
|
| +unlink
|
| +......
|
|
|
| -Some of the design decisions apparent above are arguable.
|
| -
|
| -What about stack overflow/underflow?
|
| - GDB should be able to query the target to discover its stack size.
|
| - Given that information, GDB can determine at translation time
|
| - whether a given expression will overflow the stack. But this spec
|
| - isn't about what kinds of error-checking GDB ought to do.
|
| -
|
| -Why are you doing everything in LONGEST?
|
| - Speed isn't important, but agent code size is; using LONGEST
|
| - brings in a bunch of support code to do things like division, etc.
|
| - So this is a serious concern.
|
| -
|
| - First, note that you don't need different bytecodes for different
|
| - operand sizes. You can generate code without _knowing_ how big the
|
| - stack elements actually are on the target. If the target only
|
| - supports 32-bit ints, and you don't send any 64-bit bytecodes,
|
| - everything just works. The observation here is that the MIPS and
|
| - the Alpha have only fixed-size registers, and you can still get
|
| - C's semantics even though most instructions only operate on
|
| - full-sized words. You just need to make sure everything is
|
| - properly sign-extended at the right times. So there is no need
|
| - for 32- and 64-bit variants of the bytecodes. Just implement
|
| - everything using the largest size you support.
|
| -
|
| - GDB should certainly check to see what sizes the target supports,
|
| - so the user can get an error earlier, rather than later. But this
|
| - information is not necessary for correctness.
|
| -
|
| -Why don't you have `>' or `<=' operators?
|
| - I want to keep the interpreter small, and we don't need them. We
|
| - can combine the `less_' opcodes with `log_not', and swap the order
|
| - of the operands, yielding all four asymmetrical comparison
|
| - operators. For example, `(x <= y)' is `! (x > y)', which is `! (y
|
| - < x)'.
|
| -
|
| -Why do you have `log_not'?
|
| -Why do you have `ext'?
|
| -Why do you have `zero_ext'?
|
| - These are all easily synthesized from other instructions, but I
|
| - expect them to be used frequently, and they're simple, so I
|
| - include them to keep bytecode strings short.
|
| -
|
| - `log_not' is equivalent to `const8 0 equal'; it's used in half the
|
| - relational operators.
|
| -
|
| - `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed',
|
| - where S is the size of the stack elements; it follows `refM' and
|
| - REG bytecodes when the value should be signed. See the next
|
| - bulleted item.
|
| -
|
| - `zero_ext N' is equivalent to `constM MASK log_and'; it's used
|
| - whenever we push the value of a register, because we can't assume
|
| - the upper bits of the register aren't garbage.
|
| -
|
| -Why not have sign-extending variants of the `ref' operators?
|
| - Because that would double the number of `ref' operators, and we
|
| - need the `ext' bytecode anyway for accessing bitfields.
|
| -
|
| -Why not have constant-address variants of the `ref' operators?
|
| - Because that would double the number of `ref' operators again, and
|
| - `const32 ADDRESS ref32' is only one byte longer.
|
| -
|
| -Why do the `refN' operators have to support unaligned fetches?
|
| - GDB will generate bytecode that fetches multi-byte values at
|
| - unaligned addresses whenever the executable's debugging
|
| - information tells it to. Furthermore, GDB does not know the value
|
| - the pointer will have when GDB generates the bytecode, so it
|
| - cannot determine whether a particular fetch will be aligned or not.
|
| -
|
| - In particular, structure bitfields may be several bytes long, but
|
| - follow no alignment rules; members of packed structures are not
|
| - necessarily aligned either.
|
| -
|
| - In general, there are many cases where unaligned references occur
|
| - in correct C code, either at the programmer's explicit request, or
|
| - at the compiler's discretion. Thus, it is simpler to make the GDB
|
| - agent bytecodes work correctly in all circumstances than to make
|
| - GDB guess in each case whether the compiler did the usual thing.
|
| -
|
| -Why are there no side-effecting operators?
|
| - Because our current client doesn't want them? That's a cheap
|
| - answer. I think the real answer is that I'm afraid of
|
| - implementing function calls. We should re-visit this issue after
|
| - the present contract is delivered.
|
| -
|
| -Why aren't the `goto' ops PC-relative?
|
| - The interpreter has the base address around anyway for PC bounds
|
| - checking, and it seemed simpler.
|
| -
|
| -Why is there only one offset size for the `goto' ops?
|
| - Offsets are currently sixteen bits. I'm not happy with this
|
| - situation either:
|
| -
|
| - Suppose we have multiple branch ops with different offset sizes.
|
| - As I generate code left-to-right, all my jumps are forward jumps
|
| - (there are no loops in expressions), so I never know the target
|
| - when I emit the jump opcode. Thus, I have to either always assume
|
| - the largest offset size, or do jump relaxation on the code after I
|
| - generate it, which seems like a big waste of time.
|
| -
|
| - I can imagine a reasonable expression being longer than 256 bytes.
|
| - I can't imagine one being longer than 64k. Thus, we need 16-bit
|
| - offsets. This kind of reasoning is so bogus, but relaxation is
|
| - pathetic.
|
| -
|
| - The other approach would be to generate code right-to-left. Then
|
| - I'd always know my offset size. That might be fun.
|
| -
|
| -Where is the function call bytecode?
|
| - When we add side-effects, we should add this.
|
| -
|
| -Why does the `reg' bytecode take a 16-bit register number?
|
| - Intel's IA-64 architecture has 128 general-purpose registers, and
|
| - 128 floating-point registers, and I'm sure it has some random
|
| - control registers.
|
| -
|
| -Why do we need `trace' and `trace_quick'?
|
| - Because GDB needs to record all the memory contents and registers
|
| - an expression touches. If the user wants to evaluate an expression
|
| - `x->y->z', the agent must record the values of `x' and `x->y' as
|
| - well as the value of `x->y->z'.
|
| -
|
| -Don't the `trace' bytecodes make the interpreter less general?
|
| - They do mean that the interpreter contains special-purpose code,
|
| - but that doesn't mean the interpreter can only be used for that
|
| - purpose. If an expression doesn't use the `trace' bytecodes, they
|
| - don't get in its way.
|
| -
|
| -Why doesn't `trace_quick' consume its arguments the way everything else does?
|
| - In general, you do want your operators to consume their arguments;
|
| - it's consistent, and generally reduces the amount of stack
|
| - rearrangement necessary. However, `trace_quick' is a kludge to
|
| - save space; it only exists so we needn't write `dup const8 SIZE
|
| - trace' before every memory reference. Therefore, it's okay for it
|
| - not to consume its arguments; it's meant for a specific context in
|
| - which we know exactly what it should do with the stack. If we're
|
| - going to have a kludge, it should be an effective kludge.
|
| -
|
| -Why does `trace16' exist?
|
| - That opcode was added by the customer that contracted Cygnus for
|
| - the data tracing work. I personally think it is unnecessary;
|
| - objects that large will be quite rare, so it is okay to use `dup
|
| - const16 SIZE trace' in those cases.
|
| -
|
| - Whatever we decide to do with `trace16', we should at least leave
|
| - opcode 0x30 reserved, to remain compatible with the customer who
|
| - added it.
|
| +Synopsis:
|
| + int unlink(const char *pathname);
|
|
|
| +Request:
|
| + `Funlink,PATHNAMEPTR/LEN'
|
|
|
| -
|
| -File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top
|
| +Return value:
|
| + On success, zero is returned. On error, -1 is returned.
|
|
|
| -Appendix G Target Descriptions
|
| -******************************
|
| +Errors:
|
|
|
| -One of the challenges of using GDB to debug embedded systems is that
|
| -there are so many minor variants of each processor architecture in use.
|
| -It is common practice for vendors to start with a standard processor
|
| -core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
|
| -adapt it to a particular market niche. Some architectures have
|
| -hundreds of variants, available from dozens of vendors. This leads to
|
| -a number of problems:
|
| + `EACCES'
|
| + No access to the file or the path of the file.
|
|
|
| - * With so many different customized processors, it is difficult for
|
| - the GDB maintainers to keep up with the changes.
|
| + `EPERM'
|
| + The system does not allow unlinking of directories.
|
|
|
| - * Since individual variants may have short lifetimes or limited
|
| - audiences, it may not be worthwhile to carry information about
|
| - every variant in the GDB source tree.
|
| + `EBUSY'
|
| + The file PATHNAME cannot be unlinked because it's being used
|
| + by another process.
|
|
|
| - * When GDB does support the architecture of the embedded system at
|
| - hand, the task of finding the correct architecture name to give the
|
| - `set architecture' command can be error-prone.
|
| + `EFAULT'
|
| + PATHNAMEPTR is an invalid pointer value.
|
|
|
| - To address these problems, the GDB remote protocol allows a target
|
| -system to not only identify itself to GDB, but to actually describe its
|
| -own features. This lets GDB support processor variants it has never
|
| -seen before -- to the extent that the descriptions are accurate, and
|
| -that GDB understands them.
|
| + `ENAMETOOLONG'
|
| + PATHNAME was too long.
|
|
|
| - GDB must be linked with the Expat library to support XML target
|
| -descriptions. *Note Expat::.
|
| + `ENOENT'
|
| + A directory component in PATHNAME does not exist.
|
|
|
| -* Menu:
|
| + `ENOTDIR'
|
| + A component of the path is not a directory.
|
| +
|
| + `EROFS'
|
| + The file is on a read-only filesystem.
|
| +
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| -* Retrieving Descriptions:: How descriptions are fetched from a target.
|
| -* Target Description Format:: The contents of a target description.
|
| -* Predefined Target Types:: Standard types available for target
|
| - descriptions.
|
| -* Standard Target Features:: Features GDB knows about.
|
|
|
|
|
| -File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions
|
| +File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
|
|
|
| -G.1 Retrieving Descriptions
|
| -===========================
|
| +stat/fstat
|
| +..........
|
|
|
| -Target descriptions can be read from the target automatically, or
|
| -specified by the user manually. The default behavior is to read the
|
| -description from the target. GDB retrieves it via the remote protocol
|
| -using `qXfer' requests (*note qXfer: General Query Packets.). The
|
| -ANNEX in the `qXfer' packet will be `target.xml'. The contents of the
|
| -`target.xml' annex are an XML document, of the form described in *Note
|
| -Target Description Format::.
|
| +Synopsis:
|
| + int stat(const char *pathname, struct stat *buf);
|
| + int fstat(int fd, struct stat *buf);
|
|
|
| - Alternatively, you can specify a file to read for the target
|
| -description. If a file is set, the target will not be queried. The
|
| -commands to specify a file are:
|
| +Request:
|
| + `Fstat,PATHNAMEPTR/LEN,BUFPTR'
|
| + `Ffstat,FD,BUFPTR'
|
|
|
| -`set tdesc filename PATH'
|
| - Read the target description from PATH.
|
| +Return value:
|
| + On success, zero is returned. On error, -1 is returned.
|
|
|
| -`unset tdesc filename'
|
| - Do not read the XML target description from a file. GDB will use
|
| - the description supplied by the current target.
|
| +Errors:
|
|
|
| -`show tdesc filename'
|
| - Show the filename to read for a target description, if any.
|
| + `EBADF'
|
| + FD is not a valid open file.
|
|
|
| -
|
| -File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions
|
| + `ENOENT'
|
| + A directory component in PATHNAME does not exist or the path
|
| + is an empty string.
|
|
|
| -G.2 Target Description Format
|
| -=============================
|
| + `ENOTDIR'
|
| + A component of the path is not a directory.
|
|
|
| -A target description annex is an XML (http://www.w3.org/XML/) document
|
| -which complies with the Document Type Definition provided in the GDB
|
| -sources in `gdb/features/gdb-target.dtd'. This means you can use
|
| -generally available tools like `xmllint' to check that your feature
|
| -descriptions are well-formed and valid. However, to help people
|
| -unfamiliar with XML write descriptions for their targets, we also
|
| -describe the grammar here.
|
| -
|
| - Target descriptions can identify the architecture of the remote
|
| -target and (for some architectures) provide information about custom
|
| -register sets. They can also identify the OS ABI of the remote target.
|
| -GDB can use this information to autoconfigure for your target, or to
|
| -warn you if you connect to an unsupported target.
|
| -
|
| - Here is a simple target description:
|
| -
|
| - <target version="1.0">
|
| - <architecture>i386:x86-64</architecture>
|
| - </target>
|
| -
|
| -This minimal description only says that the target uses the x86-64
|
| -architecture.
|
| -
|
| - A target description has the following overall form, with [ ] marking
|
| -optional elements and ... marking repeatable elements. The elements
|
| -are explained further below.
|
| -
|
| - <?xml version="1.0"?>
|
| - <!DOCTYPE target SYSTEM "gdb-target.dtd">
|
| - <target version="1.0">
|
| - [ARCHITECTURE]
|
| - [OSABI]
|
| - [COMPATIBLE]
|
| - [FEATURE...]
|
| - </target>
|
| -
|
| -The description is generally insensitive to whitespace and line breaks,
|
| -under the usual common-sense rules. The XML version declaration and
|
| -document type declaration can generally be omitted (GDB does not
|
| -require them), but specifying them may be useful for XML validation
|
| -tools. The `version' attribute for `<target>' may also be omitted, but
|
| -we recommend including it; if future versions of GDB use an incompatible
|
| -revision of `gdb-target.dtd', they will detect and report the version
|
| -mismatch.
|
| -
|
| -G.2.1 Inclusion
|
| ----------------
|
| -
|
| -It can sometimes be valuable to split a target description up into
|
| -several different annexes, either for organizational purposes, or to
|
| -share files between different possible target descriptions. You can
|
| -divide a description into multiple files by replacing any element of
|
| -the target description with an inclusion directive of the form:
|
| -
|
| - <xi:include href="DOCUMENT"/>
|
| -
|
| -When GDB encounters an element of this form, it will retrieve the named
|
| -XML DOCUMENT, and replace the inclusion directive with the contents of
|
| -that document. If the current description was read using `qXfer', then
|
| -so will be the included document; DOCUMENT will be interpreted as the
|
| -name of an annex. If the current description was read from a file, GDB
|
| -will look for DOCUMENT as a file in the same directory where it found
|
| -the original description.
|
| -
|
| -G.2.2 Architecture
|
| -------------------
|
| + `EFAULT'
|
| + PATHNAMEPTR is an invalid pointer value.
|
|
|
| -An `<architecture>' element has this form:
|
| + `EACCES'
|
| + No access to the file or the path of the file.
|
|
|
| - <architecture>ARCH</architecture>
|
| + `ENAMETOOLONG'
|
| + PATHNAME was too long.
|
|
|
| - ARCH is one of the architectures from the set accepted by `set
|
| -architecture' (*note Specifying a Debugging Target: Targets.).
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| -G.2.3 OS ABI
|
| -------------
|
|
|
| -This optional field was introduced in GDB version 7.0. Previous
|
| -versions of GDB ignore it.
|
| +
|
| +File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
|
|
|
| - An `<osabi>' element has this form:
|
| +gettimeofday
|
| +............
|
|
|
| - <osabi>ABI-NAME</osabi>
|
| +Synopsis:
|
| + int gettimeofday(struct timeval *tv, void *tz);
|
|
|
| - ABI-NAME is an OS ABI name from the same selection accepted by
|
| -`set osabi' (*note Configuring the Current ABI: ABI.).
|
| +Request:
|
| + `Fgettimeofday,TVPTR,TZPTR'
|
|
|
| -G.2.4 Compatible Architecture
|
| ------------------------------
|
| +Return value:
|
| + On success, 0 is returned, -1 otherwise.
|
|
|
| -This optional field was introduced in GDB version 7.0. Previous
|
| -versions of GDB ignore it.
|
| +Errors:
|
|
|
| - A `<compatible>' element has this form:
|
| + `EINVAL'
|
| + TZ is a non-NULL pointer.
|
|
|
| - <compatible>ARCH</compatible>
|
| + `EFAULT'
|
| + TVPTR and/or TZPTR is an invalid pointer value.
|
|
|
| - ARCH is one of the architectures from the set accepted by `set
|
| -architecture' (*note Specifying a Debugging Target: Targets.).
|
|
|
| - A `<compatible>' element is used to specify that the target is able
|
| -to run binaries in some other than the main target architecture given
|
| -by the `<architecture>' element. For example, on the Cell Broadband
|
| -Engine, the main architecture is `powerpc:common' or
|
| -`powerpc:common64', but the system is able to run binaries in the `spu'
|
| -architecture as well. The way to describe this capability with
|
| -`<compatible>' is as follows:
|
| +
|
| +File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
|
|
|
| - <architecture>powerpc:common</architecture>
|
| - <compatible>spu</compatible>
|
| +isatty
|
| +......
|
|
|
| -G.2.5 Features
|
| ---------------
|
| +Synopsis:
|
| + int isatty(int fd);
|
|
|
| -Each `<feature>' describes some logical portion of the target system.
|
| -Features are currently used to describe available CPU registers and the
|
| -types of their contents. A `<feature>' element has this form:
|
| +Request:
|
| + `Fisatty,FD'
|
|
|
| - <feature name="NAME">
|
| - [TYPE...]
|
| - REG...
|
| - </feature>
|
| +Return value:
|
| + Returns 1 if FD refers to the GDB console, 0 otherwise.
|
|
|
| -Each feature's name should be unique within the description. The name
|
| -of a feature does not matter unless GDB has some special knowledge of
|
| -the contents of that feature; if it does, the feature should have its
|
| -standard name. *Note Standard Target Features::.
|
| +Errors:
|
|
|
| -G.2.6 Types
|
| ------------
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| -Any register's value is a collection of bits which GDB must interpret.
|
| -The default interpretation is a two's complement integer, but other
|
| -types can be requested by name in the register description. Some
|
| -predefined types are provided by GDB (*note Predefined Target Types::),
|
| -and the description can define additional composite types.
|
| -
|
| - Each type element must have an `id' attribute, which gives a unique
|
| -(within the containing `<feature>') name to the type. Types must be
|
| -defined before they are used.
|
| -
|
| - Some targets offer vector registers, which can be treated as arrays
|
| -of scalar elements. These types are written as `<vector>' elements,
|
| -specifying the array element type, TYPE, and the number of elements,
|
| -COUNT:
|
| -
|
| - <vector id="ID" type="TYPE" count="COUNT"/>
|
| -
|
| - If a register's value is usefully viewed in multiple ways, define it
|
| -with a union type containing the useful representations. The `<union>'
|
| -element contains one or more `<field>' elements, each of which has a
|
| -NAME and a TYPE:
|
| -
|
| - <union id="ID">
|
| - <field name="NAME" type="TYPE"/>
|
| - ...
|
| - </union>
|
| -
|
| - If a register's value is composed from several separate values,
|
| -define it with a structure type. There are two forms of the `<struct>'
|
| -element; a `<struct>' element must either contain only bitfields or
|
| -contain no bitfields. If the structure contains only bitfields, its
|
| -total size in bytes must be specified, each bitfield must have an
|
| -explicit start and end, and bitfields are automatically assigned an
|
| -integer type. The field's START should be less than or equal to its
|
| -END, and zero represents the least significant bit.
|
| -
|
| - <struct id="ID" size="SIZE">
|
| - <field name="NAME" start="START" end="END"/>
|
| - ...
|
| - </struct>
|
| -
|
| - If the structure contains no bitfields, then each field has an
|
| -explicit type, and no implicit padding is added.
|
| -
|
| - <struct id="ID">
|
| - <field name="NAME" type="TYPE"/>
|
| - ...
|
| - </struct>
|
| -
|
| - If a register's value is a series of single-bit flags, define it with
|
| -a flags type. The `<flags>' element has an explicit SIZE and contains
|
| -one or more `<field>' elements. Each field has a NAME, a START, and an
|
| -END. Only single-bit flags are supported.
|
| -
|
| - <flags id="ID" size="SIZE">
|
| - <field name="NAME" start="START" end="END"/>
|
| - ...
|
| - </flags>
|
| -
|
| -G.2.7 Registers
|
| ----------------
|
| -
|
| -Each register is represented as an element with this form:
|
| -
|
| - <reg name="NAME"
|
| - bitsize="SIZE"
|
| - [regnum="NUM"]
|
| - [save-restore="SAVE-RESTORE"]
|
| - [type="TYPE"]
|
| - [group="GROUP"]/>
|
| -
|
| -The components are as follows:
|
| -
|
| -NAME
|
| - The register's name; it must be unique within the target
|
| - description.
|
| -
|
| -BITSIZE
|
| - The register's size, in bits.
|
| -
|
| -REGNUM
|
| - The register's number. If omitted, a register's number is one
|
| - greater than that of the previous register (either in the current
|
| - feature or in a preceding feature); the first register in the
|
| - target description defaults to zero. This register number is used
|
| - to read or write the register; e.g. it is used in the remote `p'
|
| - and `P' packets, and registers appear in the `g' and `G' packets
|
| - in order of increasing register number.
|
| -
|
| -SAVE-RESTORE
|
| - Whether the register should be preserved across inferior function
|
| - calls; this must be either `yes' or `no'. The default is `yes',
|
| - which is appropriate for most registers except for some system
|
| - control registers; this is not related to the target's ABI.
|
| -
|
| -TYPE
|
| - The type of the register. TYPE may be a predefined type, a type
|
| - defined in the current feature, or one of the special types `int'
|
| - and `float'. `int' is an integer type of the correct size for
|
| - BITSIZE, and `float' is a floating point type (in the
|
| - architecture's normal floating point format) of the correct size
|
| - for BITSIZE. The default is `int'.
|
| -
|
| -GROUP
|
| - The register group to which this register belongs. GROUP must be
|
| - either `general', `float', or `vector'. If no GROUP is specified,
|
| - GDB will not display the register in `info registers'.
|
|
|
| + Note that the `isatty' call is treated as a special case: it returns
|
| +1 to the target if the file descriptor is attached to the GDB console,
|
| +0 otherwise. Implementing through system calls would require
|
| +implementing `ioctl' and would be more complex than needed.
|
|
|
|
|
| -File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions
|
| -
|
| -G.3 Predefined Target Types
|
| -===========================
|
| +File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
|
|
|
| -Type definitions in the self-description can build up composite types
|
| -from basic building blocks, but can not define fundamental types.
|
| -Instead, standard identifiers are provided by GDB for the fundamental
|
| -types. The currently supported types are:
|
| +system
|
| +......
|
|
|
| -`int8'
|
| -`int16'
|
| -`int32'
|
| -`int64'
|
| -`int128'
|
| - Signed integer types holding the specified number of bits.
|
| +Synopsis:
|
| + int system(const char *command);
|
|
|
| -`uint8'
|
| -`uint16'
|
| -`uint32'
|
| -`uint64'
|
| -`uint128'
|
| - Unsigned integer types holding the specified number of bits.
|
| +Request:
|
| + `Fsystem,COMMANDPTR/LEN'
|
|
|
| -`code_ptr'
|
| -`data_ptr'
|
| - Pointers to unspecified code and data. The program counter and
|
| - any dedicated return address register may be marked as code
|
| - pointers; printing a code pointer converts it into a symbolic
|
| - address. The stack pointer and any dedicated address registers
|
| - may be marked as data pointers.
|
| +Return value:
|
| + If LEN is zero, the return value indicates whether a shell is
|
| + available. A zero return value indicates a shell is not available.
|
| + For non-zero LEN, the value returned is -1 on error and the return
|
| + status of the command otherwise. Only the exit status of the
|
| + command is returned, which is extracted from the host's `system'
|
| + return value by calling `WEXITSTATUS(retval)'. In case `/bin/sh'
|
| + could not be executed, 127 is returned.
|
|
|
| -`ieee_single'
|
| - Single precision IEEE floating point.
|
| +Errors:
|
|
|
| -`ieee_double'
|
| - Double precision IEEE floating point.
|
| + `EINTR'
|
| + The call was interrupted by the user.
|
|
|
| -`arm_fpa_ext'
|
| - The 12-byte extended precision format used by ARM FPA registers.
|
|
|
| -`i387_ext'
|
| - The 10-byte extended precision format used by x87 registers.
|
| + GDB takes over the full task of calling the necessary host calls to
|
| +perform the `system' call. The return value of `system' on the host is
|
| +simplified before it's returned to the target. Any termination signal
|
| +information from the child process is discarded, and the return value
|
| +consists entirely of the exit status of the called command.
|
|
|
| -`i386_eflags'
|
| - 32bit EFLAGS register used by x86.
|
| + Due to security concerns, the `system' call is by default refused by
|
| +GDB. The user has to allow this call explicitly with the `set remote
|
| +system-call-allowed 1' command.
|
|
|
| -`i386_mxcsr'
|
| - 32bit MXCSR register used by x86.
|
| +`set remote system-call-allowed'
|
| + Control whether to allow the `system' calls in the File I/O
|
| + protocol for the remote target. The default is zero (disabled).
|
|
|
| +`show remote system-call-allowed'
|
| + Show whether the `system' calls are allowed in the File I/O
|
| + protocol.
|
|
|
|
|
| -File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions
|
| -
|
| -G.4 Standard Target Features
|
| -============================
|
| -
|
| -A target description must contain either no registers or all the
|
| -target's registers. If the description contains no registers, then GDB
|
| -will assume a default register layout, selected based on the
|
| -architecture. If the description contains any registers, the default
|
| -layout will not be used; the standard registers must be described in
|
| -the target description, in such a way that GDB can recognize them.
|
| -
|
| - This is accomplished by giving specific names to feature elements
|
| -which contain standard registers. GDB will look for features with
|
| -those names and verify that they contain the expected registers; if any
|
| -known feature is missing required registers, or if any required feature
|
| -is missing, GDB will reject the target description. You can add
|
| -additional registers to any of the standard features -- GDB will
|
| -display them just as if they were added to an unrecognized feature.
|
| -
|
| - This section lists the known features and their expected contents.
|
| -Sample XML documents for these features are included in the GDB source
|
| -tree, in the directory `gdb/features'.
|
| -
|
| - Names recognized by GDB should include the name of the company or
|
| -organization which selected the name, and the overall architecture to
|
| -which the feature applies; so e.g. the feature containing ARM core
|
| -registers is named `org.gnu.gdb.arm.core'.
|
| -
|
| - The names of registers are not case sensitive for the purpose of
|
| -recognizing standard features, but GDB will only display registers
|
| -using the capitalization used in the description.
|
| +File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
|
| +
|
| +E.13.8 Protocol-specific Representation of Datatypes
|
| +----------------------------------------------------
|
|
|
| * Menu:
|
|
|
| -* ARM Features::
|
| -* i386 Features::
|
| -* MIPS Features::
|
| -* M68K Features::
|
| -* PowerPC Features::
|
| -* TIC6x Features::
|
| +* Integral Datatypes::
|
| +* Pointer Values::
|
| +* Memory Transfer::
|
| +* struct stat::
|
| +* struct timeval::
|
|
|
|
|
| -File: gdb.info, Node: ARM Features, Next: i386 Features, Up: Standard Target Features
|
| +File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
|
|
| -G.4.1 ARM Features
|
| -------------------
|
| +Integral Datatypes
|
| +..................
|
|
|
| -The `org.gnu.gdb.arm.core' feature is required for non-M-profile ARM
|
| -targets. It should contain registers `r0' through `r13', `sp', `lr',
|
| -`pc', and `cpsr'.
|
| +The integral datatypes used in the system calls are `int', `unsigned
|
| +int', `long', `unsigned long', `mode_t', and `time_t'.
|
|
|
| - For M-profile targets (e.g. Cortex-M3), the `org.gnu.gdb.arm.core'
|
| -feature is replaced by `org.gnu.gdb.arm.m-profile'. It should contain
|
| -registers `r0' through `r13', `sp', `lr', `pc', and `xpsr'.
|
| + `int', `unsigned int', `mode_t' and `time_t' are implemented as 32
|
| +bit values in this protocol.
|
|
|
| - The `org.gnu.gdb.arm.fpa' feature is optional. If present, it
|
| -should contain registers `f0' through `f7' and `fps'.
|
| + `long' and `unsigned long' are implemented as 64 bit types.
|
|
|
| - The `org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it
|
| -should contain at least registers `wR0' through `wR15' and `wCGR0'
|
| -through `wCGR3'. The `wCID', `wCon', `wCSSF', and `wCASF' registers
|
| -are optional.
|
| + *Note Limits::, for corresponding MIN and MAX values (similar to
|
| +those in `limits.h') to allow range checking on host and target.
|
|
|
| - The `org.gnu.gdb.arm.vfp' feature is optional. If present, it
|
| -should contain at least registers `d0' through `d15'. If they are
|
| -present, `d16' through `d31' should also be included. GDB will
|
| -synthesize the single-precision registers from halves of the
|
| -double-precision registers.
|
| + `time_t' datatypes are defined as seconds since the Epoch.
|
|
|
| - The `org.gnu.gdb.arm.neon' feature is optional. It does not need to
|
| -contain registers; it instructs GDB to display the VFP double-precision
|
| -registers as vectors and to synthesize the quad-precision registers
|
| -from pairs of double-precision registers. If this feature is present,
|
| -`org.gnu.gdb.arm.vfp' must also be present and include 32
|
| -double-precision registers.
|
| + All integral datatypes transferred as part of a memory read or write
|
| +of a structured datatype e.g. a `struct stat' have to be given in big
|
| +endian byte order.
|
|
|
|
|
| -File: gdb.info, Node: i386 Features, Next: MIPS Features, Prev: ARM Features, Up: Standard Target Features
|
| -
|
| -G.4.2 i386 Features
|
| --------------------
|
| -
|
| -The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.
|
| -It should describe the following registers:
|
| +File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
|
|
|
| - - `eax' through `edi' plus `eip' for i386
|
| +Pointer Values
|
| +..............
|
|
|
| - - `rax' through `r15' plus `rip' for amd64
|
| +Pointers to target data are transmitted as they are. An exception is
|
| +made for pointers to buffers for which the length isn't transmitted as
|
| +part of the function call, namely strings. Strings are transmitted as
|
| +a pointer/length pair, both as hex values, e.g.
|
|
|
| - - `eflags', `cs', `ss', `ds', `es', `fs', `gs'
|
| + `1aaf/12'
|
|
|
| - - `st0' through `st7'
|
| +which is a pointer to data of length 18 bytes at position 0x1aaf. The
|
| +length is defined as the full string length in bytes, including the
|
| +trailing null byte. For example, the string `"hello world"' at address
|
| +0x123456 is transmitted as
|
|
|
| - - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and
|
| - `fop'
|
| + `123456/d'
|
|
|
| - The register sets may be different, depending on the target.
|
| +
|
| +File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
|
|
|
| - The `org.gnu.gdb.i386.sse' feature is optional. It should describe
|
| -registers:
|
| +Memory Transfer
|
| +...............
|
|
|
| - - `xmm0' through `xmm7' for i386
|
| +Structured data which is transferred using a memory read or write (for
|
| +example, a `struct stat') is expected to be in a protocol-specific
|
| +format with all scalar multibyte datatypes being big endian.
|
| +Translation to this representation needs to be done both by the target
|
| +before the `F' packet is sent, and by GDB before it transfers memory to
|
| +the target. Transferred pointers to structured data should point to
|
| +the already-coerced data at any time.
|
|
|
| - - `xmm0' through `xmm15' for amd64
|
| +
|
| +File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
|
|
|
| - - `mxcsr'
|
| +struct stat
|
| +...........
|
|
|
| - The `org.gnu.gdb.i386.avx' feature is optional and requires the
|
| -`org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits
|
| -of YMM registers:
|
| +The buffer of type `struct stat' used by the target and GDB is defined
|
| +as follows:
|
|
|
| - - `ymm0h' through `ymm7h' for i386
|
| + struct stat {
|
| + unsigned int st_dev; /* device */
|
| + unsigned int st_ino; /* inode */
|
| + mode_t st_mode; /* protection */
|
| + unsigned int st_nlink; /* number of hard links */
|
| + unsigned int st_uid; /* user ID of owner */
|
| + unsigned int st_gid; /* group ID of owner */
|
| + unsigned int st_rdev; /* device type (if inode device) */
|
| + unsigned long st_size; /* total size, in bytes */
|
| + unsigned long st_blksize; /* blocksize for filesystem I/O */
|
| + unsigned long st_blocks; /* number of blocks allocated */
|
| + time_t st_atime; /* time of last access */
|
| + time_t st_mtime; /* time of last modification */
|
| + time_t st_ctime; /* time of last change */
|
| + };
|
|
|
| - - `ymm0h' through `ymm15h' for amd64
|
| + The integral datatypes conform to the definitions given in the
|
| +appropriate section (see *note Integral Datatypes::, for details) so
|
| +this structure is of size 64 bytes.
|
|
|
| - The `org.gnu.gdb.i386.linux' feature is optional. It should
|
| -describe a single register, `orig_eax'.
|
| + The values of several fields have a restricted meaning and/or range
|
| +of values.
|
|
|
| -
|
| -File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: i386 Features, Up: Standard Target Features
|
| +`st_dev'
|
| + A value of 0 represents a file, 1 the console.
|
|
|
| -G.4.3 MIPS Features
|
| --------------------
|
| +`st_ino'
|
| + No valid meaning for the target. Transmitted unchanged.
|
|
|
| -The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It
|
| -should contain registers `r0' through `r31', `lo', `hi', and `pc'.
|
| -They may be 32-bit or 64-bit depending on the target.
|
| +`st_mode'
|
| + Valid mode bits are described in *note Constants::. Any other
|
| + bits have currently no meaning for the target.
|
|
|
| - The `org.gnu.gdb.mips.cp0' feature is also required. It should
|
| -contain at least the `status', `badvaddr', and `cause' registers. They
|
| -may be 32-bit or 64-bit depending on the target.
|
| +`st_uid'
|
| +`st_gid'
|
| +`st_rdev'
|
| + No valid meaning for the target. Transmitted unchanged.
|
|
|
| - The `org.gnu.gdb.mips.fpu' feature is currently required, though it
|
| -may be optional in a future version of GDB. It should contain
|
| -registers `f0' through `f31', `fcsr', and `fir'. They may be 32-bit or
|
| -64-bit depending on the target.
|
| +`st_atime'
|
| +`st_mtime'
|
| +`st_ctime'
|
| + These values have a host and file system dependent accuracy.
|
| + Especially on Windows hosts, the file system may not support exact
|
| + timing values.
|
|
|
| - The `org.gnu.gdb.mips.dsp' feature is optional. It should contain
|
| -registers `hi1' through `hi3', `lo1' through `lo3', and `dspctl'. The
|
| -`dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit
|
| -depending on the target.
|
| + The target gets a `struct stat' of the above representation and is
|
| +responsible for coercing it to the target representation before
|
| +continuing.
|
|
|
| - The `org.gnu.gdb.mips.linux' feature is optional. It should contain
|
| -a single register, `restart', which is used by the Linux kernel to
|
| -control restartable syscalls.
|
| + Note that due to size differences between the host, target, and
|
| +protocol representations of `struct stat' members, these members could
|
| +eventually get truncated on the target.
|
|
|
|
|
| -File: gdb.info, Node: M68K Features, Next: PowerPC Features, Prev: MIPS Features, Up: Standard Target Features
|
| -
|
| -G.4.4 M68K Features
|
| --------------------
|
| +File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
|
|
|
| -``org.gnu.gdb.m68k.core''
|
| -``org.gnu.gdb.coldfire.core''
|
| -``org.gnu.gdb.fido.core''
|
| - One of those features must be always present. The feature that is
|
| - present determines which flavor of m68k is used. The feature that
|
| - is present should contain registers `d0' through `d7', `a0'
|
| - through `a5', `fp', `sp', `ps' and `pc'.
|
| +struct timeval
|
| +..............
|
|
|
| -``org.gnu.gdb.coldfire.fp''
|
| - This feature is optional. If present, it should contain registers
|
| - `fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'.
|
| +The buffer of type `struct timeval' used by the File-I/O protocol is
|
| +defined as follows:
|
|
|
| -
|
| -File: gdb.info, Node: PowerPC Features, Next: TIC6x Features, Prev: M68K Features, Up: Standard Target Features
|
| + struct timeval {
|
| + time_t tv_sec; /* second */
|
| + long tv_usec; /* microsecond */
|
| + };
|
|
|
| -G.4.5 PowerPC Features
|
| -----------------------
|
| + The integral datatypes conform to the definitions given in the
|
| +appropriate section (see *note Integral Datatypes::, for details) so
|
| +this structure is of size 8 bytes.
|
|
|
| -The `org.gnu.gdb.power.core' feature is required for PowerPC targets.
|
| -It should contain registers `r0' through `r31', `pc', `msr', `cr',
|
| -`lr', `ctr', and `xer'. They may be 32-bit or 64-bit depending on the
|
| -target.
|
| +
|
| +File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
|
|
|
| - The `org.gnu.gdb.power.fpu' feature is optional. It should contain
|
| -registers `f0' through `f31' and `fpscr'.
|
| +E.13.9 Constants
|
| +----------------
|
|
|
| - The `org.gnu.gdb.power.altivec' feature is optional. It should
|
| -contain registers `vr0' through `vr31', `vscr', and `vrsave'.
|
| +The following values are used for the constants inside of the protocol.
|
| +GDB and target are responsible for translating these values before and
|
| +after the call as needed.
|
|
|
| - The `org.gnu.gdb.power.vsx' feature is optional. It should contain
|
| -registers `vs0h' through `vs31h'. GDB will combine these registers
|
| -with the floating point registers (`f0' through `f31') and the altivec
|
| -registers (`vr0' through `vr31') to present the 128-bit wide registers
|
| -`vs0' through `vs63', the set of vector registers for POWER7.
|
| +* Menu:
|
|
|
| - The `org.gnu.gdb.power.spe' feature is optional. It should contain
|
| -registers `ev0h' through `ev31h', `acc', and `spefscr'. SPE targets
|
| -should provide 32-bit registers in `org.gnu.gdb.power.core' and provide
|
| -the upper halves in `ev0h' through `ev31h'. GDB will combine these to
|
| -present registers `ev0' through `ev31' to the user.
|
| +* Open Flags::
|
| +* mode_t Values::
|
| +* Errno Values::
|
| +* Lseek Flags::
|
| +* Limits::
|
|
|
|
|
| -File: gdb.info, Node: TIC6x Features, Prev: PowerPC Features, Up: Standard Target Features
|
| -
|
| -G.4.6 TMS320C6x Features
|
| -------------------------
|
| +File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
|
|
|
| -The `org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets.
|
| -It should contain registers `A0' through `A15', registers `B0' through
|
| -`B15', `CSR' and `PC'.
|
| +Open Flags
|
| +..........
|
|
|
| - The `org.gnu.gdb.tic6x.gp' feature is optional. It should contain
|
| -registers `A16' through `A31' and `B16' through `B31'.
|
| +All values are given in hexadecimal representation.
|
|
|
| - The `org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain
|
| -registers `TSR', `ILC' and `RILC'.
|
| + O_RDONLY 0x0
|
| + O_WRONLY 0x1
|
| + O_RDWR 0x2
|
| + O_APPEND 0x8
|
| + O_CREAT 0x200
|
| + O_TRUNC 0x400
|
| + O_EXCL 0x800
|
|
|
|
|
| -File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top
|
| -
|
| -Appendix H Operating System Information
|
| -***************************************
|
| -
|
| -* Menu:
|
| +File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
|
|
|
| -* Process list::
|
| +mode_t Values
|
| +.............
|
|
|
| - Users of GDB often wish to obtain information about the state of the
|
| -operating system running on the target--for example the list of
|
| -processes, or the list of open files. This section describes the
|
| -mechanism that makes it possible. This mechanism is similar to the
|
| -target features mechanism (*note Target Descriptions::), but focuses on
|
| -a different aspect of target.
|
| +All values are given in octal representation.
|
|
|
| - Operating system information is retrived from the target via the
|
| -remote protocol, using `qXfer' requests (*note qXfer osdata read::).
|
| -The object name in the request should be `osdata', and the ANNEX
|
| -identifies the data to be fetched.
|
| + S_IFREG 0100000
|
| + S_IFDIR 040000
|
| + S_IRUSR 0400
|
| + S_IWUSR 0200
|
| + S_IXUSR 0100
|
| + S_IRGRP 040
|
| + S_IWGRP 020
|
| + S_IXGRP 010
|
| + S_IROTH 04
|
| + S_IWOTH 02
|
| + S_IXOTH 01
|
|
|
|
|
| -File: gdb.info, Node: Process list, Up: Operating System Information
|
| -
|
| -H.1 Process list
|
| -================
|
| -
|
| -When requesting the process list, the ANNEX field in the `qXfer'
|
| -request should be `processes'. The returned data is an XML document.
|
| -The formal syntax of this document is defined in
|
| -`gdb/features/osdata.dtd'.
|
| -
|
| - An example document is:
|
| -
|
| - <?xml version="1.0"?>
|
| - <!DOCTYPE target SYSTEM "osdata.dtd">
|
| - <osdata type="processes">
|
| - <item>
|
| - <column name="pid">1</column>
|
| - <column name="user">root</column>
|
| - <column name="command">/sbin/init</column>
|
| - <column name="cores">1,2,3</column>
|
| - </item>
|
| - </osdata>
|
| -
|
| - Each item should include a column whose name is `pid'. The value of
|
| -that column should identify the process on the target. The `user' and
|
| -`command' columns are optional, and will be displayed by GDB. The
|
| -`cores' column, if present, should contain a comma-separated list of
|
| -cores that this process is running on. Target may provide additional
|
| -columns, which GDB currently ignores.
|
| +File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
|
|
|
| -
|
| -File: gdb.info, Node: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top
|
| +Errno Values
|
| +............
|
|
|
| -Appendix I Trace File Format
|
| -****************************
|
| +All values are given in decimal representation.
|
|
|
| -The trace file comes in three parts: a header, a textual description
|
| -section, and a trace frame section with binary data.
|
| + EPERM 1
|
| + ENOENT 2
|
| + EINTR 4
|
| + EBADF 9
|
| + EACCES 13
|
| + EFAULT 14
|
| + EBUSY 16
|
| + EEXIST 17
|
| + ENODEV 19
|
| + ENOTDIR 20
|
| + EISDIR 21
|
| + EINVAL 22
|
| + ENFILE 23
|
| + EMFILE 24
|
| + EFBIG 27
|
| + ENOSPC 28
|
| + ESPIPE 29
|
| + EROFS 30
|
| + ENAMETOOLONG 91
|
| + EUNKNOWN 9999
|
|
|
| - The header has the form `\x7fTRACE0\n'. The first byte is `0x7f' so
|
| -as to indicate that the file contains binary data, while the `0' is a
|
| -version number that may have different values in the future.
|
| + `EUNKNOWN' is used as a fallback error value if a host system returns
|
| + any error value not in the list of supported error numbers.
|
|
|
| - The description section consists of multiple lines of ASCII text
|
| -separated by newline characters (`0xa'). The lines may include a
|
| -variety of optional descriptive or context-setting information, such as
|
| -tracepoint definitions or register set size. GDB will ignore any line
|
| -that it does not recognize. An empty line marks the end of this
|
| -section.
|
| +
|
| +File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
|
|
|
| - The trace frame section consists of a number of consecutive frames.
|
| -Each frame begins with a two-byte tracepoint number, followed by a
|
| -four-byte size giving the amount of data in the frame. The data in the
|
| -frame consists of a number of blocks, each introduced by a character
|
| -indicating its type (at least register, memory, and trace state
|
| -variable). The data in this section is raw binary, not a hexadecimal
|
| -or other encoding; its endianness matches the target's endianness.
|
| +Lseek Flags
|
| +...........
|
|
|
| -`R BYTES'
|
| - Register block. The number and ordering of bytes matches that of a
|
| - `g' packet in the remote protocol. Note that these are the actual
|
| - bytes, in target order and GDB register order, not a hexadecimal
|
| - encoding.
|
| + SEEK_SET 0
|
| + SEEK_CUR 1
|
| + SEEK_END 2
|
|
|
| -`M ADDRESS LENGTH BYTES...'
|
| - Memory block. This is a contiguous block of memory, at the 8-byte
|
| - address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH
|
| - bytes.
|
| +
|
| +File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
|
|
|
| -`V NUMBER VALUE'
|
| - Trace state variable block. This records the 8-byte signed value
|
| - VALUE of trace state variable numbered NUMBER.
|
| +Limits
|
| +......
|
|
|
| +All values are given in decimal representation.
|
|
|
| - Future enhancements of the trace file format may include additional
|
| -types of blocks.
|
| + INT_MIN -2147483648
|
| + INT_MAX 2147483647
|
| + UINT_MAX 4294967295
|
| + LONG_MIN -9223372036854775808
|
| + LONG_MAX 9223372036854775807
|
| + ULONG_MAX 18446744073709551615
|
|
|
|
|
| -File: gdb.info, Node: Index Section Format, Next: Copying, Prev: Trace File Format, Up: Top
|
| -
|
| -Appendix J `.gdb_index' section format
|
| -**************************************
|
| -
|
| -This section documents the index section that is created by `save
|
| -gdb-index' (*note Index Files::). The index section is DWARF-specific;
|
| -some knowledge of DWARF is assumed in this description.
|
| +File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
|
|
|
| - The mapped index file format is designed to be directly `mmap'able
|
| -on any architecture. In most cases, a datum is represented using a
|
| -little-endian 32-bit integer value, called an `offset_type'. Big
|
| -endian machines must byte-swap the values before using them.
|
| -Exceptions to this rule are noted. The data is laid out such that
|
| -alignment is always respected.
|
| +E.13.10 File-I/O Examples
|
| +-------------------------
|
|
|
| - A mapped index consists of several areas, laid out in order.
|
| +Example sequence of a write call, file descriptor 3, buffer is at target
|
| +address 0x1234, 6 bytes should be written:
|
|
|
| - 1. The file header. This is a sequence of values, of `offset_type'
|
| - unless otherwise noted:
|
| + <- `Fwrite,3,1234,6'
|
| + _request memory read from target_
|
| + -> `m1234,6'
|
| + <- XXXXXX
|
| + _return "6 bytes written"_
|
| + -> `F6'
|
|
|
| - 1. The version number, currently 7. Versions 1, 2 and 3 are
|
| - obsolete. Version 4 uses a different hashing function from
|
| - versions 5 and 6. Version 6 includes symbols for inlined
|
| - functions, whereas versions 4 and 5 do not. Version 7 adds
|
| - attributes to the CU indices in the symbol table. GDB will
|
| - only read version 4, 5, or 6 indices by specifying `set
|
| - use-deprecated-index-sections on'.
|
| + Example sequence of a read call, file descriptor 3, buffer is at
|
| +target address 0x1234, 6 bytes should be read:
|
|
|
| - 2. The offset, from the start of the file, of the CU list.
|
| + <- `Fread,3,1234,6'
|
| + _request memory write to target_
|
| + -> `X1234,6:XXXXXX'
|
| + _return "6 bytes read"_
|
| + -> `F6'
|
|
|
| - 3. The offset, from the start of the file, of the types CU list.
|
| - Note that this area can be empty, in which case this offset
|
| - will be equal to the next offset.
|
| + Example sequence of a read call, call fails on the host due to
|
| +invalid file descriptor (`EBADF'):
|
|
|
| - 4. The offset, from the start of the file, of the address area.
|
| + <- `Fread,3,1234,6'
|
| + -> `F-1,9'
|
|
|
| - 5. The offset, from the start of the file, of the symbol table.
|
| + Example sequence of a read call, user presses `Ctrl-c' before
|
| +syscall on host is called:
|
|
|
| - 6. The offset, from the start of the file, of the constant pool.
|
| + <- `Fread,3,1234,6'
|
| + -> `F-1,4,C'
|
| + <- `T02'
|
|
|
| - 2. The CU list. This is a sequence of pairs of 64-bit little-endian
|
| - values, sorted by the CU offset. The first element in each pair is
|
| - the offset of a CU in the `.debug_info' section. The second
|
| - element in each pair is the length of that CU. References to a CU
|
| - elsewhere in the map are done using a CU index, which is just the
|
| - 0-based index into this table. Note that if there are type CUs,
|
| - then conceptually CUs and type CUs form a single list for the
|
| - purposes of CU indices.
|
| + Example sequence of a read call, user presses `Ctrl-c' after syscall
|
| +on host is called:
|
|
|
| - 3. The types CU list. This is a sequence of triplets of 64-bit
|
| - little-endian values. In a triplet, the first value is the CU
|
| - offset, the second value is the type offset in the CU, and the
|
| - third value is the type signature. The types CU list is not
|
| - sorted.
|
| + <- `Fread,3,1234,6'
|
| + -> `X1234,6:XXXXXX'
|
| + <- `T02'
|
|
|
| - 4. The address area. The address area consists of a sequence of
|
| - address entries. Each address entry has three elements:
|
| +
|
| +File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
|
|
|
| - 1. The low address. This is a 64-bit little-endian value.
|
| +E.14 Library List Format
|
| +========================
|
|
|
| - 2. The high address. This is a 64-bit little-endian value. Like
|
| - `DW_AT_high_pc', the value is one byte beyond the end.
|
| +On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
|
| +process as your application to manage libraries. In this case, GDB can
|
| +use the loader's symbol table and normal memory operations to maintain
|
| +a list of shared libraries. On other platforms, the operating system
|
| +manages loaded libraries. GDB can not retrieve the list of currently
|
| +loaded libraries through memory operations, so it uses the
|
| +`qXfer:libraries:read' packet (*note qXfer library list read::)
|
| +instead. The remote stub queries the target's operating system and
|
| +reports which libraries are loaded.
|
|
|
| - 3. The CU index. This is an `offset_type' value.
|
| + The `qXfer:libraries:read' packet returns an XML document which
|
| +lists loaded libraries and their offsets. Each library has an
|
| +associated name and one or more segment or section base addresses,
|
| +which report where the library was loaded in memory.
|
|
|
| - 5. The symbol table. This is an open-addressed hash table. The size
|
| - of the hash table is always a power of 2.
|
| + For the common case of libraries that are fully linked binaries, the
|
| +library should have a list of segments. If the target supports dynamic
|
| +linking of a relocatable object file, its library XML element should
|
| +instead include a list of allocated sections. The segment or section
|
| +bases are start addresses, not relocation offsets; they do not depend
|
| +on the library's link-time base addresses.
|
|
|
| - Each slot in the hash table consists of a pair of `offset_type'
|
| - values. The first value is the offset of the symbol's name in the
|
| - constant pool. The second value is the offset of the CU vector in
|
| - the constant pool.
|
| + GDB must be linked with the Expat library to support XML library
|
| +lists. *Note Expat::.
|
|
|
| - If both values are 0, then this slot in the hash table is empty.
|
| - This is ok because while 0 is a valid constant pool index, it
|
| - cannot be a valid index for both a string and a CU vector.
|
| + A simple memory map, with one loaded library relocated by a single
|
| +offset, looks like this:
|
|
|
| - The hash value for a table entry is computed by applying an
|
| - iterative hash function to the symbol's name. Starting with an
|
| - initial value of `r = 0', each (unsigned) character `c' in the
|
| - string is incorporated into the hash using the formula depending
|
| - on the index version:
|
| -
|
| - Version 4
|
| - The formula is `r = r * 67 + c - 113'.
|
| -
|
| - Versions 5 to 7
|
| - The formula is `r = r * 67 + tolower (c) - 113'.
|
| -
|
| - The terminating `\0' is not incorporated into the hash.
|
| -
|
| - The step size used in the hash table is computed via `((hash * 17)
|
| - & (size - 1)) | 1', where `hash' is the hash value, and `size' is
|
| - the size of the hash table. The step size is used to find the
|
| - next candidate slot when handling a hash collision.
|
| -
|
| - The names of C++ symbols in the hash table are canonicalized. We
|
| - don't currently have a simple description of the canonicalization
|
| - algorithm; if you intend to create new index sections, you must
|
| - read the code.
|
| -
|
| - 6. The constant pool. This is simply a bunch of bytes. It is
|
| - organized so that alignment is correct: CU vectors are stored
|
| - first, followed by strings.
|
| -
|
| - A CU vector in the constant pool is a sequence of `offset_type'
|
| - values. The first value is the number of CU indices in the vector.
|
| - Each subsequent value is the index and symbol attributes of a CU in
|
| - the CU list. This element in the hash table is used to indicate
|
| - which CUs define the symbol and how the symbol is used. See below
|
| - for the format of each CU index+attributes entry.
|
| -
|
| - A string in the constant pool is zero-terminated.
|
| -
|
| - Attributes were added to CU index values in `.gdb_index' version 7.
|
| -If a symbol has multiple uses within a CU then there is one CU
|
| -index+attributes value for each use.
|
| -
|
| - The format of each CU index+attributes entry is as follows (bit 0 =
|
| -LSB):
|
| -
|
| -Bits 0-23
|
| - This is the index of the CU in the CU list.
|
| -
|
| -Bits 24-27
|
| - These bits are reserved for future purposes and must be zero.
|
| -
|
| -Bits 28-30
|
| - The kind of the symbol in the CU.
|
| -
|
| - 0
|
| - This value is reserved and should not be used. By reserving
|
| - zero the full `offset_type' value is backwards compatible
|
| - with previous versions of the index.
|
| -
|
| - 1
|
| - The symbol is a type.
|
| -
|
| - 2
|
| - The symbol is a variable or an enum value.
|
| -
|
| - 3
|
| - The symbol is a function.
|
| -
|
| - 4
|
| - Any other kind of symbol.
|
| -
|
| - 5,6,7
|
| - These values are reserved.
|
| -
|
| -Bit 31
|
| - This bit is zero if the value is global and one if it is static.
|
| -
|
| - The determination of whether a symbol is global or static is
|
| - complicated. The authorative reference is the file `dwarf2read.c'
|
| - in GDB sources.
|
| -
|
| -
|
| - This pseudo-code describes the computation of a symbol's kind and
|
| -global/static attributes in the index.
|
| -
|
| - is_external = get_attribute (die, DW_AT_external);
|
| - language = get_attribute (cu_die, DW_AT_language);
|
| - switch (die->tag)
|
| - {
|
| - case DW_TAG_typedef:
|
| - case DW_TAG_base_type:
|
| - case DW_TAG_subrange_type:
|
| - kind = TYPE;
|
| - is_static = 1;
|
| - break;
|
| - case DW_TAG_enumerator:
|
| - kind = VARIABLE;
|
| - is_static = (language != CPLUS && language != JAVA);
|
| - break;
|
| - case DW_TAG_subprogram:
|
| - kind = FUNCTION;
|
| - is_static = ! (is_external || language == ADA);
|
| - break;
|
| - case DW_TAG_constant:
|
| - kind = VARIABLE;
|
| - is_static = ! is_external;
|
| - break;
|
| - case DW_TAG_variable:
|
| - kind = VARIABLE;
|
| - is_static = ! is_external;
|
| - break;
|
| - case DW_TAG_namespace:
|
| - kind = TYPE;
|
| - is_static = 0;
|
| - break;
|
| - case DW_TAG_class_type:
|
| - case DW_TAG_interface_type:
|
| - case DW_TAG_structure_type:
|
| - case DW_TAG_union_type:
|
| - case DW_TAG_enumeration_type:
|
| - kind = TYPE;
|
| - is_static = (language != CPLUS && language != JAVA);
|
| - break;
|
| - default:
|
| - assert (0);
|
| - }
|
| + <library-list>
|
| + <library name="/lib/libc.so.6">
|
| + <segment address="0x10000000"/>
|
| + </library>
|
| + </library-list>
|
|
|
| -
|
| -File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Index Section Format, Up: Top
|
| + Another simple memory map, with one loaded library with three
|
| +allocated sections (.text, .data, .bss), looks like this:
|
|
|
| -Appendix K GNU GENERAL PUBLIC LICENSE
|
| -*************************************
|
| + <library-list>
|
| + <library name="sharedlib.o">
|
| + <section address="0x10000000"/>
|
| + <section address="0x20000000"/>
|
| + <section address="0x30000000"/>
|
| + </library>
|
| + </library-list>
|
|
|
| - Version 3, 29 June 2007
|
| -
|
| - Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/'
|
| -
|
| - Everyone is permitted to copy and distribute verbatim copies of this
|
| - license document, but changing it is not allowed.
|
| -
|
| -Preamble
|
| -========
|
| -
|
| -The GNU General Public License is a free, copyleft license for software
|
| -and other kinds of works.
|
| -
|
| - The licenses for most software and other practical works are designed
|
| -to take away your freedom to share and change the works. By contrast,
|
| -the GNU General Public License is intended to guarantee your freedom to
|
| -share and change all versions of a program--to make sure it remains
|
| -free software for all its users. We, the Free Software Foundation, use
|
| -the GNU General Public License for most of our software; it applies
|
| -also to any other work released this way by its authors. You can apply
|
| -it to your programs, too.
|
| -
|
| - When we speak of free software, we are referring to freedom, not
|
| -price. Our General Public Licenses are designed to make sure that you
|
| -have the freedom to distribute copies of free software (and charge for
|
| -them if you wish), that you receive source code or can get it if you
|
| -want it, that you can change the software or use pieces of it in new
|
| -free programs, and that you know you can do these things.
|
| -
|
| - To protect your rights, we need to prevent others from denying you
|
| -these rights or asking you to surrender the rights. Therefore, you
|
| -have certain responsibilities if you distribute copies of the software,
|
| -or if you modify it: responsibilities to respect the freedom of others.
|
| -
|
| - For example, if you distribute copies of such a program, whether
|
| -gratis or for a fee, you must pass on to the recipients the same
|
| -freedoms that you received. You must make sure that they, too, receive
|
| -or can get the source code. And you must show them these terms so they
|
| -know their rights.
|
| -
|
| - Developers that use the GNU GPL protect your rights with two steps:
|
| -(1) assert copyright on the software, and (2) offer you this License
|
| -giving you legal permission to copy, distribute and/or modify it.
|
| -
|
| - For the developers' and authors' protection, the GPL clearly explains
|
| -that there is no warranty for this free software. For both users' and
|
| -authors' sake, the GPL requires that modified versions be marked as
|
| -changed, so that their problems will not be attributed erroneously to
|
| -authors of previous versions.
|
| -
|
| - Some devices are designed to deny users access to install or run
|
| -modified versions of the software inside them, although the
|
| -manufacturer can do so. This is fundamentally incompatible with the
|
| -aim of protecting users' freedom to change the software. The
|
| -systematic pattern of such abuse occurs in the area of products for
|
| -individuals to use, which is precisely where it is most unacceptable.
|
| -Therefore, we have designed this version of the GPL to prohibit the
|
| -practice for those products. If such problems arise substantially in
|
| -other domains, we stand ready to extend this provision to those domains
|
| -in future versions of the GPL, as needed to protect the freedom of
|
| -users.
|
| -
|
| - Finally, every program is threatened constantly by software patents.
|
| -States should not allow patents to restrict development and use of
|
| -software on general-purpose computers, but in those that do, we wish to
|
| -avoid the special danger that patents applied to a free program could
|
| -make it effectively proprietary. To prevent this, the GPL assures that
|
| -patents cannot be used to render the program non-free.
|
| -
|
| - The precise terms and conditions for copying, distribution and
|
| -modification follow.
|
| -
|
| -TERMS AND CONDITIONS
|
| -====================
|
| + The format of a library list is described by this DTD:
|
|
|
| - 0. Definitions.
|
| -
|
| - "This License" refers to version 3 of the GNU General Public
|
| - License.
|
| -
|
| - "Copyright" also means copyright-like laws that apply to other
|
| - kinds of works, such as semiconductor masks.
|
| -
|
| - "The Program" refers to any copyrightable work licensed under this
|
| - License. Each licensee is addressed as "you". "Licensees" and
|
| - "recipients" may be individuals or organizations.
|
| -
|
| - To "modify" a work means to copy from or adapt all or part of the
|
| - work in a fashion requiring copyright permission, other than the
|
| - making of an exact copy. The resulting work is called a "modified
|
| - version" of the earlier work or a work "based on" the earlier work.
|
| -
|
| - A "covered work" means either the unmodified Program or a work
|
| - based on the Program.
|
| -
|
| - To "propagate" a work means to do anything with it that, without
|
| - permission, would make you directly or secondarily liable for
|
| - infringement under applicable copyright law, except executing it
|
| - on a computer or modifying a private copy. Propagation includes
|
| - copying, distribution (with or without modification), making
|
| - available to the public, and in some countries other activities as
|
| - well.
|
| -
|
| - To "convey" a work means any kind of propagation that enables other
|
| - parties to make or receive copies. Mere interaction with a user
|
| - through a computer network, with no transfer of a copy, is not
|
| - conveying.
|
| -
|
| - An interactive user interface displays "Appropriate Legal Notices"
|
| - to the extent that it includes a convenient and prominently visible
|
| - feature that (1) displays an appropriate copyright notice, and (2)
|
| - tells the user that there is no warranty for the work (except to
|
| - the extent that warranties are provided), that licensees may
|
| - convey the work under this License, and how to view a copy of this
|
| - License. If the interface presents a list of user commands or
|
| - options, such as a menu, a prominent item in the list meets this
|
| - criterion.
|
| -
|
| - 1. Source Code.
|
| -
|
| - The "source code" for a work means the preferred form of the work
|
| - for making modifications to it. "Object code" means any
|
| - non-source form of a work.
|
| -
|
| - A "Standard Interface" means an interface that either is an
|
| - official standard defined by a recognized standards body, or, in
|
| - the case of interfaces specified for a particular programming
|
| - language, one that is widely used among developers working in that
|
| - language.
|
| -
|
| - The "System Libraries" of an executable work include anything,
|
| - other than the work as a whole, that (a) is included in the normal
|
| - form of packaging a Major Component, but which is not part of that
|
| - Major Component, and (b) serves only to enable use of the work
|
| - with that Major Component, or to implement a Standard Interface
|
| - for which an implementation is available to the public in source
|
| - code form. A "Major Component", in this context, means a major
|
| - essential component (kernel, window system, and so on) of the
|
| - specific operating system (if any) on which the executable work
|
| - runs, or a compiler used to produce the work, or an object code
|
| - interpreter used to run it.
|
| -
|
| - The "Corresponding Source" for a work in object code form means all
|
| - the source code needed to generate, install, and (for an executable
|
| - work) run the object code and to modify the work, including
|
| - scripts to control those activities. However, it does not include
|
| - the work's System Libraries, or general-purpose tools or generally
|
| - available free programs which are used unmodified in performing
|
| - those activities but which are not part of the work. For example,
|
| - Corresponding Source includes interface definition files
|
| - associated with source files for the work, and the source code for
|
| - shared libraries and dynamically linked subprograms that the work
|
| - is specifically designed to require, such as by intimate data
|
| - communication or control flow between those subprograms and other
|
| - parts of the work.
|
| -
|
| - The Corresponding Source need not include anything that users can
|
| - regenerate automatically from other parts of the Corresponding
|
| - Source.
|
| -
|
| - The Corresponding Source for a work in source code form is that
|
| - same work.
|
| -
|
| - 2. Basic Permissions.
|
| -
|
| - All rights granted under this License are granted for the term of
|
| - copyright on the Program, and are irrevocable provided the stated
|
| - conditions are met. This License explicitly affirms your unlimited
|
| - permission to run the unmodified Program. The output from running
|
| - a covered work is covered by this License only if the output,
|
| - given its content, constitutes a covered work. This License
|
| - acknowledges your rights of fair use or other equivalent, as
|
| - provided by copyright law.
|
| -
|
| - You may make, run and propagate covered works that you do not
|
| - convey, without conditions so long as your license otherwise
|
| - remains in force. You may convey covered works to others for the
|
| - sole purpose of having them make modifications exclusively for
|
| - you, or provide you with facilities for running those works,
|
| - provided that you comply with the terms of this License in
|
| - conveying all material for which you do not control copyright.
|
| - Those thus making or running the covered works for you must do so
|
| - exclusively on your behalf, under your direction and control, on
|
| - terms that prohibit them from making any copies of your
|
| - copyrighted material outside their relationship with you.
|
| -
|
| - Conveying under any other circumstances is permitted solely under
|
| - the conditions stated below. Sublicensing is not allowed; section
|
| - 10 makes it unnecessary.
|
| -
|
| - 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
| -
|
| - No covered work shall be deemed part of an effective technological
|
| - measure under any applicable law fulfilling obligations under
|
| - article 11 of the WIPO copyright treaty adopted on 20 December
|
| - 1996, or similar laws prohibiting or restricting circumvention of
|
| - such measures.
|
| -
|
| - When you convey a covered work, you waive any legal power to forbid
|
| - circumvention of technological measures to the extent such
|
| - circumvention is effected by exercising rights under this License
|
| - with respect to the covered work, and you disclaim any intention
|
| - to limit operation or modification of the work as a means of
|
| - enforcing, against the work's users, your or third parties' legal
|
| - rights to forbid circumvention of technological measures.
|
| -
|
| - 4. Conveying Verbatim Copies.
|
| -
|
| - You may convey verbatim copies of the Program's source code as you
|
| - receive it, in any medium, provided that you conspicuously and
|
| - appropriately publish on each copy an appropriate copyright notice;
|
| - keep intact all notices stating that this License and any
|
| - non-permissive terms added in accord with section 7 apply to the
|
| - code; keep intact all notices of the absence of any warranty; and
|
| - give all recipients a copy of this License along with the Program.
|
| -
|
| - You may charge any price or no price for each copy that you convey,
|
| - and you may offer support or warranty protection for a fee.
|
| -
|
| - 5. Conveying Modified Source Versions.
|
| -
|
| - You may convey a work based on the Program, or the modifications to
|
| - produce it from the Program, in the form of source code under the
|
| - terms of section 4, provided that you also meet all of these
|
| - conditions:
|
| -
|
| - a. The work must carry prominent notices stating that you
|
| - modified it, and giving a relevant date.
|
| -
|
| - b. The work must carry prominent notices stating that it is
|
| - released under this License and any conditions added under
|
| - section 7. This requirement modifies the requirement in
|
| - section 4 to "keep intact all notices".
|
| -
|
| - c. You must license the entire work, as a whole, under this
|
| - License to anyone who comes into possession of a copy. This
|
| - License will therefore apply, along with any applicable
|
| - section 7 additional terms, to the whole of the work, and all
|
| - its parts, regardless of how they are packaged. This License
|
| - gives no permission to license the work in any other way, but
|
| - it does not invalidate such permission if you have separately
|
| - received it.
|
| -
|
| - d. If the work has interactive user interfaces, each must display
|
| - Appropriate Legal Notices; however, if the Program has
|
| - interactive interfaces that do not display Appropriate Legal
|
| - Notices, your work need not make them do so.
|
| -
|
| - A compilation of a covered work with other separate and independent
|
| - works, which are not by their nature extensions of the covered
|
| - work, and which are not combined with it such as to form a larger
|
| - program, in or on a volume of a storage or distribution medium, is
|
| - called an "aggregate" if the compilation and its resulting
|
| - copyright are not used to limit the access or legal rights of the
|
| - compilation's users beyond what the individual works permit.
|
| - Inclusion of a covered work in an aggregate does not cause this
|
| - License to apply to the other parts of the aggregate.
|
| -
|
| - 6. Conveying Non-Source Forms.
|
| -
|
| - You may convey a covered work in object code form under the terms
|
| - of sections 4 and 5, provided that you also convey the
|
| - machine-readable Corresponding Source under the terms of this
|
| - License, in one of these ways:
|
| -
|
| - a. Convey the object code in, or embodied in, a physical product
|
| - (including a physical distribution medium), accompanied by the
|
| - Corresponding Source fixed on a durable physical medium
|
| - customarily used for software interchange.
|
| -
|
| - b. Convey the object code in, or embodied in, a physical product
|
| - (including a physical distribution medium), accompanied by a
|
| - written offer, valid for at least three years and valid for
|
| - as long as you offer spare parts or customer support for that
|
| - product model, to give anyone who possesses the object code
|
| - either (1) a copy of the Corresponding Source for all the
|
| - software in the product that is covered by this License, on a
|
| - durable physical medium customarily used for software
|
| - interchange, for a price no more than your reasonable cost of
|
| - physically performing this conveying of source, or (2) access
|
| - to copy the Corresponding Source from a network server at no
|
| - charge.
|
| -
|
| - c. Convey individual copies of the object code with a copy of
|
| - the written offer to provide the Corresponding Source. This
|
| - alternative is allowed only occasionally and noncommercially,
|
| - and only if you received the object code with such an offer,
|
| - in accord with subsection 6b.
|
| -
|
| - d. Convey the object code by offering access from a designated
|
| - place (gratis or for a charge), and offer equivalent access
|
| - to the Corresponding Source in the same way through the same
|
| - place at no further charge. You need not require recipients
|
| - to copy the Corresponding Source along with the object code.
|
| - If the place to copy the object code is a network server, the
|
| - Corresponding Source may be on a different server (operated
|
| - by you or a third party) that supports equivalent copying
|
| - facilities, provided you maintain clear directions next to
|
| - the object code saying where to find the Corresponding Source.
|
| - Regardless of what server hosts the Corresponding Source, you
|
| - remain obligated to ensure that it is available for as long
|
| - as needed to satisfy these requirements.
|
| -
|
| - e. Convey the object code using peer-to-peer transmission,
|
| - provided you inform other peers where the object code and
|
| - Corresponding Source of the work are being offered to the
|
| - general public at no charge under subsection 6d.
|
| -
|
| -
|
| - A separable portion of the object code, whose source code is
|
| - excluded from the Corresponding Source as a System Library, need
|
| - not be included in conveying the object code work.
|
| -
|
| - A "User Product" is either (1) a "consumer product", which means
|
| - any tangible personal property which is normally used for personal,
|
| - family, or household purposes, or (2) anything designed or sold for
|
| - incorporation into a dwelling. In determining whether a product
|
| - is a consumer product, doubtful cases shall be resolved in favor of
|
| - coverage. For a particular product received by a particular user,
|
| - "normally used" refers to a typical or common use of that class of
|
| - product, regardless of the status of the particular user or of the
|
| - way in which the particular user actually uses, or expects or is
|
| - expected to use, the product. A product is a consumer product
|
| - regardless of whether the product has substantial commercial,
|
| - industrial or non-consumer uses, unless such uses represent the
|
| - only significant mode of use of the product.
|
| -
|
| - "Installation Information" for a User Product means any methods,
|
| - procedures, authorization keys, or other information required to
|
| - install and execute modified versions of a covered work in that
|
| - User Product from a modified version of its Corresponding Source.
|
| - The information must suffice to ensure that the continued
|
| - functioning of the modified object code is in no case prevented or
|
| - interfered with solely because modification has been made.
|
| -
|
| - If you convey an object code work under this section in, or with,
|
| - or specifically for use in, a User Product, and the conveying
|
| - occurs as part of a transaction in which the right of possession
|
| - and use of the User Product is transferred to the recipient in
|
| - perpetuity or for a fixed term (regardless of how the transaction
|
| - is characterized), the Corresponding Source conveyed under this
|
| - section must be accompanied by the Installation Information. But
|
| - this requirement does not apply if neither you nor any third party
|
| - retains the ability to install modified object code on the User
|
| - Product (for example, the work has been installed in ROM).
|
| -
|
| - The requirement to provide Installation Information does not
|
| - include a requirement to continue to provide support service,
|
| - warranty, or updates for a work that has been modified or
|
| - installed by the recipient, or for the User Product in which it
|
| - has been modified or installed. Access to a network may be denied
|
| - when the modification itself materially and adversely affects the
|
| - operation of the network or violates the rules and protocols for
|
| - communication across the network.
|
| -
|
| - Corresponding Source conveyed, and Installation Information
|
| - provided, in accord with this section must be in a format that is
|
| - publicly documented (and with an implementation available to the
|
| - public in source code form), and must require no special password
|
| - or key for unpacking, reading or copying.
|
| -
|
| - 7. Additional Terms.
|
| -
|
| - "Additional permissions" are terms that supplement the terms of
|
| - this License by making exceptions from one or more of its
|
| - conditions. Additional permissions that are applicable to the
|
| - entire Program shall be treated as though they were included in
|
| - this License, to the extent that they are valid under applicable
|
| - law. If additional permissions apply only to part of the Program,
|
| - that part may be used separately under those permissions, but the
|
| - entire Program remains governed by this License without regard to
|
| - the additional permissions.
|
| -
|
| - When you convey a copy of a covered work, you may at your option
|
| - remove any additional permissions from that copy, or from any part
|
| - of it. (Additional permissions may be written to require their own
|
| - removal in certain cases when you modify the work.) You may place
|
| - additional permissions on material, added by you to a covered work,
|
| - for which you have or can give appropriate copyright permission.
|
| -
|
| - Notwithstanding any other provision of this License, for material
|
| - you add to a covered work, you may (if authorized by the copyright
|
| - holders of that material) supplement the terms of this License
|
| - with terms:
|
| -
|
| - a. Disclaiming warranty or limiting liability differently from
|
| - the terms of sections 15 and 16 of this License; or
|
| -
|
| - b. Requiring preservation of specified reasonable legal notices
|
| - or author attributions in that material or in the Appropriate
|
| - Legal Notices displayed by works containing it; or
|
| -
|
| - c. Prohibiting misrepresentation of the origin of that material,
|
| - or requiring that modified versions of such material be
|
| - marked in reasonable ways as different from the original
|
| - version; or
|
| -
|
| - d. Limiting the use for publicity purposes of names of licensors
|
| - or authors of the material; or
|
| -
|
| - e. Declining to grant rights under trademark law for use of some
|
| - trade names, trademarks, or service marks; or
|
| -
|
| - f. Requiring indemnification of licensors and authors of that
|
| - material by anyone who conveys the material (or modified
|
| - versions of it) with contractual assumptions of liability to
|
| - the recipient, for any liability that these contractual
|
| - assumptions directly impose on those licensors and authors.
|
| -
|
| - All other non-permissive additional terms are considered "further
|
| - restrictions" within the meaning of section 10. If the Program as
|
| - you received it, or any part of it, contains a notice stating that
|
| - it is governed by this License along with a term that is a further
|
| - restriction, you may remove that term. If a license document
|
| - contains a further restriction but permits relicensing or
|
| - conveying under this License, you may add to a covered work
|
| - material governed by the terms of that license document, provided
|
| - that the further restriction does not survive such relicensing or
|
| - conveying.
|
| -
|
| - If you add terms to a covered work in accord with this section, you
|
| - must place, in the relevant source files, a statement of the
|
| - additional terms that apply to those files, or a notice indicating
|
| - where to find the applicable terms.
|
| -
|
| - Additional terms, permissive or non-permissive, may be stated in
|
| - the form of a separately written license, or stated as exceptions;
|
| - the above requirements apply either way.
|
| -
|
| - 8. Termination.
|
| -
|
| - You may not propagate or modify a covered work except as expressly
|
| - provided under this License. Any attempt otherwise to propagate or
|
| - modify it is void, and will automatically terminate your rights
|
| - under this License (including any patent licenses granted under
|
| - the third paragraph of section 11).
|
| -
|
| - However, if you cease all violation of this License, then your
|
| - license from a particular copyright holder is reinstated (a)
|
| - provisionally, unless and until the copyright holder explicitly
|
| - and finally terminates your license, and (b) permanently, if the
|
| - copyright holder fails to notify you of the violation by some
|
| - reasonable means prior to 60 days after the cessation.
|
| -
|
| - Moreover, your license from a particular copyright holder is
|
| - reinstated permanently if the copyright holder notifies you of the
|
| - violation by some reasonable means, this is the first time you have
|
| - received notice of violation of this License (for any work) from
|
| - that copyright holder, and you cure the violation prior to 30 days
|
| - after your receipt of the notice.
|
| -
|
| - Termination of your rights under this section does not terminate
|
| - the licenses of parties who have received copies or rights from
|
| - you under this License. If your rights have been terminated and
|
| - not permanently reinstated, you do not qualify to receive new
|
| - licenses for the same material under section 10.
|
| -
|
| - 9. Acceptance Not Required for Having Copies.
|
| -
|
| - You are not required to accept this License in order to receive or
|
| - run a copy of the Program. Ancillary propagation of a covered work
|
| - occurring solely as a consequence of using peer-to-peer
|
| - transmission to receive a copy likewise does not require
|
| - acceptance. However, nothing other than this License grants you
|
| - permission to propagate or modify any covered work. These actions
|
| - infringe copyright if you do not accept this License. Therefore,
|
| - by modifying or propagating a covered work, you indicate your
|
| - acceptance of this License to do so.
|
| -
|
| - 10. Automatic Licensing of Downstream Recipients.
|
| -
|
| - Each time you convey a covered work, the recipient automatically
|
| - receives a license from the original licensors, to run, modify and
|
| - propagate that work, subject to this License. You are not
|
| - responsible for enforcing compliance by third parties with this
|
| - License.
|
| -
|
| - An "entity transaction" is a transaction transferring control of an
|
| - organization, or substantially all assets of one, or subdividing an
|
| - organization, or merging organizations. If propagation of a
|
| - covered work results from an entity transaction, each party to that
|
| - transaction who receives a copy of the work also receives whatever
|
| - licenses to the work the party's predecessor in interest had or
|
| - could give under the previous paragraph, plus a right to
|
| - possession of the Corresponding Source of the work from the
|
| - predecessor in interest, if the predecessor has it or can get it
|
| - with reasonable efforts.
|
| -
|
| - You may not impose any further restrictions on the exercise of the
|
| - rights granted or affirmed under this License. For example, you
|
| - may not impose a license fee, royalty, or other charge for
|
| - exercise of rights granted under this License, and you may not
|
| - initiate litigation (including a cross-claim or counterclaim in a
|
| - lawsuit) alleging that any patent claim is infringed by making,
|
| - using, selling, offering for sale, or importing the Program or any
|
| - portion of it.
|
| -
|
| - 11. Patents.
|
| -
|
| - A "contributor" is a copyright holder who authorizes use under this
|
| - License of the Program or a work on which the Program is based.
|
| - The work thus licensed is called the contributor's "contributor
|
| - version".
|
| -
|
| - A contributor's "essential patent claims" are all patent claims
|
| - owned or controlled by the contributor, whether already acquired or
|
| - hereafter acquired, that would be infringed by some manner,
|
| - permitted by this License, of making, using, or selling its
|
| - contributor version, but do not include claims that would be
|
| - infringed only as a consequence of further modification of the
|
| - contributor version. For purposes of this definition, "control"
|
| - includes the right to grant patent sublicenses in a manner
|
| - consistent with the requirements of this License.
|
| -
|
| - Each contributor grants you a non-exclusive, worldwide,
|
| - royalty-free patent license under the contributor's essential
|
| - patent claims, to make, use, sell, offer for sale, import and
|
| - otherwise run, modify and propagate the contents of its
|
| - contributor version.
|
| -
|
| - In the following three paragraphs, a "patent license" is any
|
| - express agreement or commitment, however denominated, not to
|
| - enforce a patent (such as an express permission to practice a
|
| - patent or covenant not to sue for patent infringement). To
|
| - "grant" such a patent license to a party means to make such an
|
| - agreement or commitment not to enforce a patent against the party.
|
| -
|
| - If you convey a covered work, knowingly relying on a patent
|
| - license, and the Corresponding Source of the work is not available
|
| - for anyone to copy, free of charge and under the terms of this
|
| - License, through a publicly available network server or other
|
| - readily accessible means, then you must either (1) cause the
|
| - Corresponding Source to be so available, or (2) arrange to deprive
|
| - yourself of the benefit of the patent license for this particular
|
| - work, or (3) arrange, in a manner consistent with the requirements
|
| - of this License, to extend the patent license to downstream
|
| - recipients. "Knowingly relying" means you have actual knowledge
|
| - that, but for the patent license, your conveying the covered work
|
| - in a country, or your recipient's use of the covered work in a
|
| - country, would infringe one or more identifiable patents in that
|
| - country that you have reason to believe are valid.
|
| -
|
| - If, pursuant to or in connection with a single transaction or
|
| - arrangement, you convey, or propagate by procuring conveyance of, a
|
| - covered work, and grant a patent license to some of the parties
|
| - receiving the covered work authorizing them to use, propagate,
|
| - modify or convey a specific copy of the covered work, then the
|
| - patent license you grant is automatically extended to all
|
| - recipients of the covered work and works based on it.
|
| -
|
| - A patent license is "discriminatory" if it does not include within
|
| - the scope of its coverage, prohibits the exercise of, or is
|
| - conditioned on the non-exercise of one or more of the rights that
|
| - are specifically granted under this License. You may not convey a
|
| - covered work if you are a party to an arrangement with a third
|
| - party that is in the business of distributing software, under
|
| - which you make payment to the third party based on the extent of
|
| - your activity of conveying the work, and under which the third
|
| - party grants, to any of the parties who would receive the covered
|
| - work from you, a discriminatory patent license (a) in connection
|
| - with copies of the covered work conveyed by you (or copies made
|
| - from those copies), or (b) primarily for and in connection with
|
| - specific products or compilations that contain the covered work,
|
| - unless you entered into that arrangement, or that patent license
|
| - was granted, prior to 28 March 2007.
|
| -
|
| - Nothing in this License shall be construed as excluding or limiting
|
| - any implied license or other defenses to infringement that may
|
| - otherwise be available to you under applicable patent law.
|
| -
|
| - 12. No Surrender of Others' Freedom.
|
| -
|
| - If conditions are imposed on you (whether by court order,
|
| - agreement or otherwise) that contradict the conditions of this
|
| - License, they do not excuse you from the conditions of this
|
| - License. If you cannot convey a covered work so as to satisfy
|
| - simultaneously your obligations under this License and any other
|
| - pertinent obligations, then as a consequence you may not convey it
|
| - at all. For example, if you agree to terms that obligate you to
|
| - collect a royalty for further conveying from those to whom you
|
| - convey the Program, the only way you could satisfy both those
|
| - terms and this License would be to refrain entirely from conveying
|
| - the Program.
|
| -
|
| - 13. Use with the GNU Affero General Public License.
|
| -
|
| - Notwithstanding any other provision of this License, you have
|
| - permission to link or combine any covered work with a work licensed
|
| - under version 3 of the GNU Affero General Public License into a
|
| - single combined work, and to convey the resulting work. The terms
|
| - of this License will continue to apply to the part which is the
|
| - covered work, but the special requirements of the GNU Affero
|
| - General Public License, section 13, concerning interaction through
|
| - a network will apply to the combination as such.
|
| -
|
| - 14. Revised Versions of this License.
|
| -
|
| - The Free Software Foundation may publish revised and/or new
|
| - versions of the GNU General Public License from time to time.
|
| - Such new versions will be similar in spirit to the present
|
| - version, but may differ in detail to address new problems or
|
| - concerns.
|
| -
|
| - Each version is given a distinguishing version number. If the
|
| - Program specifies that a certain numbered version of the GNU
|
| - General Public License "or any later version" applies to it, you
|
| - have the option of following the terms and conditions either of
|
| - that numbered version or of any later version published by the
|
| - Free Software Foundation. If the Program does not specify a
|
| - version number of the GNU General Public License, you may choose
|
| - any version ever published by the Free Software Foundation.
|
| -
|
| - If the Program specifies that a proxy can decide which future
|
| - versions of the GNU General Public License can be used, that
|
| - proxy's public statement of acceptance of a version permanently
|
| - authorizes you to choose that version for the Program.
|
| -
|
| - Later license versions may give you additional or different
|
| - permissions. However, no additional obligations are imposed on any
|
| - author or copyright holder as a result of your choosing to follow a
|
| - later version.
|
| -
|
| - 15. Disclaimer of Warranty.
|
| -
|
| - THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
| - APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
|
| - COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
|
| - WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
|
| - INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
| - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
|
| - RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
|
| - SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
|
| - NECESSARY SERVICING, REPAIR OR CORRECTION.
|
| -
|
| - 16. Limitation of Liability.
|
| -
|
| - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
|
| - WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
|
| - AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
|
| - FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
|
| - CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
|
| - THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
|
| - BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
| - PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
|
| - PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
|
| - THE POSSIBILITY OF SUCH DAMAGES.
|
| -
|
| - 17. Interpretation of Sections 15 and 16.
|
| -
|
| - If the disclaimer of warranty and limitation of liability provided
|
| - above cannot be given local legal effect according to their terms,
|
| - reviewing courts shall apply local law that most closely
|
| - approximates an absolute waiver of all civil liability in
|
| - connection with the Program, unless a warranty or assumption of
|
| - liability accompanies a copy of the Program in return for a fee.
|
| -
|
| -
|
| -END OF TERMS AND CONDITIONS
|
| -===========================
|
| + <!-- library-list: Root element with versioning -->
|
| + <!ELEMENT library-list (library)*>
|
| + <!ATTLIST library-list version CDATA #FIXED "1.0">
|
| + <!ELEMENT library (segment*, section*)>
|
| + <!ATTLIST library name CDATA #REQUIRED>
|
| + <!ELEMENT segment EMPTY>
|
| + <!ATTLIST segment address CDATA #REQUIRED>
|
| + <!ELEMENT section EMPTY>
|
| + <!ATTLIST section address CDATA #REQUIRED>
|
|
|
| -How to Apply These Terms to Your New Programs
|
| -=============================================
|
| -
|
| -If you develop a new program, and you want it to be of the greatest
|
| -possible use to the public, the best way to achieve this is to make it
|
| -free software which everyone can redistribute and change under these
|
| -terms.
|
| -
|
| - To do so, attach the following notices to the program. It is safest
|
| -to attach them to the start of each source file to most effectively
|
| -state the exclusion of warranty; and each file should have at least the
|
| -"copyright" line and a pointer to where the full notice is found.
|
| -
|
| - ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
|
| - Copyright (C) YEAR NAME OF AUTHOR
|
| -
|
| - This program is free software: you can redistribute it and/or modify
|
| - it under the terms of the GNU General Public License as published by
|
| - the Free Software Foundation, either version 3 of the License, or (at
|
| - your option) any later version.
|
| -
|
| - This program is distributed in the hope that it will be useful, but
|
| - WITHOUT ANY WARRANTY; without even the implied warranty of
|
| - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
| - General Public License for more details.
|
| -
|
| - You should have received a copy of the GNU General Public License
|
| - along with this program. If not, see `http://www.gnu.org/licenses/'.
|
| -
|
| - Also add information on how to contact you by electronic and paper
|
| -mail.
|
| -
|
| - If the program does terminal interaction, make it output a short
|
| -notice like this when it starts in an interactive mode:
|
| -
|
| - PROGRAM Copyright (C) YEAR NAME OF AUTHOR
|
| - This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
| - This is free software, and you are welcome to redistribute it
|
| - under certain conditions; type `show c' for details.
|
| -
|
| - The hypothetical commands `show w' and `show c' should show the
|
| -appropriate parts of the General Public License. Of course, your
|
| -program's commands might be different; for a GUI interface, you would
|
| -use an "about box".
|
| -
|
| - You should also get your employer (if you work as a programmer) or
|
| -school, if any, to sign a "copyright disclaimer" for the program, if
|
| -necessary. For more information on this, and how to apply and follow
|
| -the GNU GPL, see `http://www.gnu.org/licenses/'.
|
| -
|
| - The GNU General Public License does not permit incorporating your
|
| -program into proprietary programs. If your program is a subroutine
|
| -library, you may consider it more useful to permit linking proprietary
|
| -applications with the library. If this is what you want to do, use the
|
| -GNU Lesser General Public License instead of this License. But first,
|
| -please read `http://www.gnu.org/philosophy/why-not-lgpl.html'.
|
| + In addition, segments and section descriptors cannot be mixed within
|
| +a single library element, and you must supply at least one segment or
|
| +section for each library.
|
|
|
|
|
Chromium Code Reviews
Issue 124383005:
GDB 7.6.50 (Closed)
Base URL: http://git.chromium.org/native_client/nacl-gdb.git@upstream