| This is gdb.info, produced by makeinfo version 6.0 from gdb.texinfo. |
| |
| Copyright (C) 1988-2016 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 |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| 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 |
| |
| 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.11. |
| |
| Copyright (C) 1988-2016 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 |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Free Software" and "Free Software Needs Free |
| Documentation", with the Front-Cover Texts being "A GNU Manual," and |
| with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: "You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom." |
| |
| |
| File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing |
| |
| 32.5 Readline vi Mode |
| ===================== |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top |
| |
| 33 Using History Interactively |
| ****************************** |
| |
| 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 |
| (history)Programming with GNU History::. |
| |
| * Menu: |
| |
| * History Interaction:: What it feels like using History as a user. |
| |
| |
| File: gdb.info, Node: History Interaction, Up: Using History Interactively |
| |
| 33.1 History Expansion |
| ====================== |
| |
| 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. |
| |
| * Menu: |
| |
| * Event Designators:: How to specify which history line to use. |
| * Word Designators:: Specifying which words are of interest. |
| * Modifiers:: Modifying the results of substitution. |
| |
| |
| File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction |
| |
| 33.1.1 Event Designators |
| ------------------------ |
| |
| 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. |
| |
| '!' |
| Start a history substitution, except when followed by a space, tab, |
| the end of the line, or '='. |
| |
| '!N' |
| Refer to command line N. |
| |
| '!-N' |
| Refer to the command N lines back. |
| |
| '!!' |
| Refer to the previous command. This is a synonym for '!-1'. |
| |
| '!STRING' |
| Refer to the most recent command preceding the current position in |
| the history list starting with STRING. |
| |
| '!?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. |
| |
| '^STRING1^STRING2^' |
| Quick Substitution. Repeat the last command, replacing STRING1 |
| with STRING2. Equivalent to '!!:s/STRING1/STRING2/'. |
| |
| '!#' |
| The entire command line typed so far. |
| |
| |
| File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction |
| |
| 33.1.2 Word Designators |
| ----------------------- |
| |
| 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. |
| |
| For example, |
| |
| '!!' |
| designates the preceding command. When you type this, the |
| preceding command is repeated in toto. |
| |
| '!!:$' |
| designates the last argument of the preceding command. This may be |
| shortened to '!$'. |
| |
| '!fi:2' |
| designates the second argument of the most recent command starting |
| with the letters 'fi'. |
| |
| Here are the word designators: |
| |
| '0 (zero)' |
| The '0'th word. For many applications, this is the command word. |
| |
| 'N' |
| The Nth word. |
| |
| '^' |
| The first argument; that is, word 1. |
| |
| '$' |
| The last argument. |
| |
| '%' |
| The word matched by the most recent '?STRING?' search. |
| |
| 'X-Y' |
| A range of words; '-Y' abbreviates '0-Y'. |
| |
| '*' |
| 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. |
| |
| 'X*' |
| Abbreviates 'X-$' |
| |
| 'X-' |
| Abbreviates 'X-$' like 'X*', but omits the last word. |
| |
| If a word designator is supplied without an event specification, the |
| previous command is used as the event. |
| |
| |
| File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction |
| |
| 33.1.3 Modifiers |
| ---------------- |
| |
| After the optional word designator, you can add a sequence of one or |
| more of the following modifiers, each preceded by a ':'. |
| |
| 'h' |
| Remove a trailing pathname component, leaving only the head. |
| |
| 't' |
| Remove all leading pathname components, leaving the tail. |
| |
| 'r' |
| Remove a trailing suffix of the form '.SUFFIX', leaving the |
| basename. |
| |
| 'e' |
| Remove all but the trailing suffix. |
| |
| 'p' |
| Print the new command but do not execute it. |
| |
| '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. |
| |
| '&' |
| Repeat the previous substitution. |
| |
| 'g' |
| 'a' |
| Cause changes to be applied over the entire event line. Used in |
| conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. |
| |
| 'G' |
| Apply the following 's' modifier once to each word in the event. |
| |
| |
| File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top |
| |
| Appendix A In Memoriam |
| ********************** |
| |
| The GDB project mourns the loss of the following long-time contributors: |
| |
| '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. |
| |
| '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. |
| |
| |
| 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.11/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.11', in the case of version 7.11), 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.11/gdb') and type: |
| |
| make gdb.dvi |
| |
| Then give 'gdb.dvi' to your DVI printing program. |
| |
| ---------- Footnotes ---------- |
| |
| (1) In 'gdb-7.11/gdb/refcard.ps' of the version 7.11 release. |
| |
| |
| File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top |
| |
| Appendix C Installing GDB |
| ************************* |
| |
| * Menu: |
| |
| * 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 |
| |
| |
| File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB |
| |
| C.1 Requirements for Building GDB |
| ================================= |
| |
| Building GDB requires various tools and packages to be available. Other |
| packages will be used only if they are found. |
| |
| Tools/Packages Necessary for Building GDB |
| ========================================= |
| |
| ISO C90 compiler |
| GDB is written in ISO C90. It should be buildable with any working |
| C90 compiler, e.g. GCC. |
| |
| Tools/Packages Optional for Building GDB |
| ======================================== |
| |
| 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. |
| |
| Expat is used for: |
| |
| * Remote protocol memory maps (*note Memory Map Format::) |
| * Target descriptions (*note Target Descriptions::) |
| * Remote shared library lists (*Note Library List Format::, or |
| alternatively *note Library List Format for SVR4 Targets::) |
| * MS-Windows shared libraries (*note Shared Libraries::) |
| * Traceframe info (*note Traceframe Info Format::) |
| * Branch trace (*note Branch Trace Format::, *note Branch Trace |
| Configuration Format::) |
| |
| 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. |
| |
| 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>. |
| |
| 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'. |
| |
| 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. |
| |
| 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. |
| |
| 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'. |
| |
| |
| File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB |
| |
| C.2 Invoking the GDB 'configure' Script |
| ======================================= |
| |
| 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 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'. |
| |
| For example, the GDB version 7.11 distribution is in the 'gdb-7.11' |
| directory. That directory contains: |
| |
| 'gdb-7.11/configure (and supporting files)' |
| script for configuring GDB and all its supporting libraries |
| |
| 'gdb-7.11/gdb' |
| the source specific to GDB itself |
| |
| 'gdb-7.11/bfd' |
| source for the Binary File Descriptor library |
| |
| 'gdb-7.11/include' |
| GNU include files |
| |
| 'gdb-7.11/libiberty' |
| source for the '-liberty' free software library |
| |
| 'gdb-7.11/opcodes' |
| source for the library of opcode tables and disassemblers |
| |
| 'gdb-7.11/readline' |
| source for the GNU command-line interface |
| |
| 'gdb-7.11/glob' |
| source for the GNU filename pattern-matching subroutine |
| |
| 'gdb-7.11/mmalloc' |
| source for the GNU memory-mapped malloc package |
| |
| 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.11' directory. |
| |
| 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. |
| |
| For example: |
| |
| cd gdb-7.11 |
| ./configure HOST |
| make |
| |
| 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.) |
| |
| 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: |
| |
| sh configure HOST |
| |
| If you run 'configure' from a directory that contains source |
| directories for multiple libraries or programs, such as the 'gdb-7.11' |
| source directory for version 7.11, 'configure' creates configuration |
| files for every directory level underneath (unless you tell it not to, |
| with the '--norecursion' option). |
| |
| 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'. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB |
| |
| C.3 Compiling GDB in Another Directory |
| ====================================== |
| |
| 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. |
| |
| 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.) |
| |
| For example, with version 7.11, you can build GDB in a separate |
| directory for a Sun 4 like this: |
| |
| cd gdb-7.11 |
| mkdir ../gdb-sun4 |
| cd ../gdb-sun4 |
| ../gdb-7.11/configure sun4 |
| make |
| |
| 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'. |
| |
| 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.11/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'. |
| |
| 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'. |
| |
| 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 'Makefile' that 'configure' generates in each source directory |
| also runs recursively. If you type 'make' in a source directory such as |
| 'gdb-7.11' (or in a separate configured directory configured with |
| '--srcdir=DIRNAME/gdb-7.11'), you will build all the required libraries, |
| and then build GDB. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB |
| |
| C.4 Specifying Names for Hosts and Targets |
| ========================================== |
| |
| 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: |
| |
| ARCHITECTURE-VENDOR-OS |
| |
| 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: |
| |
| % 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 |
| |
| 'config.sub' is also distributed in the GDB source directory |
| ('gdb-7.11', for version 7.11). |
| |
| |
| File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB |
| |
| C.5 'configure' Options |
| ======================= |
| |
| 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'. |
| |
| configure [--help] |
| [--prefix=DIR] |
| [--exec-prefix=DIR] |
| [--srcdir=DIRNAME] |
| [--norecursion] [--rm] |
| [--target=TARGET] |
| HOST |
| |
| You may introduce options with a single '-' rather than '--' if you |
| prefer; but you may abbreviate option names if you use '--'. |
| |
| '--help' |
| Display a quick summary of how to invoke 'configure'. |
| |
| '--prefix=DIR' |
| Configure the source to install programs and files under directory |
| 'DIR'. |
| |
| '--exec-prefix=DIR' |
| Configure the source to install programs under directory 'DIR'. |
| |
| '--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. |
| |
| '--norecursion' |
| Configure only the directory level where 'configure' is executed; |
| do not propagate configuration to subdirectories. |
| |
| '--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. |
| |
| There is no convenient way to generate a list of all available |
| targets. |
| |
| 'HOST ...' |
| Configure GDB to run on the specified HOST. |
| |
| 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: System-wide configuration, Prev: Configure Options, Up: Installing GDB |
| |
| C.6 System-wide configuration and settings |
| ========================================== |
| |
| 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.). |
| |
| Here is the corresponding configure option: |
| |
| '--with-system-gdbinit=FILE' |
| Specify that the default location of the system-wide init file is |
| FILE. |
| |
| If GDB has been configured with the option '--prefix=$prefix', it may |
| be subject to relocation. Two possible cases: |
| |
| * 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'. |
| |
| * 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. |
| |
| * Menu: |
| |
| * System-wide Configuration Scripts:: Installed System-wide Configuration Scripts |
| |
| |
| File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration |
| |
| C.6.1 Installed System-wide Configuration Scripts |
| ------------------------------------------------- |
| |
| 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. |
| |
| 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. |
| |
| * '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: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top |
| |
| Appendix D Maintenance Commands |
| ******************************* |
| |
| 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::.) |
| |
| '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. |
| |
| '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::). |
| |
| '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. |
| |
| 'watchpoint' |
| Normal, explicitly set watchpoint. |
| |
| 'longjmp' |
| Internal breakpoint, used to handle correctly stepping through |
| 'longjmp' calls. |
| |
| 'longjmp resume' |
| Internal breakpoint at the target of a 'longjmp'. |
| |
| 'until' |
| Temporary internal breakpoint used by the GDB 'until' command. |
| |
| 'finish' |
| Temporary internal breakpoint used by the GDB 'finish' |
| command. |
| |
| 'shlib events' |
| Shared library events. |
| |
| 'maint info btrace' |
| Pint information about raw branch tracing data. |
| |
| 'maint btrace packet-history' |
| Print the raw branch trace packets that are used to compute the |
| execution history for the 'record btrace' command. Both the |
| information and the format in which it is printed depend on the |
| btrace recording format. |
| |
| 'bts' |
| For the BTS recording format, print a list of blocks of |
| sequential code. For each block, the following information is |
| printed: |
| |
| Block number |
| Newer blocks have higher numbers. The oldest block has |
| number zero. |
| Lowest 'PC' |
| Highest 'PC' |
| |
| 'pt' |
| For the Intel Processor Trace recording format, print a list |
| of Intel Processor Trace packets. For each packet, the |
| following information is printed: |
| |
| Packet number |
| Newer packets have higher numbers. The oldest packet has |
| number zero. |
| Trace offset |
| The packet's offset in the trace stream. |
| Packet opcode and payload |
| |
| 'maint btrace clear-packet-history' |
| Discards the cached packet history printed by the 'maint btrace |
| packet-history' command. The history will be computed again when |
| needed. |
| |
| 'maint btrace clear' |
| Discard the branch trace data. The data will be fetched anew and |
| the branch trace will be recomputed when needed. |
| |
| This implicitly truncates the branch trace to a single branch trace |
| buffer. When updating branch trace incrementally, the branch trace |
| available to GDB may be bigger than a single branch trace buffer. |
| |
| 'maint set btrace pt skip-pad' |
| 'maint show btrace pt skip-pad' |
| Control whether GDB will skip PAD packets when computing the packet |
| history. |
| |
| '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. |
| |
| 'set displaced-stepping on' |
| If the target architecture supports it, GDB will use displaced |
| stepping to step over breakpoints. |
| |
| 'set displaced-stepping off' |
| GDB will not use displaced stepping to step over breakpoints, |
| even if such is supported by the target architecture. |
| |
| '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. |
| |
| '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. |
| |
| 'maint check-symtabs' |
| Check the consistency of currently expanded symtabs. |
| |
| 'maint expand-symtabs [REGEXP]' |
| Expand symbol tables. If REGEXP is specified, only expand symbol |
| tables for file names matching REGEXP. |
| |
| 'maint set catch-demangler-crashes [on|off]' |
| 'maint show catch-demangler-crashes' |
| Control whether GDB should attempt to catch crashes in the symbol |
| name demangler. The default is to attempt to catch crashes. If |
| enabled, the first time a crash is caught, a core file is created, |
| the offending symbol is displayed and the user is presented with |
| the option to terminate the current session. |
| |
| 'maint cplus first_component NAME' |
| Print the first C++ class/namespace component of NAME. |
| |
| 'maint cplus namespace' |
| Print the list of possible C++ namespaces. |
| |
| '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. |
| |
| 'maint internal-error [MESSAGE-TEXT]' |
| 'maint internal-warning [MESSAGE-TEXT]' |
| 'maint demangler-warning [MESSAGE-TEXT]' |
| |
| Cause GDB to call the internal function 'internal_error', |
| 'internal_warning' or 'demangler_warning' and hence behave as |
| though an internal problem has been detected. In addition to |
| reporting the internal problem, these functions give the user the |
| opportunity to either quit GDB or (for 'internal_error' and |
| 'internal_warning') create a core file of the current GDB session. |
| |
| These commands take an optional parameter MESSAGE-TEXT that is used |
| as the text of the error or warning message. |
| |
| Here's an example of using 'internal-error': |
| |
| (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) |
| |
| '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' |
| 'maint set demangler-warning ACTION [ask|yes|no]' |
| 'maint show demangler-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. |
| |
| 'quit' |
| You can specify that GDB should always (yes) or never (no) |
| quit. The default is to ask the user what to do. |
| |
| '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. Note that there is no 'corefile' option for |
| 'demangler-warning': demangler warnings always create a core |
| file and this cannot be disabled. |
| |
| '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. |
| |
| 'maint print architecture [FILE]' |
| Print the entire architecture configuration. The optional argument |
| FILE names the file where the output goes. |
| |
| '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. |
| |
| 'maint print dummy-frames' |
| Prints the contents of GDB's internal dummy-frame stack. |
| |
| (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 |
| 0xa8206d8: id={stack=0xbfffe734,code=0xbfffe73f,!special}, ptid=process 9353 |
| (gdb) |
| |
| Takes an optional file parameter. |
| |
| '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. |
| |
| 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. |
| |
| These commands take an optional parameter, a file name to which to |
| write the information. |
| |
| 'maint print reggroups [FILE]' |
| Print GDB's internal register group data structures. The optional |
| argument FILE tells to what file to write the information. |
| |
| 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 |
| |
| 'flushregs' |
| This command forces GDB to flush its internal register cache. |
| |
| '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. |
| |
| 'maint print user-registers' |
| List all currently available "user registers". User registers |
| typically provide alternate names for actual hardware registers. |
| They include the four "standard" registers '$fp', '$pc', '$sp', and |
| '$ps'. *Note standard registers::. User registers can be used in |
| expressions in the same way as the canonical register names, but |
| only the latter are listed by the 'info registers' and 'maint print |
| registers' commands. |
| |
| '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::. |
| |
| '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. |
| |
| '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. |
| |
| 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. |
| |
| '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. |
| |
| 'maint set dwarf always-disassemble' |
| 'maint show dwarf always-disassemble' |
| Control the behavior of 'info address' when using DWARF debugging |
| information. |
| |
| 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. |
| |
| Here is an example of the resulting disassembly: |
| |
| (gdb) info addr argc |
| Symbol "argc" is a complex DWARF expression: |
| 1: DW_OP_fbreg 0 |
| |
| For more information on these expressions, see the DWARF standard |
| (http://www.dwarfstd.org/). |
| |
| 'maint set dwarf max-cache-age' |
| 'maint show dwarf max-cache-age' |
| Control the DWARF compilation unit cache. |
| |
| In object files with inter-compilation-unit references, such as |
| those produced by the GCC option '-feliminate-dwarf2-dups', the |
| DWARF 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. |
| |
| '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. |
| |
| Configuring with '--enable-profiling' arranges for GDB to be |
| compiled with the '-pg' compiler option. |
| |
| '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. |
| |
| 'maint set target-async' |
| 'maint show target-async' |
| This controls whether GDB targets operate in synchronous or |
| asynchronous mode (*note Background Execution::). Normally the |
| default is asynchronous, if it is available; but this can be |
| changed to more easily debug problems occurring only in synchronous |
| mode. |
| |
| 'maint set target-non-stop' |
| 'maint show target-non-stop' |
| |
| This controls whether GDB targets always operate in non-stop mode |
| even if 'set non-stop' is 'off' (*note Non-Stop Mode::). The |
| default is 'auto', meaning non-stop mode is enabled if supported by |
| the target. |
| |
| 'maint set target-non-stop auto' |
| This is the default mode. GDB controls the target in non-stop |
| mode if the target supports it. |
| |
| 'maint set target-non-stop on' |
| GDB controls the target in non-stop mode even if the target |
| does not indicate support. |
| |
| 'maint set target-non-stop off' |
| GDB does not control the target in non-stop mode even if the |
| target supports it. |
| |
| '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. |
| |
| '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. |
| |
| 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. |
| |
| The following command is useful for non-interactive invocations of |
| GDB, such as in the test suite. |
| |
| '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. |
| |
| 'show watchdog' |
| Show the current setting of the target wait timeout. |
| |
| |
| File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top |
| |
| Appendix E GDB Remote Serial Protocol |
| ************************************* |
| |
| * Menu: |
| |
| * 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:: |
| * Branch Trace Configuration Format:: |
| |
| |
| File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol |
| |
| E.1 Overview |
| ============ |
| |
| 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. |
| |
| In the examples below, '->' and '<-' are used to indicate transmitted |
| and received data, respectively. |
| |
| 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: |
| |
| $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). |
| |
| 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 |
| |
| 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 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): |
| |
| -> $PACKET-DATA#CHECKSUM |
| <- + |
| |
| The '+'/'-' acknowledgments can be disabled once a connection is |
| established. *Note Packet Acknowledgment::, for details. |
| |
| 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. |
| |
| PACKET-DATA consists of a sequence of characters with the exception |
| of '#' and '$' (see 'X' packet for additional exceptions). |
| |
| Fields within the packet should be separated using ',' ';' or ':'. |
| Except where otherwise noted all numbers are represented in HEX with |
| leading zeros suppressed. |
| |
| 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). |
| |
| 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 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 at ADDR, which is the 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.). |
| Depending on the operation to be performed, OP should be 'c' for |
| step and continue operations (note that this is deprecated, |
| supporting the 'vCont' command is a better option), and '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. |
| |
| The exact effect of this packet is not specified. |
| |
| For a bare-metal target, it may power cycle or reset the target |
| system. For that reason, the 'k' packet has no reply. |
| |
| For a single-process target, it may kill that process if possible. |
| |
| A multiple-process target may choose to kill just one process, or |
| all that are under GDB's control. For more precise control, use |
| the vKill packet (*note vKill packet::). |
| |
| If the target system immediately closes the connection in response |
| to 'k', GDB does not consider the lack of packet acknowledgment to |
| be an error, and assumes the kill was successful. |
| |
| If connected using 'target extended-remote', and the target does |
| not close the connection in response to a kill request, GDB probes |
| the target state as if a new connection was opened (*note ? |
| packet::). |
| |
| 'm ADDR,LENGTH' |
| Read LENGTH addressable memory units starting at address ADDR |
| (*note addressable memory unit::). 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 addressable |
| memory units 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 addressable memory units starting at address ADDR |
| (*note addressable memory unit::). The data is given by XX...; |
| 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. The 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, resuming at ADDR. 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, both of which are are 4 byte long. There must be |
| at least 3 digits in ADDR. |
| |
| '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. |
| |
| 'vCtrlC' |
| Interrupt remote target as if a control-C was pressed on the remote |
| terminal. This is the equivalent to reacting to the '^C' ('\003', |
| the control-C character) character in all-stop mode while the |
| target is running, except this works in non-stop mode. *Note |
| interrupting remote targets::, for more info on the all-stop |
| variant. |
| |
| Reply: |
| 'E NN' |
| for an error |
| 'OK' |
| for success |
| |
| '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, which 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. |
| Memory is specified by its address ADDR and number of addressable |
| memory units LENGTH (*note addressable memory unit::); '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. |
| |
| See also the 'swbreak' stop reason (*note swbreak stop reason::) |
| for how to best report a memory breakpoint event to GDB. |
| |
| 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. The 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. The |
| number of bytes to watch is specified by KIND. |
| |
| 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. The |
| number of bytes to watch is specified by KIND. |
| |
| 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. The |
| number of bytes to watch is specified by KIND. |
| |
| 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. The data 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. The 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. |
| |
| 'syscall_entry' |
| 'syscall_return' |
| The packet indicates a syscall entry or return, and R is the |
| syscall number, 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. The R part 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. |
| |
| 'swbreak' |
| The packet indicates a memory breakpoint instruction was |
| executed, irrespective of whether it was GDB that planted the |
| breakpoint or the breakpoint is hardcoded in the program. The |
| R part must be left empty. |
| |
| On some architectures, such as x86, at the architecture level, |
| when a breakpoint instruction executes the program counter |
| points at the breakpoint address plus an offset. On such |
| targets, the stub is responsible for adjusting the PC to point |
| back at the breakpoint address. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| This packet is required for correct non-stop mode operation. |
| |
| 'hwbreak' |
| The packet indicates the target stopped for a hardware |
| breakpoint. The R part must be left empty. |
| |
| The same remarks about 'qSupported' and non-stop mode above |
| apply. |
| |
| 'fork' |
| The packet indicates that 'fork' was called, and R is the |
| thread ID of the new child process. Refer to *note thread-id |
| syntax:: for the format of the THREAD-ID field. This packet |
| is only applicable to targets that support fork events. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| 'vfork' |
| The packet indicates that 'vfork' was called, and R is the |
| thread ID of the new child process. Refer to *note thread-id |
| syntax:: for the format of the THREAD-ID field. This packet |
| is only applicable to targets that support vfork events. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| 'vforkdone' |
| The packet indicates that a child process created by a vfork |
| has either called 'exec' or terminated, so that the address |
| spaces of the parent and child process are no longer shared. |
| The R part is ignored. This packet is only applicable to |
| targets that support vforkdone events. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| 'exec' |
| The packet indicates that 'execve' was called, and R is the |
| absolute pathname of the file that was executed, in hex. This |
| packet is only applicable to targets that support exec events. |
| |
| This packet should not be sent by default; older GDB versions |
| did not support it. GDB requests it, by supplying an |
| appropriate 'qSupported' feature (*note qSupported::). The |
| remote stub must also supply the appropriate 'qSupported' |
| feature indicating support. |
| |
| 'create' |
| The packet indicates that the thread was just created. The |
| new thread is stopped until GDB sets it running with a |
| resumption packet (*note vCont packet::). This packet should |
| not be sent by default; GDB requests it with the *note |
| QThreadEvents:: packet. See also the 'w' (*note thread exit |
| event::) remote reply below. |
| |
| '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. |
| |
| 'w AA ; TID' |
| |
| The thread exited, and AA is the exit status. This response should |
| not be sent by default; GDB requests it with the *note |
| QThreadEvents:: packet. See also *note thread create event:: |
| above. |
| |
| 'N' |
| There are no resumed threads left in the target. In other words, |
| even though the process is alive, the last resumed thread has |
| exited. For example, say the target process has two threads: |
| thread 1 and thread 2. The client leaves thread 1 stopped, and |
| resumes thread 2, which subsequently exits. At this point, even |
| though the process is still alive, and thus no 'W' stop reply is |
| sent, no thread is actually executing either. The 'N' stop reply |
| thus informs the client that it can stop waiting for stop replies. |
| This packet should not be sent by default; older GDB versions did |
| not support it. GDB requests it, by supplying an appropriate |
| 'qSupported' feature (*note qSupported::). The remote stub must |
| also supply the appropriate 'qSupported' feature indicating |
| support. |
| |
| '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. The error number NN is given as 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. |
| |
| _Note: GDB will send the 'qfThreadInfo' query during the initial |
| connection with the remote target, and the very first thread ID |
| mentioned in the reply will be stopped by GDB in a subsequent |
| message. Therefore, the stub should ensure that the first thread |
| ID in the 'qfThreadInfo' reply is suitable for being stopped by |
| GDB._ |
| |
| '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. The error number NN is given as 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, THREADID (eight hex |
| digits), from the target. 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. The error number NN is given as 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::. |
| |
| 'QCatchSyscalls:1 [;SYSNO]...' |
| 'QCatchSyscalls:0' |
| Enable ('QCatchSyscalls:1') or disable ('QCatchSyscalls:0') |
| catching syscalls from the inferior process. |
| |
| For 'QCatchSyscalls:1', each listed syscall SYSNO (encoded in hex) |
| should be reported to GDB. If no syscall SYSNO is listed, every |
| system call should be reported. |
| |
| Note that if a syscall not in the list is reported, GDB will still |
| filter the event according to its own list from all corresponding |
| 'catch syscall' commands. However, it is more efficient to only |
| report the requested syscalls. |
| |
| Multiple 'QCatchSyscalls:1' packets do not combine; any earlier |
| 'QCatchSyscalls:1' list is completely replaced by the new list. |
| |
| If the inferior process execs, the state of 'QCatchSyscalls' is |
| kept for the new process too. On targets where exec may affect |
| syscall numbers, for example with exec between 32 and 64-bit |
| processes, the client should send a new packet with the new syscall |
| list. |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. NN are hex digits. |
| |
| '' |
| An empty reply indicates that 'QCatchSyscalls' is not |
| supported by the stub. |
| |
| Use of this packet is controlled by the 'set remote catch-syscalls' |
| command (*note set remote catch-syscalls: Remote Configuration.). |
| This packet is not probed by default; the remote stub must request |
| it, by supplying an appropriate 'qSupported' response (*note |
| qSupported::). |
| |
| '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. The error number NN is given as 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. The error number NN is given as 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::). |
| |
| 'QThreadEvents:1' |
| 'QThreadEvents:0' |
| |
| Enable ('QThreadEvents:1') or disable ('QThreadEvents:0') reporting |
| of thread create and exit events. *Note thread create event::, for |
| the reply specifications. For example, this is used in non-stop |
| mode when GDB stops a set of threads and synchronously waits for |
| the their corresponding stop replies. Without exit events, if one |
| of the threads exits, GDB would hang forever not knowing that it |
| should no longer expect a stop for that same thread. GDB does not |
| enable this feature unless the stub reports that it supports it by |
| including 'QThreadEvents+' in its 'qSupported' reply. |
| |
| Reply: |
| 'OK' |
| The request succeeded. |
| |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| |
| '' |
| An empty reply indicates that 'QThreadEvents' is not supported |
| by the stub. |
| |
| Use of this packet is controlled by the 'set remote thread-events' |
| command (*note set remote thread-events: Remote Configuration.). |
| |
| '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.) |
| |
| 'qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' |
| Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. Both ADDRESS |
| and LENGTH are encoded in hex; SEARCH-PATTERN is a sequence of |
| bytes, also hex encoded. |
| |
| 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.). |
| |
| 'swbreak' |
| This feature indicates whether GDB supports the swbreak stop |
| reason in stop replies. *Note swbreak stop reason::, for |
| details. |
| |
| 'hwbreak' |
| This feature indicates whether GDB supports the hwbreak stop |
| reason in stop replies. *Note swbreak stop reason::, for |
| details. |
| |
| 'fork-events' |
| This feature indicates whether GDB supports fork event |
| extensions to the remote protocol. GDB does not use such |
| extensions unless the stub also reports that it supports them |
| by including 'fork-events+' in its 'qSupported' reply. |
| |
| 'vfork-events' |
| This feature indicates whether GDB supports vfork event |
| extensions to the remote protocol. GDB does not use such |
| extensions unless the stub also reports that it supports them |
| by including 'vfork-events+' in its 'qSupported' reply. |
| |
| 'exec-events' |
| This feature indicates whether GDB supports exec event |
| extensions to the remote protocol. GDB does not use such |
| extensions unless the stub also reports that it supports them |
| by including 'exec-events+' in its 'qSupported' reply. |
| |
| 'vContSupported' |
| This feature indicates whether GDB wants to know the supported |
| actions in the reply to 'vCont?' packet. |
| |
| 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 |
| Required Allowed |
| |
| 'PacketSize' Yes '-' No |
| |
| 'qXfer:auxv:read' No '-' Yes |
| |
| 'qXfer:btrace:read' No '-' Yes |
| |
| 'qXfer:btrace-conf:read' No '-' Yes |
| |
| 'qXfer:exec-file: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 |
| |
| 'Qbtrace:pt' Yes '-' Yes |
| |
| 'Qbtrace-conf:bts:size' Yes '-' Yes |
| |
| 'Qbtrace-conf:pt:size' Yes '-' Yes |
| |
| 'QNonStop' No '-' Yes |
| |
| 'QCatchSyscalls' 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 |
| |
| 'swbreak' No '-' No |
| |
| 'hwbreak' No '-' No |
| |
| 'fork-events' No '-' No |
| |
| 'vfork-events' No '-' No |
| |
| 'exec-events' No '-' No |
| |
| 'QThreadEvents' No '-' No |
| |
| 'no-resumed' 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:btrace-conf:read' |
| The remote stub understands the 'qXfer:btrace-conf:read' |
| packet (*note qXfer btrace-conf read::). |
| |
| 'qXfer:exec-file:read' |
| The remote stub understands the 'qXfer:exec-file:read' packet |
| (*note qXfer executable filename 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::). |
| |
| 'QCatchSyscalls' |
| The remote stub understands the 'QCatchSyscalls' packet (*note |
| QCatchSyscalls::). |
| |
| 'QPassSignals' |
| The remote stub understands the 'QPassSignals' packet (*note |
| QPassSignals::). |
| |
| 'QStartNoAckMode' |
| The remote stub understands the 'QStartNoAckMode' packet and |
| prefers to operate in no-acknowledgment mode. *Note Packet |
| Acknowledgment::. |
| |
| '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::). |
| |
| '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.). |
| |
| 'ConditionalTracepoints' |
| The remote stub accepts and implements conditional expressions |
| defined for tracepoints (*note Tracepoint Conditions::). |
| |
| 'ReverseContinue' |
| The remote stub accepts and implements the reverse continue |
| packet (*note bc::). |
| |
| 'ReverseStep' |
| The remote stub accepts and implements the reverse step packet |
| (*note bs::). |
| |
| 'TracepointSource' |
| The remote stub understands the 'QTDPsrc' packet that supplies |
| the source form of tracepoint definitions. |
| |
| 'QAgent' |
| The remote stub understands the 'QAgent' packet. |
| |
| 'QAllow' |
| The remote stub understands the 'QAllow' packet. |
| |
| 'QDisableRandomization' |
| The remote stub understands the 'QDisableRandomization' |
| packet. |
| |
| 'StaticTracepoint' |
| The remote stub supports static tracepoints. |
| |
| 'InstallInTrace' |
| The remote stub supports installing tracepoint in tracing. |
| |
| '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. |
| |
| 'QTBuffer:size' |
| The remote stub supports the 'QTBuffer:size' (*note |
| QTBuffer-size::) packet that allows to change the size of the |
| trace buffer. |
| |
| 'tracenz' |
| The remote stub supports the 'tracenz' bytecode for collecting |
| strings. See *note Bytecode Descriptions:: for details about |
| the bytecode. |
| |
| 'BreakpointCommands' |
| The remote stub supports running a breakpoint's command list |
| itself, rather than reporting the hit to GDB. |
| |
| 'Qbtrace:off' |
| The remote stub understands the 'Qbtrace:off' packet. |
| |
| 'Qbtrace:bts' |
| The remote stub understands the 'Qbtrace:bts' packet. |
| |
| 'Qbtrace:pt' |
| The remote stub understands the 'Qbtrace:pt' packet. |
| |
| 'Qbtrace-conf:bts:size' |
| The remote stub understands the 'Qbtrace-conf:bts:size' |
| packet. |
| |
| 'Qbtrace-conf:pt:size' |
| The remote stub understands the 'Qbtrace-conf:pt:size' packet. |
| |
| 'swbreak' |
| The remote stub reports the 'swbreak' stop reason for memory |
| breakpoints. |
| |
| 'hwbreak' |
| The remote stub reports the 'hwbreak' stop reason for hardware |
| breakpoints. |
| |
| 'fork-events' |
| The remote stub reports the 'fork' stop reason for fork |
| events. |
| |
| 'vfork-events' |
| The remote stub reports the 'vfork' stop reason for vfork |
| events and vforkdone events. |
| |
| 'exec-events' |
| The remote stub reports the 'exec' stop reason for exec |
| events. |
| |
| 'vContSupported' |
| The remote stub reports the supported actions in the reply to |
| 'vCont?' packet. |
| |
| 'QThreadEvents' |
| The remote stub understands the 'QThreadEvents' packet. |
| |
| 'no-resumed' |
| The remote stub reports the 'N' stop reply. |
| |
| 'qSymbol::' |
| Notify the target that GDB is prepared to serve symbol lookup |
| requests. Accept requests from the target for the values of |
| symbols. |
| |
| Reply: |
| 'OK' |
| The target does not need to look up any (more) symbols. |
| '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. |
| |
| 'qSymbol:SYM_VALUE:SYM_NAME' |
| Set the value of SYM_NAME to SYM_VALUE. |
| |
| SYM_NAME (hex encoded) is the name of a symbol whose value the |
| target has previously requested. |
| |
| 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. |
| |
| Reply: |
| 'OK' |
| The target does not need to look up any (more) symbols. |
| '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. |
| |
| 'qTBuffer' |
| 'QTBuffer' |
| 'QTDisconnected' |
| 'QTDP' |
| 'QTDPsrc' |
| 'QTDV' |
| 'qTfP' |
| 'qTfV' |
| 'QTFrame' |
| 'qTMinFTPILen' |
| |
| *Note Tracepoint Packets::. |
| |
| 'qThreadExtraInfo,THREAD-ID' |
| Obtain from the target OS a printable string description of thread |
| attributes for the thread THREAD-ID; see *note thread-id syntax::, |
| for the forms of THREAD-ID. 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'. |
| |
| 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.) |
| |
| 'QTNotes' |
| 'qTP' |
| 'QTSave' |
| 'qTsP' |
| 'qTsV' |
| 'QTStart' |
| 'QTStop' |
| 'QTEnable' |
| 'QTDisable' |
| 'QTinit' |
| 'QTro' |
| 'qTStatus' |
| 'qTV' |
| 'qTfSTM' |
| 'qTsSTM' |
| 'qTSTMat' |
| *Note Tracepoint Packets::. |
| |
| '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. |
| |
| Here are the specific requests of this form defined so far. All |
| 'qXfer:OBJECT:read:...' requests use the same reply formats, listed |
| below. |
| |
| 'qXfer:auxv:read::OFFSET,LENGTH' |
| Access the target's "auxiliary vector". *Note auxiliary |
| vector: OS Information. Note ANNEX must be empty. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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: |
| |
| 'all' |
| Returns all available branch trace. |
| |
| 'new' |
| Returns all available branch trace if the branch trace |
| changed since the last read request. |
| |
| 'delta' |
| Returns the new branch trace since the last read request. |
| Adds a new block to the end of the trace that begins at |
| zero and ends at the source location of the first branch |
| in the trace buffer. This extra block is used to stitch |
| traces together. |
| |
| If the trace buffer overflowed, returns an error |
| indicating the overflow. |
| |
| This packet is not probed by default; the remote stub must |
| request it by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:btrace-conf:read::OFFSET,LENGTH' |
| |
| Return a description of the current branch trace |
| configuration. *Note Branch Trace Configuration Format::. |
| |
| This packet is not probed by default; the remote stub must |
| request it by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:exec-file:read:ANNEX:OFFSET,LENGTH' |
| Return the full absolute name of the file that was executed to |
| create a process running on the remote system. The annex |
| specifies the numeric process ID of the process to query, |
| encoded as a hexadecimal number. If the annex part is empty |
| the remote stub should return the filename corresponding to |
| the currently executing process. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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::). |
| |
| 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. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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::). |
| |
| This packet is optional for better performance on SVR4 |
| targets. GDB uses memory read packets to read the SVR4 |
| library list otherwise. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 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: |
| |
| '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. |
| |
| '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. |
| |
| Arguments that are not understood by the remote stub will be |
| silently ignored. |
| |
| '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::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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. |
| |
| This packet is not probed by default. |
| |
| '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. |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| 'qXfer:osdata:read::OFFSET,LENGTH' |
| Access the target's "operating system information". *Note |
| Operating System Information::. |
| |
| 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). It is |
| possible for DATA to have fewer bytes than the LENGTH in the |
| request. |
| |
| 'l DATA' |
| Data DATA (*note Binary Data::) has been read from the target. |
| There is no more data to be read. It is possible for DATA to |
| 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. |
| |
| 'E00' |
| The request was malformed, or ANNEX was invalid. |
| |
| 'E NN' |
| The offset was invalid, or there was an error encountered |
| reading the data. The NN part is a hex-encoded 'errno' value. |
| |
| '' |
| 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. The binary-encoded data (*note Binary Data::) to be written |
| is given by DATA.... The content and encoding of ANNEX is specific |
| to OBJECT; it can supply additional details about what data to |
| access. |
| |
| Here are the specific requests of this form defined so far. All |
| 'qXfer:OBJECT:write:...' requests use the same reply formats, |
| listed below. |
| |
| '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::). |
| |
| This packet is not probed by default; the remote stub must |
| request it, by supplying an appropriate 'qSupported' response |
| (*note qSupported::). |
| |
| '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::). |
| |
| Reply: |
| 'NN' |
| NN (hex encoded) is the number of bytes written. This may be |
| fewer bytes than supplied in the request. |
| |
| 'E00' |
| The request was malformed, or ANNEX was invalid. |
| |
| 'E NN' |
| The offset was invalid, or there was an error encountered |
| writing the data. The NN part is a hex-encoded 'errno' value. |
| |
| '' |
| An empty reply indicates the OBJECT string was not recognized |
| by the stub, or that the object does not support writing. |
| |
| '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. |
| |
| '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. |
| |
| Reply: |
| '1' |
| The remote server attached to an existing process. |
| '0' |
| The remote server created a new process. |
| 'E NN' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace:bts' |
| Enable branch tracing for the current thread using Branch Trace |
| Store. |
| |
| Reply: |
| 'OK' |
| Branch tracing has been enabled. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace:pt' |
| Enable branch tracing for the current thread using Intel Processor |
| Trace. |
| |
| Reply: |
| 'OK' |
| Branch tracing has been enabled. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace:off' |
| Disable branch tracing for the current thread. |
| |
| Reply: |
| 'OK' |
| Branch tracing has been disabled. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace-conf:bts:size=VALUE' |
| Set the requested ring buffer size for new threads that use the |
| btrace recording method in bts format. |
| |
| Reply: |
| 'OK' |
| The ring buffer size has been set. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| 'Qbtrace-conf:pt:size=VALUE' |
| Set the requested ring buffer size for new threads that use the |
| btrace recording method in pt format. |
| |
| Reply: |
| 'OK' |
| The ring buffer size has been set. |
| 'E.errtext' |
| A badly formed request or an error was encountered. |
| |
| ---------- 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: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol |
| |
| E.5 Architecture-Specific Protocol Details |
| ========================================== |
| |
| 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. |
| |
| * Menu: |
| |
| * ARM-Specific Protocol Details:: |
| * MIPS-Specific Protocol Details:: |
| |
| |
| 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 |
| ----------------------------------- |
| |
| * Menu: |
| |
| * ARM Breakpoint Kinds:: |
| |
| |
| File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details |
| |
| E.5.1.1 ARM Breakpoint Kinds |
| ............................ |
| |
| These breakpoint kinds are defined for the 'Z0' and 'Z1' packets. |
| |
| 2 |
| 16-bit Thumb mode breakpoint. |
| |
| 3 |
| 32-bit Thumb mode (Thumb-2) breakpoint. |
| |
| 4 |
| 32-bit ARM mode breakpoint. |
| |
| |
| File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details |
| |
| E.5.2 MIPS-specific Protocol Details |
| ------------------------------------ |
| |
| * Menu: |
| |
| * MIPS Register packet Format:: |
| * MIPS Breakpoint Kinds:: |
| |
| |
| 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 |
| ................................... |
| |
| 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. |
| |
| 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. |
| |
| 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'. |
| |
| |
| File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details |
| |
| E.5.2.2 MIPS Breakpoint Kinds |
| ............................. |
| |
| These breakpoint kinds are defined for the 'Z0' and 'Z1' packets. |
| |
| 2 |
| 16-bit MIPS16 mode breakpoint. |
| |
| 3 |
| 16-bit microMIPS mode breakpoint. |
| |
| 4 |
| 32-bit standard MIPS mode breakpoint. |
| |
| 5 |
| 32-bit microMIPS mode breakpoint. |
| |
| |
| 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::). |
| |
| '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. The STEP gives the tracepoint's step count, and PASS |
| gives 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. |
| |
| Replies: |
| 'OK' |
| The packet was understood and carried out. |
| 'qRelocInsn' |
| *Note Relocate instruction reply packet: Tracepoint Packets. |
| '' |
| The packet was not recognized. |
| |
| 'QTDP:-N:ADDR:[S]ACTION...[-]' |
| Define actions to be taken when a tracepoint is hit. The 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. |
| |
| 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. |
| |
| The 'ACTION...' portion of the packet is a series of actions, |
| concatenated without separators. Each action has one of the |
| following forms: |
| |
| 'R MASK' |
| Collect the registers whose bits are set in MASK, 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. |
| |
| '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). |
| |
| 'X LEN,EXPR' |
| Evaluate EXPR, whose length is LEN, and collect memory as it |
| directs. The agent expression EXPR is 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). |
| |
| 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.) |
| |
| Replies: |
| 'OK' |
| The packet was understood and carried out. |
| 'qRelocInsn' |
| *Note Relocate instruction reply packet: Tracepoint Packets. |
| '' |
| 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. The 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. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 'QTDV:N:VALUE:BUILTIN:NAME' |
| 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. The value BUILTIN should be 1 (one) if the trace |
| state variable is builtin and 0 (zero) if it is not builtin. GDB |
| only sets BUILTIN to 1 if a previous 'qTfV' or 'qTsV' packet had it |
| set. The contents of NAME is the hex-encoded name (without the |
| leading '$') of the trace state variable. |
| |
| '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. |
| |
| 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: |
| |
| '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. |
| |
| '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). |
| |
| '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. |
| |
| Replies: |
| |
| '0' |
| The minimum instruction length is currently unknown. |
| 'LENGTH' |
| The minimum instruction length is LENGTH, where LENGTH is a |
| hexadecimal number greater or equal to 1. A reply of 1 means |
| that a fast tracepoint may be placed on any instruction |
| regardless of size. |
| 'E' |
| An error has occurred. |
| '' |
| An empty reply indicates that the request is not supported by |
| the stub. |
| |
| '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.). |
| |
| 'QTStop' |
| End the tracepoint experiment. Stop collecting trace frames. |
| |
| '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. |
| |
| '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. |
| |
| 'QTinit' |
| Clear the table of tracepoints, and empty the trace frame buffer. |
| |
| '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. |
| |
| 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. |
| |
| '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. |
| |
| 'qTStatus' |
| Ask the stub if there is a trace experiment running right now. |
| |
| 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. |
| |
| If the trace is not running, the agent may report any of several |
| explanations as one of the optional fields: |
| |
| 'tnotrun:0' |
| No trace has been run yet. |
| |
| '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. |
| |
| 'tfull:0' |
| The trace stopped because the trace buffer filled up. |
| |
| 'tdisconnected:0' |
| The trace stopped because GDB disconnected from the target. |
| |
| 'tpasscount:TPNUM' |
| The trace stopped because tracepoint TPNUM exceeded its pass |
| count. |
| |
| '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); |
| it is hex encoded. |
| |
| 'tunknown:0' |
| The trace stopped for some other reason. |
| |
| 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. |
| |
| 'tframes:N' |
| The number of trace frames in the buffer. |
| |
| '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. |
| |
| 'tsize:N' |
| The total size of the trace buffer, in bytes. |
| |
| 'tfree:N' |
| The number of bytes still unused in the buffer. |
| |
| '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. |
| |
| '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. |
| |
| 'qTP:TP:ADDR' |
| Ask the stub for the current state of tracepoint number TP at |
| address ADDR. |
| |
| 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. |
| |
| 'qTV:VAR' |
| Ask the stub for the value of the trace state variable number VAR. |
| |
| 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. |
| |
| '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. |
| |
| '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. |
| |
| '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: |
| |
| Reply: |
| 'm ADDRESS:ID:EXTRA' |
| A single marker |
| 'm ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...' |
| a comma-separated list of markers |
| 'l' |
| (lower case letter 'L') denotes end of list. |
| 'E NN' |
| An error occurred. The error number NN is given as hex |
| digits. |
| '' |
| An empty reply indicates that the request is not supported by |
| the stub. |
| |
| The ADDRESS is encoded in hex; ID and EXTRA are strings encoded in |
| hex. |
| |
| 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. |
| |
| 'QTSave:FILENAME' |
| This packet directs the target to save trace data to the file name |
| FILENAME in the target's filesystem. The FILENAME is encoded as a |
| hex string; the interpretation of the file name (relative vs |
| absolute, wild cards, etc) is up to the target. |
| |
| '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. |
| |
| '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. |
| |
| '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. |
| |
| '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. |
| |
| E.6.1 Relocate instruction reply packet |
| --------------------------------------- |
| |
| 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. |
| |
| 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: |
| |
| '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. |
| |
| Replies: |
| 'qRelocInsn:ADJUSTED_SIZE' |
| Informs the stub the relocation is complete. The ADJUSTED_SIZE is |
| the length in bytes of resulting relocated instruction sequence. |
| 'E NN' |
| A badly formed request was detected, or an error was encountered |
| while relocating the instruction. |
| |
| |
| File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol |
| |
| E.7 Host I/O Packets |
| ==================== |
| |
| 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: |
| |
| '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::). |
| |
| The valid responses to Host I/O packets are: |
| |
| '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 specifying 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. |
| |
| '' |
| An empty response indicates that this operation is not recognized. |
| |
| These are the supported Host I/O operations: |
| |
| 'vFile:open: FILENAME, FLAGS, MODE' |
| Open a file at FILENAME and return a file descriptor for it, or |
| return -1 if an error occurs. The FILENAME 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. |
| |
| 'vFile:close: FD' |
| Close the open file corresponding to FD and return 0, or -1 if an |
| error occurs. |
| |
| '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. |
| |
| 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. |
| |
| '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. |
| |
| 'vFile:fstat: FD' |
| Get information about the open file corresponding to FD. On |
| success the information is returned as a binary attachment and the |
| return value is the size of this attachment in bytes. If an error |
| occurs the return value is -1. The format of the returned binary |
| attachment is as described in *note struct stat::. |
| |
| 'vFile:unlink: FILENAME' |
| Delete the file at FILENAME on the target. Return 0, or -1 if an |
| error occurs. The FILENAME 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. |
| |
| 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. |
| |
| 'vFile:setfs: PID' |
| Select the filesystem on which 'vFile' operations with FILENAME |
| arguments will operate. This is required for GDB to be able to |
| access files on remote targets where the remote stub does not share |
| a common filesystem with the inferior(s). |
| |
| If PID is nonzero, select the filesystem as seen by process PID. |
| If PID is zero, select the filesystem as seen by the remote stub. |
| Return 0 on success, or -1 if an error occurs. If 'vFile:setfs:' |
| indicates success, the selected filesystem remains selected until |
| the next successful 'vFile:setfs:' operation. |
| |
| |
| File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol |
| |
| E.8 Interrupts |
| ============== |
| |
| In all-stop mode, 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'. |
| |
| 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. |
| |
| '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. |
| |
| '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. |
| |
| In non-stop mode, because packet resumptions are asynchronous (*note |
| vCont packet::), GDB is always free to send a remote command to the |
| remote stub, even when the target is running. For that reason, GDB |
| instead sends a regular packet (*note vCtrlC packet::) with the usual |
| packet framing instead of the single byte '0x03'. |
| |
| 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 queued and the program will be interrupted when it is |
| resumed next time. |
| |
| |
| File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol |
| |
| 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. |
| |
| 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. |
| |
| Every notification's DATA begins with a name, which contains no colon |
| characters, followed by a colon character. |
| |
| 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. |
| |
| 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. |
| |
| (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, and NAME |
| specifying 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. |
| |
| 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 mode. |
| *note Stop Reply Packets::. |
| Refer to |
| *note Remote Non-Stop::, |
| for information on how |
| these notifications are |
| acknowledged by GDB. |
| |
| |
| File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol |
| |
| E.10 Remote Protocol Support for Non-Stop Mode |
| ============================================== |
| |
| 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::). |
| |
| 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. |
| |
| 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. |
| |
| 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'. |
| |
| If the stub supports non-stop mode, it should also support the |
| 'swbreak' stop reason if software breakpoints are supported, and the |
| 'hwbreak' stop reason if hardware breakpoints are supported (*note |
| swbreak stop reason::). This is because given the asynchronous nature |
| of non-stop mode, between the time a thread hits a breakpoint and the |
| time the event is finally processed by GDB, the breakpoint may have |
| already been removed from the target. Due to this, GDB needs to be able |
| to tell whether a trap stop was caused by a delayed breakpoint event, |
| which should be ignored, as opposed to a random trap signal, which |
| should be reported to the user. Note the 'swbreak' feature implies that |
| the target is responsible for adjusting the PC when a software |
| breakpoint triggers, if necessary, such as on the x86 architecture. |
| |
| |
| File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol |
| |
| E.11 Packet Acknowledgment |
| ========================== |
| |
| 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. |
| |
| 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::. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol |
| |
| E.12 Examples |
| ============= |
| |
| Example sequence of a target being re-started. Notice how the restart |
| does not get any direct output: |
| |
| -> R00 |
| <- + |
| _target restarts_ |
| -> ? |
| <- + |
| <- T001:1234123412341234 |
| -> + |
| |
| Example sequence of a target being stepped by a single instruction: |
| |
| -> 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 |
| |
| E.13 File-I/O Remote Protocol Extension |
| ======================================= |
| |
| * Menu: |
| |
| * 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: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension |
| |
| E.13.1 File-I/O Overview |
| ------------------------ |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| (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 |
| |
| 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: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension |
| |
| E.13.2 Protocol Basics |
| ---------------------- |
| |
| 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: |
| |
| * A unique identifier for the requested system call. |
| |
| * 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. |
| |
| At this point, GDB has to perform the following actions. |
| |
| * 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. |
| |
| * GDB translates all value from protocol representation to host |
| representation as needed. Datatypes are coerced into the host |
| types. |
| |
| * GDB calls the system call. |
| |
| * It then coerces datatypes back to protocol representation. |
| |
| * 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. |
| |
| Eventually GDB replies with another 'F' packet which contains all |
| necessary information for the target to continue. This at least |
| contains |
| |
| * Return value. |
| |
| * 'errno', if has been changed by the system call. |
| |
| * "Ctrl-C" flag. |
| |
| After having done the needed type and value coercion, the target |
| continues the latest continue or step action. |
| |
| |
| 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.3 The 'F' Request Packet |
| ----------------------------- |
| |
| The 'F' request packet has the following format: |
| |
| '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. |
| |
| |
| 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 |
| |
| E.13.4 The 'F' Reply Packet |
| --------------------------- |
| |
| The 'F' reply packet has the following format: |
| |
| 'FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT' |
| |
| RETCODE is the return code of the system call as hexadecimal value. |
| |
| ERRNO is the 'errno' set by the call, in protocol-specific |
| representation. This parameter can be omitted if the call was |
| successful. |
| |
| 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': |
| |
| F0,0,C |
| |
| or, if the call was interrupted before the host call has been |
| performed: |
| |
| F-1,4,C |
| |
| assuming 4 is the protocol-specific representation of 'EINTR'. |
| |
| |
| File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension |
| |
| E.13.5 The 'Ctrl-C' Message |
| --------------------------- |
| |
| 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. |
| |
| It's important for the target to know in which state the system call |
| was interrupted. There are two possible cases: |
| |
| * The system call hasn't been performed on the host yet. |
| |
| * The system call on the host has been finished. |
| |
| 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. |
| |
| 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: 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 |
| ------------------ |
| |
| 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: |
| |
| * The user types 'Ctrl-c'. The behaviour is as explained above, and |
| the 'read' system call is treated as finished. |
| |
| * The user presses <RET>. This is treated as end of input with a |
| trailing newline. |
| |
| * 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. |
| |
| 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 |
| |
| E.13.7 List of Supported Calls |
| ------------------------------ |
| |
| * Menu: |
| |
| * open:: |
| * close:: |
| * read:: |
| * write:: |
| * lseek:: |
| * rename:: |
| * unlink:: |
| * stat/fstat:: |
| * gettimeofday:: |
| * isatty:: |
| * system:: |
| |
| |
| 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' |
| |
| FLAGS is the bitwise 'OR' of the following values: |
| |
| '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. |
| |
| 'O_EXCL' |
| When used with 'O_CREAT', if the file already exists it is an |
| error and open() fails. |
| |
| '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. |
| |
| 'O_APPEND' |
| The file is opened in append mode. |
| |
| 'O_RDONLY' |
| The file is opened for reading only. |
| |
| 'O_WRONLY' |
| The file is opened for writing only. |
| |
| 'O_RDWR' |
| The file is opened for reading and writing. |
| |
| Other bits are silently ignored. |
| |
| MODE is the bitwise 'OR' of the following values: |
| |
| 'S_IRUSR' |
| User has read permission. |
| |
| 'S_IWUSR' |
| User has write permission. |
| |
| 'S_IRGRP' |
| Group has read permission. |
| |
| 'S_IWGRP' |
| Group has write permission. |
| |
| 'S_IROTH' |
| Others have read permission. |
| |
| 'S_IWOTH' |
| Others have write permission. |
| |
| Other bits are silently ignored. |
| |
| Return value: |
| 'open' returns the new file descriptor or -1 if an error occurred. |
| |
| Errors: |
| |
| 'EEXIST' |
| PATHNAME already exists and 'O_CREAT' and 'O_EXCL' were used. |
| |
| 'EISDIR' |
| PATHNAME refers to a directory. |
| |
| 'EACCES' |
| The requested access is not allowed. |
| |
| 'ENAMETOOLONG' |
| PATHNAME was too long. |
| |
| 'ENOENT' |
| A directory component in PATHNAME does not exist. |
| |
| 'ENODEV' |
| PATHNAME refers to a device, pipe, named pipe or socket. |
| |
| 'EROFS' |
| PATHNAME refers to a file on a read-only filesystem and write |
| access was requested. |
| |
| 'EFAULT' |
| PATHNAME is an invalid pointer value. |
| |
| 'ENOSPC' |
| No space on device to create the file. |
| |
| 'EMFILE' |
| The process already has the maximum number of files open. |
| |
| 'ENFILE' |
| The limit on the total number of files open on the system has |
| been reached. |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| |
| File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls |
| |
| close |
| ..... |
| |
| Synopsis: |
| int close(int fd); |
| |
| Request: |
| 'Fclose,FD' |
| |
| Return value: |
| 'close' returns zero on success, or -1 if an error occurred. |
| |
| Errors: |
| |
| 'EBADF' |
| FD isn't a valid open file descriptor. |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| |
| File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls |
| |
| read |
| .... |
| |
| Synopsis: |
| int read(int fd, void *buf, unsigned int count); |
| |
| Request: |
| 'Fread,FD,BUFPTR,COUNT' |
| |
| 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. |
| |
| Errors: |
| |
| 'EBADF' |
| FD is not a valid file descriptor or is not open for reading. |
| |
| 'EFAULT' |
| BUFPTR is an invalid pointer value. |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| |
| File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls |
| |
| write |
| ..... |
| |
| Synopsis: |
| int write(int fd, const void *buf, unsigned int count); |
| |
| Request: |
| 'Fwrite,FD,BUFPTR,COUNT' |
| |
| Return value: |
| On success, the number of bytes written are returned. Zero |
| indicates nothing was written. On error, -1 is returned. |
| |
| Errors: |
| |
| 'EBADF' |
| FD is not a valid file descriptor or is not open for writing. |
| |
| 'EFAULT' |
| BUFPTR is an invalid pointer value. |
| |
| 'EFBIG' |
| An attempt was made to write a file that exceeds the |
| host-specific maximum file size allowed. |
| |
| 'ENOSPC' |
| No space on device to write the data. |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| |
| File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls |
| |
| lseek |
| ..... |
| |
| Synopsis: |
| long lseek (int fd, long offset, int flag); |
| |
| Request: |
| 'Flseek,FD,OFFSET,FLAG' |
| |
| FLAG is one of: |
| |
| 'SEEK_SET' |
| The offset is set to OFFSET bytes. |
| |
| 'SEEK_CUR' |
| The offset is set to its current location plus OFFSET bytes. |
| |
| '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. |
| |
| Errors: |
| |
| 'EBADF' |
| FD is not a valid open file descriptor. |
| |
| 'ESPIPE' |
| FD is associated with the GDB console. |
| |
| 'EINVAL' |
| FLAG is not a proper value. |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| |
| File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls |
| |
| rename |
| ...... |
| |
| Synopsis: |
| int rename(const char *oldpath, const char *newpath); |
| |
| Request: |
| 'Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN' |
| |
| Return value: |
| On success, zero is returned. On error, -1 is returned. |
| |
| Errors: |
| |
| 'EISDIR' |
| NEWPATH is an existing directory, but OLDPATH is not a |
| directory. |
| |
| 'EEXIST' |
| NEWPATH is a non-empty directory. |
| |
| 'EBUSY' |
| OLDPATH or NEWPATH is a directory that is in use by some |
| process. |
| |
| 'EINVAL' |
| An attempt was made to make a directory a subdirectory of |
| itself. |
| |
| '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. |
| |
| 'EFAULT' |
| OLDPATHPTR or NEWPATHPTR are invalid pointer values. |
| |
| 'EACCES' |
| No access to the file or the path of the file. |
| |
| 'ENAMETOOLONG' |
| |
| OLDPATH or NEWPATH was too long. |
| |
| 'ENOENT' |
| A directory component in OLDPATH or NEWPATH does not exist. |
| |
| 'EROFS' |
| The file is on a read-only filesystem. |
| |
| 'ENOSPC' |
| The device containing the file has no room for the new |
| directory entry. |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| |
| File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls |
| |
| unlink |
| ...... |
| |
| Synopsis: |
| int unlink(const char *pathname); |
| |
| Request: |
| 'Funlink,PATHNAMEPTR/LEN' |
| |
| Return value: |
| On success, zero is returned. On error, -1 is returned. |
| |
| Errors: |
| |
| 'EACCES' |
| No access to the file or the path of the file. |
| |
| 'EPERM' |
| The system does not allow unlinking of directories. |
| |
| 'EBUSY' |
| The file PATHNAME cannot be unlinked because it's being used |
| by another process. |
| |
| 'EFAULT' |
| PATHNAMEPTR is an invalid pointer value. |
| |
| 'ENAMETOOLONG' |
| PATHNAME was too long. |
| |
| 'ENOENT' |
| A directory component in PATHNAME does not exist. |
| |
| '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. |
| |
| |
| File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls |
| |
| stat/fstat |
| .......... |
| |
| Synopsis: |
| int stat(const char *pathname, struct stat *buf); |
| int fstat(int fd, struct stat *buf); |
| |
| Request: |
| 'Fstat,PATHNAMEPTR/LEN,BUFPTR' |
| 'Ffstat,FD,BUFPTR' |
| |
| Return value: |
| On success, zero is returned. On error, -1 is returned. |
| |
| Errors: |
| |
| 'EBADF' |
| FD is not a valid open file. |
| |
| 'ENOENT' |
| A directory component in PATHNAME does not exist or the path |
| is an empty string. |
| |
| 'ENOTDIR' |
| A component of the path is not a directory. |
| |
| 'EFAULT' |
| PATHNAMEPTR is an invalid pointer value. |
| |
| 'EACCES' |
| No access to the file or the path of the file. |
| |
| 'ENAMETOOLONG' |
| PATHNAME was too long. |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| |
| File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls |
| |
| gettimeofday |
| ............ |
| |
| Synopsis: |
| int gettimeofday(struct timeval *tv, void *tz); |
| |
| Request: |
| 'Fgettimeofday,TVPTR,TZPTR' |
| |
| Return value: |
| On success, 0 is returned, -1 otherwise. |
| |
| Errors: |
| |
| 'EINVAL' |
| TZ is a non-NULL pointer. |
| |
| 'EFAULT' |
| TVPTR and/or TZPTR is an invalid pointer value. |
| |
| |
| File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls |
| |
| isatty |
| ...... |
| |
| Synopsis: |
| int isatty(int fd); |
| |
| Request: |
| 'Fisatty,FD' |
| |
| Return value: |
| Returns 1 if FD refers to the GDB console, 0 otherwise. |
| |
| Errors: |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| 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: system, Prev: isatty, Up: List of Supported Calls |
| |
| system |
| ...... |
| |
| Synopsis: |
| int system(const char *command); |
| |
| Request: |
| 'Fsystem,COMMANDPTR/LEN' |
| |
| 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. |
| |
| Errors: |
| |
| 'EINTR' |
| The call was interrupted by the user. |
| |
| 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. |
| |
| 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. |
| |
| '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: 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: |
| |
| * Integral Datatypes:: |
| * Pointer Values:: |
| * Memory Transfer:: |
| * struct stat:: |
| * struct timeval:: |
| |
| |
| File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes |
| |
| Integral Datatypes |
| .................. |
| |
| The integral datatypes used in the system calls are 'int', 'unsigned |
| int', 'long', 'unsigned long', 'mode_t', and 'time_t'. |
| |
| 'int', 'unsigned int', 'mode_t' and 'time_t' are implemented as 32 |
| bit values in this protocol. |
| |
| 'long' and 'unsigned long' are implemented as 64 bit types. |
| |
| *Note Limits::, for corresponding MIN and MAX values (similar to |
| those in 'limits.h') to allow range checking on host and target. |
| |
| 'time_t' datatypes are defined as seconds since the Epoch. |
| |
| 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: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes |
| |
| Pointer Values |
| .............. |
| |
| 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. |
| |
| 1aaf/12 |
| |
| 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 |
| |
| 123456/d |
| |
| |
| File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes |
| |
| Memory Transfer |
| ............... |
| |
| 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. |
| |
| |
| File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes |
| |
| struct stat |
| ........... |
| |
| The buffer of type 'struct stat' used by the target and GDB is defined |
| as follows: |
| |
| 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 */ |
| }; |
| |
| 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 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. |
| |
| 'st_ino' |
| No valid meaning for the target. Transmitted unchanged. |
| |
| 'st_mode' |
| Valid mode bits are described in *note Constants::. Any other bits |
| have currently no meaning for the target. |
| |
| 'st_uid' |
| 'st_gid' |
| 'st_rdev' |
| No valid meaning for the target. Transmitted unchanged. |
| |
| '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 target gets a 'struct stat' of the above representation and is |
| responsible for coercing it to the target representation before |
| continuing. |
| |
| 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 |
| |
| struct timeval |
| .............. |
| |
| The buffer of type 'struct timeval' used by the File-I/O protocol is |
| defined as follows: |
| |
| struct timeval { |
| time_t tv_sec; /* second */ |
| long tv_usec; /* microsecond */ |
| }; |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension |
| |
| E.13.9 Constants |
| ---------------- |
| |
| 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. |
| |
| * Menu: |
| |
| * Open Flags:: |
| * mode_t Values:: |
| * Errno Values:: |
| * Lseek Flags:: |
| * Limits:: |
| |
| |
| File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants |
| |
| Open Flags |
| .......... |
| |
| All values are given in hexadecimal representation. |
| |
| 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: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants |
| |
| mode_t Values |
| ............. |
| |
| All values are given in octal representation. |
| |
| 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: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants |
| |
| Errno Values |
| ............ |
| |
| 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 |
| |
| 'EUNKNOWN' is used as a fallback error value if a host system returns |
| any error value not in the list of supported error numbers. |
| |
| |
| File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants |
| |
| Lseek Flags |
| ........... |
| |
| SEEK_SET 0 |
| SEEK_CUR 1 |
| SEEK_END 2 |
| |
| |
| File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants |
| |
| Limits |
| ...... |
| |
| All values are given in decimal representation. |
| |
| INT_MIN -2147483648 |
| INT_MAX 2147483647 |
| UINT_MAX 4294967295 |
| LONG_MIN -9223372036854775808 |
| LONG_MAX 9223372036854775807 |
| ULONG_MAX 18446744073709551615 |
| |
| |
| File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension |
| |
| E.13.10 File-I/O Examples |
| ------------------------- |
| |
| Example sequence of a write call, file descriptor 3, buffer is at target |
| address 0x1234, 6 bytes should be written: |
| |
| <- Fwrite,3,1234,6 |
| _request memory read from target_ |
| -> m1234,6 |
| <- XXXXXX |
| _return "6 bytes written"_ |
| -> F6 |
| |
| Example sequence of a read call, file descriptor 3, buffer is at |
| target address 0x1234, 6 bytes should be read: |
| |
| <- Fread,3,1234,6 |
| _request memory write to target_ |
| -> X1234,6:XXXXXX |
| _return "6 bytes read"_ |
| -> F6 |
| |
| Example sequence of a read call, call fails on the host due to |
| invalid file descriptor ('EBADF'): |
| |
| <- Fread,3,1234,6 |
| -> F-1,9 |
| |
| Example sequence of a read call, user presses 'Ctrl-c' before syscall |
| on host is called: |
| |
| <- Fread,3,1234,6 |
| -> F-1,4,C |
| <- T02 |
| |
| Example sequence of a read call, user presses 'Ctrl-c' after syscall |
| on host is called: |
| |
| <- Fread,3,1234,6 |
| -> X1234,6:XXXXXX |
| <- T02 |
| |
| |
| File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol |
| |
| E.14 Library List Format |
| ======================== |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| GDB must be linked with the Expat library to support XML library |
| lists. *Note Expat::. |
| |
| A simple memory map, with one loaded library relocated by a single |
| offset, looks like this: |
| |
| <library-list> |
| <library name="/lib/libc.so.6"> |
| <segment address="0x10000000"/> |
| </library> |
| </library-list> |
| |
| Another simple memory map, with one loaded library with three |
| allocated sections (.text, .data, .bss), looks like this: |
| |
| <library-list> |
| <library name="sharedlib.o"> |
| <section address="0x10000000"/> |
| <section address="0x20000000"/> |
| <section address="0x30000000"/> |
| </library> |
| </library-list> |
| |
| The format of a library list is described by this DTD: |
| |
| <!-- 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> |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol |
| |
| E.15 Library List Format for SVR4 Targets |
| ========================================= |
| |
| 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. |
| |
| 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: |
| |
| - 'name', the absolute file name from the 'l_name' field of 'struct |
| link_map'. |
| - 'lm' with address of 'struct link_map' used for TLS (Thread Local |
| Storage) access. |
| - '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. |
| - 'l_ld', which is memory address of the 'PT_DYNAMIC' segment |
| |
| 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. |
| |
| GDB must be linked with the Expat library to support XML SVR4 library |
| lists. *Note Expat::. |
| |
| A simple memory map, with two loaded libraries (which do not use |
| prelink), looks like this: |
| |
| <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> |
| |
| The format of an SVR4 library list is described by this DTD: |
| |
| <!-- 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> |
| |
| |
| File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol |
| |
| E.16 Memory Map Format |
| ====================== |
| |
| 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. |
| |
| 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. |
| |
| GDB must be linked with the Expat library to support XML memory maps. |
| *Note Expat::. |
| |
| The top-level structure of the document is shown below: |
| |
| <?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> |
| |
| Each region can be either: |
| |
| * A region of RAM starting at ADDR and extending for LENGTH bytes |
| from there: |
| |
| <memory type="ram" start="ADDR" length="LENGTH"/> |
| |
| * A region of read-only memory: |
| |
| <memory type="rom" start="ADDR" length="LENGTH"/> |
| |
| * A region of flash memory, with erasure blocks BLOCKSIZE bytes in |
| length: |
| |
| <memory type="flash" start="ADDR" length="LENGTH"> |
| <property name="blocksize">BLOCKSIZE</property> |
| </memory> |
| |
| 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. |
| |
| The formal DTD for memory map format is given below: |
| |
| <!-- ................................................... --> |
| <!-- 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" name="name"> |
| ... description ... |
| </thread> |
| </threads> |
| |
| 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 'name' attribute, if present, specifies the human-readable name |
| of the thread. The content of the of 'thread' element is interpreted as |
| human-readable auxiliary information. |
| |
| |
| File: gdb.info, Node: Traceframe Info Format, Next: Branch Trace Format, Prev: Thread List Format, Up: Remote Protocol |
| |
| E.18 Traceframe Info Format |
| =========================== |
| |
| 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. |
| |
| This list is obtained using the 'qXfer:traceframe-info:read' (*note |
| qXfer traceframe info read::) packet and is an XML document. |
| |
| GDB must be linked with the Expat library to support XML traceframe |
| info discovery. *Note Expat::. |
| |
| The top-level structure of the document is shown below: |
| |
| <?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> |
| |
| Each traceframe block can be either: |
| |
| * A region of collected memory starting at ADDR and extending for |
| LENGTH bytes from there: |
| |
| <memory start="ADDR" length="LENGTH"/> |
| |
| * A block indicating trace state variable numbered NUMBER has been |
| collected: |
| |
| <tvar id="NUMBER"/> |
| |
| The formal DTD for the traceframe info format is given below: |
| |
| <!ELEMENT traceframe-info (memory | tvar)* > |
| <!ATTLIST traceframe-info version CDATA #FIXED "1.0"> |
| |
| <!ELEMENT memory EMPTY> |
| <!ATTLIST memory start CDATA #REQUIRED |
| length CDATA #REQUIRED> |
| <!ELEMENT tvar> |
| <!ATTLIST tvar id CDATA #REQUIRED> |
| |
| |
| File: gdb.info, Node: Branch Trace Format, Next: Branch Trace Configuration Format, Prev: Traceframe Info Format, Up: Remote Protocol |
| |
| E.19 Branch Trace Format |
| ======================== |
| |
| In order to display the branch trace of an inferior thread, GDB needs to |
| obtain the list of branches. This list is represented as list of |
| sequential code blocks that are connected via branches. The code in |
| each block has been executed sequentially. |
| |
| This list is obtained using the 'qXfer:btrace:read' (*note qXfer |
| btrace read::) packet and is an XML document. |
| |
| GDB must be linked with the Expat library to support XML traceframe |
| info discovery. *Note Expat::. |
| |
| The top-level structure of the document is shown below: |
| |
| <?xml version="1.0"?> |
| <!DOCTYPE btrace |
| PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN" |
| "http://sourceware.org/gdb/gdb-btrace.dtd"> |
| <btrace> |
| block... |
| </btrace> |
| |
| * A block of sequentially executed instructions starting at BEGIN and |
| ending at END: |
| |
| <block begin="BEGIN" end="END"/> |
| |
| The formal DTD for the branch trace format is given below: |
| |
| <!ELEMENT btrace (block* | pt) > |
| <!ATTLIST btrace version CDATA #FIXED "1.0"> |
| |
| <!ELEMENT block EMPTY> |
| <!ATTLIST block begin CDATA #REQUIRED |
| end CDATA #REQUIRED> |
| |
| <!ELEMENT pt (pt-config?, raw?)> |
| |
| <!ELEMENT pt-config (cpu?)> |
| |
| <!ELEMENT cpu EMPTY> |
| <!ATTLIST cpu vendor CDATA #REQUIRED |
| family CDATA #REQUIRED |
| model CDATA #REQUIRED |
| stepping CDATA #REQUIRED> |
| |
| <!ELEMENT raw (#PCDATA)> |
| |
| |
| File: gdb.info, Node: Branch Trace Configuration Format, Prev: Branch Trace Format, Up: Remote Protocol |
| |
| E.20 Branch Trace Configuration Format |
| ====================================== |
| |
| For each inferior thread, GDB can obtain the branch trace configuration |
| using the 'qXfer:btrace-conf:read' (*note qXfer btrace-conf read::) |
| packet. |
| |
| The configuration describes the branch trace format and configuration |
| settings for that format. The following information is described: |
| |
| 'bts' |
| This thread uses the "Branch Trace Store" (BTS) format. |
| 'size' |
| The size of the BTS ring buffer in bytes. |
| 'pt' |
| This thread uses the "Intel Processor Trace" (Intel PT) format. |
| 'size' |
| The size of the Intel PT ring buffer in bytes. |
| |
| GDB must be linked with the Expat library to support XML branch trace |
| configuration discovery. *Note Expat::. |
| |
| The formal DTD for the branch trace configuration format is given |
| below: |
| |
| <!ELEMENT btrace-conf (bts?, pt?)> |
| <!ATTLIST btrace-conf version CDATA #FIXED "1.0"> |
| |
| <!ELEMENT bts EMPTY> |
| <!ATTLIST bts size CDATA #IMPLIED> |
| |
| <!ELEMENT pt EMPTY> |
| <!ATTLIST pt size CDATA #IMPLIED> |
| |
| |
| File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top |
| |
| Appendix F The GDB Agent Expression Mechanism |
| ********************************************* |
| |
| 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. |
| |
| 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. |
| |
| * Menu: |
| |
| * 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 |
| |
| F.1 General Bytecode Design |
| =========================== |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions |
| |
| F.2 Bytecode Descriptions |
| ========================= |
| |
| Each bytecode description has the following form: |
| |
| 'add' (0x02): A B => A+B |
| |
| Pop the top two stack items, A and B, as integers; push their sum, |
| as an integer. |
| |
| 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 => 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. |
| |
| |
| File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions |
| |
| F.3 Using Agent Expressions |
| =========================== |
| |
| Agent expressions can be used in several different ways by GDB, and the |
| debugger can generate different bytecode sequences as appropriate. |
| |
| 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. |
| |
| * The user selects trace points in the program's code at which GDB |
| should collect data. |
| |
| * 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. |
| |
| * GDB transmits the tracepoints and their associated expressions to |
| the GDB agent, running on the debugging target. |
| |
| * The agent arranges to be notified when a trace point is hit. |
| |
| * 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. |
| |
| * 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. |
| |
| |
| File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions |
| |
| F.4 Varying Target Capabilities |
| =============================== |
| |
| 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. |
| |
| 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: |
| |
| * whether floating point is supported |
| |
| * whether 'long long' is supported |
| |
| * maximum acceptable size of bytecode stack |
| |
| * maximum acceptable length of bytecode expressions |
| |
| * which registers are actually available for collection |
| |
| * whether the target supports disabled tracepoints |
| |
| |
| File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions |
| |
| F.5 Rationale |
| ============= |
| |
| 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. |
| |
| |
| File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top |
| |
| Appendix G Target Descriptions |
| ****************************** |
| |
| 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: |
| |
| * With so many different customized processors, it is difficult for |
| the GDB maintainers to keep up with the changes. |
| * 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. |
| * 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. |
| |
| 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. |
| |
| GDB must be linked with the Expat library to support XML target |
| descriptions. *Note Expat::. |
| |
| * Menu: |
| |
| * 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 |
| |
| G.1 Retrieving Descriptions |
| =========================== |
| |
| 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::. |
| |
| 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: |
| |
| 'set tdesc filename PATH' |
| Read the target description from PATH. |
| |
| 'unset tdesc filename' |
| Do not read the XML target description from a file. GDB will use |
| the description supplied by the current target. |
| |
| 'show tdesc filename' |
| Show the filename to read for a target description, if any. |
| |
| |
| File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions |
| |
| G.2 Target Description Format |
| ============================= |
| |
| 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 |
| ------------------ |
| |
| An '<architecture>' element has this form: |
| |
| <architecture>ARCH</architecture> |
| |
| ARCH is one of the architectures from the set accepted by 'set |
| architecture' (*note Specifying a Debugging Target: Targets.). |
| |
| G.2.3 OS ABI |
| ------------ |
| |
| This optional field was introduced in GDB version 7.0. Previous |
| versions of GDB ignore it. |
| |
| An '<osabi>' element has this form: |
| |
| <osabi>ABI-NAME</osabi> |
| |
| ABI-NAME is an OS ABI name from the same selection accepted by |
| 'set osabi' (*note Configuring the Current ABI: ABI.). |
| |
| G.2.4 Compatible Architecture |
| ----------------------------- |
| |
| This optional field was introduced in GDB version 7.0. Previous |
| versions of GDB ignore it. |
| |
| A '<compatible>' element has this form: |
| |
| <compatible>ARCH</compatible> |
| |
| 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: |
| |
| <architecture>powerpc:common</architecture> |
| <compatible>spu</compatible> |
| |
| G.2.5 Features |
| -------------- |
| |
| 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: |
| |
| <feature name="NAME"> |
| [TYPE...] |
| REG... |
| </feature> |
| |
| 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::. |
| |
| G.2.6 Types |
| ----------- |
| |
| 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. It 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. It must be |
| either 'general', 'float', or 'vector'. If no GROUP is specified, |
| GDB will not display the register in 'info registers'. |
| |
| |
| File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions |
| |
| G.3 Predefined Target Types |
| =========================== |
| |
| 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: |
| |
| 'int8' |
| 'int16' |
| 'int32' |
| 'int64' |
| 'int128' |
| Signed integer types holding the specified number of bits. |
| |
| 'uint8' |
| 'uint16' |
| 'uint32' |
| 'uint64' |
| 'uint128' |
| Unsigned integer types holding the specified number of bits. |
| |
| '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. |
| |
| 'ieee_single' |
| Single precision IEEE floating point. |
| |
| 'ieee_double' |
| Double precision IEEE floating point. |
| |
| '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. |
| |
| 'i386_eflags' |
| 32bit EFLAGS register used by x86. |
| |
| 'i386_mxcsr' |
| 32bit MXCSR register used by x86. |
| |
| |
| 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. |
| |
| * Menu: |
| |
| * AArch64 Features:: |
| * ARM Features:: |
| * i386 Features:: |
| * MicroBlaze Features:: |
| * MIPS Features:: |
| * M68K Features:: |
| * Nios II Features:: |
| * PowerPC Features:: |
| * S/390 and System z Features:: |
| * TIC6x Features:: |
| |
| |
| File: gdb.info, Node: AArch64 Features, Next: ARM Features, Up: Standard Target Features |
| |
| G.4.1 AArch64 Features |
| ---------------------- |
| |
| The 'org.gnu.gdb.aarch64.core' feature is required for AArch64 targets. |
| It should contain registers 'x0' through 'x30', 'sp', 'pc', and 'cpsr'. |
| |
| The 'org.gnu.gdb.aarch64.fpu' feature is optional. If present, it |
| should contain registers 'v0' through 'v31', 'fpsr', and 'fpcr'. |
| |
| |
| File: gdb.info, Node: ARM Features, Next: i386 Features, Prev: AArch64 Features, Up: Standard Target Features |
| |
| G.4.2 ARM Features |
| ------------------ |
| |
| 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'. |
| |
| 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'. |
| |
| The 'org.gnu.gdb.arm.fpa' feature is optional. If present, it should |
| contain registers 'f0' through 'f7' and 'fps'. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: i386 Features, Next: MicroBlaze Features, Prev: ARM Features, Up: Standard Target Features |
| |
| G.4.3 i386 Features |
| ------------------- |
| |
| The 'org.gnu.gdb.i386.core' feature is required for i386/amd64 targets. |
| It should describe the following registers: |
| |
| - 'eax' through 'edi' plus 'eip' for i386 |
| - 'rax' through 'r15' plus 'rip' for amd64 |
| - 'eflags', 'cs', 'ss', 'ds', 'es', 'fs', 'gs' |
| - 'st0' through 'st7' |
| - 'fctrl', 'fstat', 'ftag', 'fiseg', 'fioff', 'foseg', 'fooff' and |
| 'fop' |
| |
| The register sets may be different, depending on the target. |
| |
| The 'org.gnu.gdb.i386.sse' feature is optional. It should describe |
| registers: |
| |
| - 'xmm0' through 'xmm7' for i386 |
| - 'xmm0' through 'xmm15' for amd64 |
| - 'mxcsr' |
| |
| 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: |
| |
| - 'ymm0h' through 'ymm7h' for i386 |
| - 'ymm0h' through 'ymm15h' for amd64 |
| |
| The 'org.gnu.gdb.i386.mpx' is an optional feature representing Intel |
| Memory Protection Extension (MPX). It should describe the following |
| registers: |
| |
| - 'bnd0raw' through 'bnd3raw' for i386 and amd64. |
| - 'bndcfgu' and 'bndstatus' for i386 and amd64. |
| |
| The 'org.gnu.gdb.i386.linux' feature is optional. It should describe |
| a single register, 'orig_eax'. |
| |
| The 'org.gnu.gdb.i386.avx512' feature is optional and requires the |
| 'org.gnu.gdb.i386.avx' feature. It should describe additional XMM |
| registers: |
| |
| - 'xmm16h' through 'xmm31h', only valid for amd64. |
| |
| It should describe the upper 128 bits of additional YMM registers: |
| |
| - 'ymm16h' through 'ymm31h', only valid for amd64. |
| |
| It should describe the upper 256 bits of ZMM registers: |
| |
| - 'zmm0h' through 'zmm7h' for i386. |
| - 'zmm0h' through 'zmm15h' for amd64. |
| |
| It should describe the additional ZMM registers: |
| |
| - 'zmm16h' through 'zmm31h', only valid for amd64. |
| |
| |
| File: gdb.info, Node: MicroBlaze Features, Next: MIPS Features, Prev: i386 Features, Up: Standard Target Features |
| |
| G.4.4 MicroBlaze Features |
| ------------------------- |
| |
| The 'org.gnu.gdb.microblaze.core' feature is required for MicroBlaze |
| targets. It should contain registers 'r0' through 'r31', 'rpc', 'rmsr', |
| 'rear', 'resr', 'rfsr', 'rbtr', 'rpvr', 'rpvr1' through 'rpvr11', |
| 'redr', 'rpid', 'rzpr', 'rtlbx', 'rtlbsx', 'rtlblo', and 'rtlbhi'. |
| |
| The 'org.gnu.gdb.microblaze.stack-protect' feature is optional. If |
| present, it should contain registers 'rshr' and 'rslr' |
| |
| |
| File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: MicroBlaze Features, Up: Standard Target Features |
| |
| G.4.5 MIPS Features |
| ------------------- |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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 '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. |
| |
| |
| File: gdb.info, Node: M68K Features, Next: Nios II Features, Prev: MIPS Features, Up: Standard Target Features |
| |
| G.4.6 M68K Features |
| ------------------- |
| |
| ''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'. |
| |
| ''org.gnu.gdb.coldfire.fp'' |
| This feature is optional. If present, it should contain registers |
| 'fp0' through 'fp7', 'fpcontrol', 'fpstatus' and 'fpiaddr'. |
| |
| |
| File: gdb.info, Node: Nios II Features, Next: PowerPC Features, Prev: M68K Features, Up: Standard Target Features |
| |
| G.4.7 Nios II Features |
| ---------------------- |
| |
| The 'org.gnu.gdb.nios2.cpu' feature is required for Nios II targets. It |
| should contain the 32 core registers ('zero', 'at', 'r2' through 'r23', |
| 'et' through 'ra'), 'pc', and the 16 control registers ('status' through |
| 'mpuacc'). |
| |
| |
| File: gdb.info, Node: PowerPC Features, Next: S/390 and System z Features, Prev: Nios II Features, Up: Standard Target Features |
| |
| G.4.8 PowerPC Features |
| ---------------------- |
| |
| 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. |
| |
| The 'org.gnu.gdb.power.fpu' feature is optional. It should contain |
| registers 'f0' through 'f31' and 'fpscr'. |
| |
| The 'org.gnu.gdb.power.altivec' feature is optional. It should |
| contain registers 'vr0' through 'vr31', 'vscr', and 'vrsave'. |
| |
| 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. |
| |
| 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. |
| |
| |
| File: gdb.info, Node: S/390 and System z Features, Next: TIC6x Features, Prev: PowerPC Features, Up: Standard Target Features |
| |
| G.4.9 S/390 and System z Features |
| --------------------------------- |
| |
| The 'org.gnu.gdb.s390.core' feature is required for S/390 and System z |
| targets. It should contain the PSW and the 16 general registers. In |
| particular, System z targets should provide the 64-bit registers 'pswm', |
| 'pswa', and 'r0' through 'r15'. S/390 targets should provide the 32-bit |
| versions of these registers. A System z target that runs in 31-bit |
| addressing mode should provide 32-bit versions of 'pswm' and 'pswa', as |
| well as the general register's upper halves 'r0h' through 'r15h', and |
| their lower halves 'r0l' through 'r15l'. |
| |
| The 'org.gnu.gdb.s390.fpr' feature is required. It should contain |
| the 64-bit registers 'f0' through 'f15', and 'fpc'. |
| |
| The 'org.gnu.gdb.s390.acr' feature is required. It should contain |
| the 32-bit registers 'acr0' through 'acr15'. |
| |
| The 'org.gnu.gdb.s390.linux' feature is optional. It should contain |
| the register 'orig_r2', which is 64-bit wide on System z targets and |
| 32-bit otherwise. In addition, the feature may contain the 'last_break' |
| register, whose width depends on the addressing mode, as well as the |
| 'system_call' register, which is always 32-bit wide. |
| |
| The 'org.gnu.gdb.s390.tdb' feature is optional. It should contain |
| the 64-bit registers 'tdb0', 'tac', 'tct', 'atia', and 'tr0' through |
| 'tr15'. |
| |
| The 'org.gnu.gdb.s390.vx' feature is optional. It should contain |
| 64-bit wide registers 'v0l' through 'v15l', which will be combined by |
| GDB with the floating point registers 'f0' through 'f15' to present the |
| 128-bit wide vector registers 'v0' through 'v15'. In addition, this |
| feature should contain the 128-bit wide vector registers 'v16' through |
| 'v31'. |
| |
| |
| File: gdb.info, Node: TIC6x Features, Prev: S/390 and System z Features, Up: Standard Target Features |
| |
| G.4.10 TMS320C6x Features |
| ------------------------- |
| |
| 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'. |
| |
| The 'org.gnu.gdb.tic6x.gp' feature is optional. It should contain |
| registers 'A16' through 'A31' and 'B16' through 'B31'. |
| |
| The 'org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain |
| registers 'TSR', 'ILC' and 'RILC'. |
| |
| |
| File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top |
| |
| Appendix H Operating System Information |
| *************************************** |
| |
| * Menu: |
| |
| * Process list:: |
| |
| 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. |
| |
| 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. |
| |
| |
| 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: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top |
| |
| Appendix I Trace File Format |
| **************************** |
| |
| The trace file comes in three parts: a header, a textual description |
| section, and a trace frame section with binary data. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| '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. |
| |
| '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. |
| |
| 'V NUMBER VALUE' |
| Trace state variable block. This records the 8-byte signed value |
| VALUE of trace state variable numbered NUMBER. |
| |
| Future enhancements of the trace file format may include additional |
| types of blocks. |
| |
| |
| File: gdb.info, Node: Index Section Format, Next: Man Pages, 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. |
| |
| 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. |
| |
| A mapped index consists of several areas, laid out in order. |
| |
| 1. The file header. This is a sequence of values, of 'offset_type' |
| unless otherwise noted: |
| |
| 1. The version number, currently 8. 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. Version 8 |
| specifies that symbols from DWARF type units |
| ('DW_TAG_type_unit') refer to the type unit's symbol table and |
| not the compilation unit ('DW_TAG_comp_unit') using the type. |
| |
| GDB will only read version 4, 5, or 6 indices by specifying |
| 'set use-deprecated-index-sections on'. GDB has a workaround |
| for potentially broken version 7 indices so it is currently |
| not flagged as deprecated. |
| |
| 2. The offset, from the start of the file, of the CU list. |
| |
| 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. |
| |
| 4. The offset, from the start of the file, of the address area. |
| |
| 5. The offset, from the start of the file, of the symbol table. |
| |
| 6. The offset, from the start of the file, of the constant pool. |
| |
| 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. |
| |
| 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. |
| |
| 4. The address area. The address area consists of a sequence of |
| address entries. Each address entry has three elements: |
| |
| 1. The low address. This is a 64-bit little-endian value. |
| |
| 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. |
| |
| 3. The CU index. This is an 'offset_type' value. |
| |
| 5. The symbol table. This is an open-addressed hash table. The size |
| of the hash table is always a power of 2. |
| |
| 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. |
| |
| 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. |
| |
| 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); |
| } |
| |