1 This is gdb.info, produced by makeinfo version 5.2 from gdb.texinfo.
3 Copyright (C) 1988-2015 Free Software Foundation, Inc.
5 Permission is granted to copy, distribute and/or modify this document
6 under the terms of the GNU Free Documentation License, Version 1.3 or
7 any later version published by the Free Software Foundation; with the
8 Invariant Sections being "Free Software" and "Free Software Needs Free
9 Documentation", with the Front-Cover Texts being "A GNU Manual," and
10 with the Back-Cover Texts as in (a) below.
12 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
13 this GNU Manual. Buying copies from GNU Press supports the FSF in
14 developing GNU and promoting software freedom."
15 INFO-DIR-SECTION Software development
17 * Gdb: (gdb). The GNU debugger.
18 * gdbserver: (gdb) Server. The GNU debugging server.
21 This file documents the GNU debugger GDB.
23 This is the Tenth Edition, of 'Debugging with GDB: the GNU
24 Source-Level Debugger' for GDB (GDB) Version 7.9.
26 Copyright (C) 1988-2015 Free Software Foundation, Inc.
28 Permission is granted to copy, distribute and/or modify this document
29 under the terms of the GNU Free Documentation License, Version 1.3 or
30 any later version published by the Free Software Foundation; with the
31 Invariant Sections being "Free Software" and "Free Software Needs Free
32 Documentation", with the Front-Cover Texts being "A GNU Manual," and
33 with the Back-Cover Texts as in (a) below.
35 (a) The FSF's Back-Cover Text is: "You are free to copy and modify
36 this GNU Manual. Buying copies from GNU Press supports the FSF in
37 developing GNU and promoting software freedom."
40 File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top
42 Appendix E GDB Remote Serial Protocol
43 *************************************
49 * Stop Reply Packets::
50 * General Query Packets::
51 * Architecture-Specific Protocol Details::
52 * Tracepoint Packets::
55 * Notification Packets::
57 * Packet Acknowledgment::
59 * File-I/O Remote Protocol Extension::
60 * Library List Format::
61 * Library List Format for SVR4 Targets::
63 * Thread List Format::
64 * Traceframe Info Format::
65 * Branch Trace Format::
68 File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol
73 There may be occasions when you need to know something about the
74 protocol--for example, if there is only one serial port to your target
75 machine, you might want your program to do something special if it
76 recognizes a packet meant for GDB.
78 In the examples below, '->' and '<-' are used to indicate transmitted
79 and received data, respectively.
81 All GDB commands and responses (other than acknowledgments and
82 notifications, see *note Notification Packets::) are sent as a PACKET.
83 A PACKET is introduced with the character '$', the actual PACKET-DATA,
84 and the terminating character '#' followed by a two-digit CHECKSUM:
88 The two-digit CHECKSUM is computed as the modulo 256 sum of all
89 characters between the leading '$' and the trailing '#' (an eight bit
92 Implementors should note that prior to GDB 5.0 the protocol
93 specification also included an optional two-digit SEQUENCE-ID:
95 $SEQUENCE-ID:PACKET-DATA#CHECKSUM
97 That SEQUENCE-ID was appended to the acknowledgment. GDB has never
98 output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 must
99 not accept SEQUENCE-ID.
101 When either the host or the target machine receives a packet, the
102 first response expected is an acknowledgment: either '+' (to indicate
103 the package was received correctly) or '-' (to request retransmission):
105 -> $PACKET-DATA#CHECKSUM
108 The '+'/'-' acknowledgments can be disabled once a connection is
109 established. *Note Packet Acknowledgment::, for details.
111 The host (GDB) sends COMMANDs, and the target (the debugging stub
112 incorporated in your program) sends a RESPONSE. In the case of step and
113 continue COMMANDs, the response is only sent when the operation has
114 completed, and the target has again stopped all threads in all attached
115 processes. This is the default all-stop mode behavior, but the remote
116 protocol also supports GDB's non-stop execution mode; see *note Remote
117 Non-Stop::, for details.
119 PACKET-DATA consists of a sequence of characters with the exception
120 of '#' and '$' (see 'X' packet for additional exceptions).
122 Fields within the packet should be separated using ',' ';' or ':'.
123 Except where otherwise noted all numbers are represented in HEX with
124 leading zeros suppressed.
126 Implementors should note that prior to GDB 5.0, the character ':'
127 could not appear as the third character in a packet (as it would
128 potentially conflict with the SEQUENCE-ID).
130 Binary data in most packets is encoded either as two hexadecimal
131 digits per byte of binary data. This allowed the traditional remote
132 protocol to work over connections which were only seven-bit clean. Some
133 packets designed more recently assume an eight-bit clean connection, and
134 use a more efficient encoding to send and receive binary data.
136 The binary data representation uses '7d' (ASCII '}') as an escape
137 character. Any escaped byte is transmitted as the escape character
138 followed by the original character XORed with '0x20'. For example, the
139 byte '0x7d' would be transmitted as the two bytes '0x7d 0x5d'. The
140 bytes '0x23' (ASCII '#'), '0x24' (ASCII '$'), and '0x7d' (ASCII '}')
141 must always be escaped. Responses sent by the stub must also escape
142 '0x2a' (ASCII '*'), so that it is not interpreted as the start of a
143 run-length encoded sequence (described next).
145 Response DATA can be run-length encoded to save space. Run-length
146 encoding replaces runs of identical characters with one instance of the
147 repeated character, followed by a '*' and a repeat count. The repeat
148 count is itself sent encoded, to avoid binary characters in DATA: a
149 value of N is sent as 'N+29'. For a repeat count greater or equal to 3,
150 this produces a printable ASCII character, e.g. a space (ASCII code 32)
151 for a repeat count of 3. (This is because run-length encoding starts to
152 win for counts 3 or more.) Thus, for example, '0* ' is a run-length
153 encoding of "0000": the space character after '*' means repeat the
154 leading '0' '32 - 29 = 3' more times.
156 The printable characters '#' and '$' or with a numeric value greater
157 than 126 must not be used. Runs of six repeats ('#') or seven repeats
158 ('$') can be expanded using a repeat count of only five ('"'). For
159 example, '00000000' can be encoded as '0*"00'.
161 The error response returned for some packets includes a two character
162 error number. That number is not well defined.
164 For any COMMAND not supported by the stub, an empty response ('$#00')
165 should be returned. That way it is possible to extend the protocol. A
166 newer GDB can tell if a packet is supported based on that response.
168 At a minimum, a stub is required to support the 'g' and 'G' commands
169 for register access, and the 'm' and 'M' commands for memory access.
170 Stubs that only control single-threaded targets can implement run
171 control with the 'c' (continue), and 's' (step) commands. Stubs that
172 support multi-threading targets should support the 'vCont' command. All
173 other commands are optional.
176 File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol
181 The following table provides a complete list of all currently defined
182 COMMANDs and their corresponding response DATA. *Note File-I/O Remote
183 Protocol Extension::, for details about the File I/O extension of the
186 Each packet's description has a template showing the packet's overall
187 syntax, followed by an explanation of the packet's meaning. We include
188 spaces in some of the templates for clarity; these are not part of the
189 packet's syntax. No GDB packet uses spaces to separate its components.
190 For example, a template like 'foo BAR BAZ' describes a packet beginning
191 with the three ASCII bytes 'foo', followed by a BAR, followed directly
192 by a BAZ. GDB does not transmit a space character between the 'foo' and
193 the BAR, or between the BAR and the BAZ.
195 Several packets and replies include a THREAD-ID field to identify a
196 thread. Normally these are positive numbers with a target-specific
197 interpretation, formatted as big-endian hex strings. A THREAD-ID can
198 also be a literal '-1' to indicate all threads, or '0' to pick any
201 In addition, the remote protocol supports a multiprocess feature in
202 which the THREAD-ID syntax is extended to optionally include both
203 process and thread ID fields, as 'pPID.TID'. The PID (process) and TID
204 (thread) components each have the format described above: a positive
205 number with target-specific interpretation formatted as a big-endian hex
206 string, literal '-1' to indicate all processes or threads
207 (respectively), or '0' to indicate an arbitrary process or thread.
208 Specifying just a process, as 'pPID', is equivalent to 'pPID.-1'. It is
209 an error to specify all processes but a specific thread, such as
210 'p-1.TID'. Note that the 'p' prefix is _not_ used for those packets and
211 replies explicitly documented to include a process ID, rather than a
214 The multiprocess THREAD-ID syntax extensions are only used if both
215 GDB and the stub report support for the 'multiprocess' feature using
216 'qSupported'. *Note multiprocess extensions::, for more information.
218 Note that all packet forms beginning with an upper- or lower-case
219 letter, other than those described here, are reserved for future use.
221 Here are the packet descriptions.
224 Enable extended mode. In extended mode, the remote server is made
225 persistent. The 'R' packet is used to restart the program being
230 The remote target both supports and has enabled extended mode.
233 Indicate the reason the target halted. The reply is the same as
234 for step and continue. This packet has a special interpretation
235 when the target is in non-stop mode; see *note Remote Non-Stop::.
237 Reply: *Note Stop Reply Packets::, for the reply specifications.
239 'A ARGLEN,ARGNUM,ARG,...'
240 Initialized 'argv[]' array passed into program. ARGLEN specifies
241 the number of bytes in the hex encoded byte stream ARG. See
242 'gdbserver' for more details.
246 The arguments were set.
251 (Don't use this packet; its behavior is not well-defined.) Change
252 the serial line speed to BAUD.
254 JTC: _When does the transport layer state change? When it's
255 received, or after the ACK is transmitted. In either case, there
256 are problems if the command or the acknowledgment packet is
259 Stan: _If people really wanted to add something like this, and get
260 it working for the first time, they ought to modify ser-unix.c to
261 send some kind of out-of-band message to a specially-setup stub and
262 have the switch happen "in between" packets, so that from remote
263 protocol's point of view, nothing actually happened._
266 Set (MODE is 'S') or clear (MODE is 'C') a breakpoint at ADDR.
268 Don't use this packet. Use the 'Z' and 'z' packets instead (*note
269 insert breakpoint or watchpoint packet::).
272 Backward continue. Execute the target system in reverse. No
273 parameter. *Note Reverse Execution::, for more information.
275 Reply: *Note Stop Reply Packets::, for the reply specifications.
278 Backward single step. Execute one instruction in reverse. No
279 parameter. *Note Reverse Execution::, for more information.
281 Reply: *Note Stop Reply Packets::, for the reply specifications.
284 Continue at ADDR, which is the address to resume. If ADDR is
285 omitted, resume at current address.
287 This packet is deprecated for multi-threading support. *Note vCont
290 Reply: *Note Stop Reply Packets::, for the reply specifications.
293 Continue with signal SIG (hex signal number). If ';ADDR' is
294 omitted, resume at same address.
296 This packet is deprecated for multi-threading support. *Note vCont
299 Reply: *Note Stop Reply Packets::, for the reply specifications.
304 Don't use this packet; instead, define a general set packet (*note
305 General Query Packets::).
309 The first form of the packet is used to detach GDB from the remote
310 system. It is sent to the remote target before GDB disconnects via
311 the 'detach' command.
313 The second form, including a process ID, is used when multiprocess
314 protocol extensions are enabled (*note multiprocess extensions::),
315 to detach only a specific process. The PID is specified as a
316 big-endian hex string.
325 A reply from GDB to an 'F' packet sent by the target. This is part
326 of the File-I/O protocol extension. *Note File-I/O Remote Protocol
327 Extension::, for the specification.
330 Read general registers.
334 Each byte of register data is described by two hex digits.
335 The bytes with the register are transmitted in target byte
336 order. The size of each register and their position within
337 the 'g' packet are determined by the GDB internal gdbarch
338 functions 'DEPRECATED_REGISTER_RAW_SIZE' and
339 'gdbarch_register_name'. The specification of several
340 standard 'g' packets is specified below.
342 When reading registers from a trace frame (*note Using the
343 Collected Data: Analyze Collected Data.), the stub may also
344 return a string of literal 'x''s in place of the register data
345 digits, to indicate that the corresponding register has not
346 been collected, thus its value is unavailable. For example,
347 for an architecture with 4 registers of 4 bytes each, the
348 following reply indicates to GDB that registers 0 and 2 have
349 not been collected, while registers 1 and 3 have been
350 collected, and both have zero value:
353 <- xxxxxxxx00000000xxxxxxxx00000000
359 Write general registers. *Note read registers packet::, for a
360 description of the XX... data.
369 Set thread for subsequent operations ('m', 'M', 'g', 'G', et.al.).
370 Depending on the operation to be performed, OP should be 'c' for
371 step and continue operations (note that this is deprecated,
372 supporting the 'vCont' command is a better option), and 'g' for
373 other operations. The thread designator THREAD-ID has the format
374 and interpretation described in *note thread-id syntax::.
383 Step the remote target by a single clock cycle. If ',NNN' is
384 present, cycle step NNN cycles. If ADDR is present, cycle step
385 starting at that address.
388 Signal, then cycle step. *Note step with signal packet::. *Note
394 The exact effect of this packet is not specified.
396 For a bare-metal target, it may power cycle or reset the target
397 system. For that reason, the 'k' packet has no reply.
399 For a single-process target, it may kill that process if possible.
401 A multiple-process target may choose to kill just one process, or
402 all that are under GDB's control. For more precise control, use
403 the vKill packet (*note vKill packet::).
405 If the target system immediately closes the connection in response
406 to 'k', GDB does not consider the lack of packet acknowledgment to
407 be an error, and assumes the kill was successful.
409 If connected using 'target extended-remote', and the target does
410 not close the connection in response to a kill request, GDB probes
411 the target state as if a new connection was opened (*note ?
415 Read LENGTH bytes of memory starting at address ADDR. Note that
416 ADDR may not be aligned to any particular boundary.
418 The stub need not use any particular size or alignment when
419 gathering data from memory for the response; even if ADDR is
420 word-aligned and LENGTH is a multiple of the word size, the stub is
421 free to use byte accesses, or not. For this reason, this packet
422 may not be suitable for accessing memory-mapped I/O devices.
426 Memory contents; each byte is transmitted as a two-digit
427 hexadecimal number. The reply may contain fewer bytes than
428 requested if the server was able to read only part of the
433 'M ADDR,LENGTH:XX...'
434 Write LENGTH bytes of memory starting at address ADDR. The data is
435 given by XX...; each byte is transmitted as a two-digit hexadecimal
442 for an error (this includes the case where only part of the
446 Read the value of register N; N is in hex. *Note read registers
447 packet::, for a description of how the returned register value is
456 Indicating an unrecognized QUERY.
459 Write register N... with value R.... The register number N is in
460 hexadecimal, and R... contains two hex digits for each byte in the
461 register (target byte order).
471 General query ('q') and set ('Q'). These packets are described
472 fully in *note General Query Packets::.
475 Reset the entire system.
477 Don't use this packet; use the 'R' packet instead.
480 Restart the program being debugged. The XX, while needed, is
481 ignored. This packet is only available in extended mode (*note
484 The 'R' packet has no reply.
487 Single step, resuming at ADDR. If ADDR is omitted, resume at same
490 This packet is deprecated for multi-threading support. *Note vCont
493 Reply: *Note Stop Reply Packets::, for the reply specifications.
496 Step with signal. This is analogous to the 'C' packet, but
497 requests a single-step, rather than a normal resumption of
500 This packet is deprecated for multi-threading support. *Note vCont
503 Reply: *Note Stop Reply Packets::, for the reply specifications.
506 Search backwards starting at address ADDR for a match with pattern
507 PP and mask MM, both of which are are 4 byte long. There must be
508 at least 3 digits in ADDR.
511 Find out if the thread THREAD-ID is alive. *Note thread-id
516 thread is still alive
521 Packets starting with 'v' are identified by a multi-letter name, up
522 to the first ';' or '?' (or the end of the packet).
525 Attach to a new process with the specified process ID PID. The
526 process ID is a hexadecimal integer identifying the process. In
527 all-stop mode, all threads in the attached process are stopped; in
528 non-stop mode, it may be attached without being stopped if that is
529 supported by the target.
531 This packet is only available in extended mode (*note extended
538 for success in all-stop mode (*note Stop Reply Packets::)
540 for success in non-stop mode (*note Remote Non-Stop::)
542 'vCont[;ACTION[:THREAD-ID]]...'
543 Resume the inferior, specifying different actions for each thread.
544 If an action is specified with no THREAD-ID, then it is applied to
545 any threads that don't have a specific action specified; if no
546 default action is specified then other threads should remain
547 stopped in all-stop mode and in their current state in non-stop
548 mode. Specifying multiple default actions is an error; specifying
549 no actions is also an error. Thread IDs are specified using the
550 syntax described in *note thread-id syntax::.
552 Currently supported actions are:
557 Continue with signal SIG. The signal SIG should be two hex
562 Step with signal SIG. The signal SIG should be two hex
567 Step once, and then keep stepping as long as the thread stops
568 at addresses between START (inclusive) and END (exclusive).
569 The remote stub reports a stop reply when either the thread
570 goes out of the range or is stopped due to an unrelated
571 reason, such as hitting a breakpoint. *Note range stepping::.
573 If the range is empty (START == END), then the action becomes
574 equivalent to the 's' action. In other words, single-step
575 once, and report the stop (even if the stepped instruction
578 (A stop reply may be sent at any point even if the PC is still
579 within the stepping range; for example, it is valid to
580 implement this packet in a degenerate way as a single
581 instruction step operation.)
583 The optional argument ADDR normally associated with the 'c', 'C',
584 's', and 'S' packets is not supported in 'vCont'.
586 The 't' action is only relevant in non-stop mode (*note Remote
587 Non-Stop::) and may be ignored by the stub otherwise. A stop reply
588 should be generated for any affected thread not already stopped.
589 When a thread is stopped by means of a 't' action, the
590 corresponding stop reply should indicate that the thread has
591 stopped with signal '0', regardless of whether the target uses some
592 other signal as an implementation detail.
594 The stub must support 'vCont' if it reports support for
595 multiprocess extensions (*note multiprocess extensions::). Note
596 that in this case 'vCont' actions can be specified to apply to all
597 threads in a process by using the 'pPID.-1' form of the THREAD-ID.
599 Reply: *Note Stop Reply Packets::, for the reply specifications.
602 Request a list of actions supported by the 'vCont' packet.
606 The 'vCont' packet is supported. Each ACTION is a supported
607 command in the 'vCont' packet.
609 The 'vCont' packet is not supported.
611 'vFile:OPERATION:PARAMETER...'
612 Perform a file operation on the target system. For details, see
613 *note Host I/O Packets::.
615 'vFlashErase:ADDR,LENGTH'
616 Direct the stub to erase LENGTH bytes of flash starting at ADDR.
617 The region may enclose any number of flash blocks, but its start
618 and end must fall on block boundaries, as indicated by the flash
619 block size appearing in the memory map (*note Memory Map Format::).
620 GDB groups flash memory programming operations together, and sends
621 a 'vFlashDone' request after each group; the stub is allowed to
622 delay erase operation until the 'vFlashDone' packet is received.
630 'vFlashWrite:ADDR:XX...'
631 Direct the stub to write data to flash address ADDR. The data is
632 passed in binary form using the same encoding as for the 'X' packet
633 (*note Binary Data::). The memory ranges specified by
634 'vFlashWrite' packets preceding a 'vFlashDone' packet must not
635 overlap, and must appear in order of increasing addresses (although
636 'vFlashErase' packets for higher addresses may already have been
637 received; the ordering is guaranteed only between 'vFlashWrite'
638 packets). If a packet writes to an address that was neither erased
639 by a preceding 'vFlashErase' packet nor by some other
640 target-specific method, the results are unpredictable.
646 for vFlashWrite addressing non-flash memory
651 Indicate to the stub that flash programming operation is finished.
652 The stub is permitted to delay or batch the effects of a group of
653 'vFlashErase' and 'vFlashWrite' packets until a 'vFlashDone' packet
654 is received. The contents of the affected regions of flash memory
655 are unpredictable until the 'vFlashDone' request is completed.
658 Kill the process with the specified process ID PID, which is a
659 hexadecimal integer identifying the process. This packet is used
660 in preference to 'k' when multiprocess protocol extensions are
661 supported; see *note multiprocess extensions::.
669 'vRun;FILENAME[;ARGUMENT]...'
670 Run the program FILENAME, passing it each ARGUMENT on its command
671 line. The file and arguments are hex-encoded strings. If FILENAME
672 is an empty string, the stub may use a default program (e.g. the
673 last program run). The program is created in the stopped state.
675 This packet is only available in extended mode (*note extended
682 for success (*note Stop Reply Packets::)
685 *Note Notification Packets::.
687 'X ADDR,LENGTH:XX...'
688 Write data to memory, where the data is transmitted in binary.
689 Memory is specified by its address ADDR and number of bytes LENGTH;
690 'XX...' is binary data (*note Binary Data::).
700 Insert ('Z') or remove ('z') a TYPE breakpoint or watchpoint
701 starting at address ADDRESS of kind KIND.
703 Each breakpoint and watchpoint packet TYPE is documented
706 _Implementation notes: A remote target shall return an empty string
707 for an unrecognized breakpoint or watchpoint packet TYPE. A remote
708 target shall support either both or neither of a given 'ZTYPE...'
709 and 'zTYPE...' packet pair. To avoid potential problems with
710 duplicate packets, the operations should be implemented in an
714 'Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]'
715 Insert ('Z0') or remove ('z0') a memory breakpoint at address ADDR
718 A memory breakpoint is implemented by replacing the instruction at
719 ADDR with a software breakpoint or trap instruction. The KIND is
720 target-specific and typically indicates the size of the breakpoint
721 in bytes that should be inserted. E.g., the ARM and MIPS can
722 insert either a 2 or 4 byte breakpoint. Some architectures have
723 additional meanings for KIND; COND_LIST is an optional list of
724 conditional expressions in bytecode form that should be evaluated
725 on the target's side. These are the conditions that should be
726 taken into consideration when deciding if the breakpoint trigger
727 should be reported back to GDBN.
729 The COND_LIST parameter is comprised of a series of expressions,
730 concatenated without separators. Each expression has the following
734 LEN is the length of the bytecode expression and EXPR is the
735 actual conditional expression in bytecode form.
737 The optional CMD_LIST parameter introduces commands that may be run
738 on the target, rather than being reported back to GDB. The
739 parameter starts with a numeric flag PERSIST; if the flag is
740 nonzero, then the breakpoint may remain active and the commands
741 continue to be run even when GDB disconnects from the target.
742 Following this flag is a series of expressions concatenated with no
743 separators. Each expression has the following form:
746 LEN is the length of the bytecode expression and EXPR is the
747 actual conditional expression in bytecode form.
749 see *note Architecture-Specific Protocol Details::.
751 _Implementation note: It is possible for a target to copy or move
752 code that contains memory breakpoints (e.g., when implementing
753 overlays). The behavior of this packet, in the presence of such a
754 target, is not defined._
765 'Z1,ADDR,KIND[;COND_LIST...]'
766 Insert ('Z1') or remove ('z1') a hardware breakpoint at address
769 A hardware breakpoint is implemented using a mechanism that is not
770 dependant on being able to modify the target's memory. The KIND
771 and COND_LIST have the same meaning as in 'Z0' packets.
773 _Implementation note: A hardware breakpoint is not affected by code
786 Insert ('Z2') or remove ('z2') a write watchpoint at ADDR. The
787 number of bytes to watch is specified by KIND.
799 Insert ('Z3') or remove ('z3') a read watchpoint at ADDR. The
800 number of bytes to watch is specified by KIND.
812 Insert ('Z4') or remove ('z4') an access watchpoint at ADDR. The
813 number of bytes to watch is specified by KIND.
824 File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol
826 E.3 Stop Reply Packets
827 ======================
829 The 'C', 'c', 'S', 's', 'vCont', 'vAttach', 'vRun', 'vStopped', and '?'
830 packets can receive any of the below as a reply. Except for '?' and
831 'vStopped', that reply is only returned when the target halts. In the
832 below the exact meaning of "signal number" is defined by the header
833 'include/gdb/signals.h' in the GDB source code.
835 As in the description of request packets, we include spaces in the
836 reply templates for clarity; these are not part of the reply packet's
837 syntax. No GDB stop reply packet uses spaces to separate its
841 The program received signal number AA (a two-digit hexadecimal
842 number). This is equivalent to a 'T' response with no N:R pairs.
844 'T AA N1:R1;N2:R2;...'
845 The program received signal number AA (a two-digit hexadecimal
846 number). This is equivalent to an 'S' response, except that the
847 'N:R' pairs can carry values of important registers and other
848 information directly in the stop reply packet, reducing round-trip
849 latency. Single-step and breakpoint traps are reported this way.
850 Each 'N:R' pair is interpreted as follows:
852 * If N is a hexadecimal number, it is a register number, and the
853 corresponding R gives that register's value. The data R is a
854 series of bytes in target byte order, with each byte given by
855 a two-digit hex number.
857 * If N is 'thread', then R is the THREAD-ID of the stopped
858 thread, as specified in *note thread-id syntax::.
860 * If N is 'core', then R is the hexadecimal number of the core
861 on which the stop event was detected.
863 * If N is a recognized "stop reason", it describes a more
864 specific event that stopped the target. The currently defined
865 stop reasons are listed below. The AA should be '05', the
866 trap signal. At most one stop reason should be present.
868 * Otherwise, GDB should ignore this 'N:R' pair and go on to the
869 next; this allows us to extend the protocol in the future.
871 The currently defined stop reasons are:
876 The packet indicates a watchpoint hit, and R is the data
880 The packet indicates that the loaded libraries have changed.
881 GDB should use 'qXfer:libraries:read' to fetch a new list of
882 loaded libraries. The R part is ignored.
885 The packet indicates that the target cannot continue replaying
886 logged execution events, because it has reached the end (or
887 the beginning when executing backward) of the log. The value
888 of R will be either 'begin' or 'end'. *Note Reverse
889 Execution::, for more information.
893 The process exited, and AA is the exit status. This is only
894 applicable to certain targets.
896 The second form of the response, including the process ID of the
897 exited process, can be used only when GDB has reported support for
898 multiprocess protocol extensions; see *note multiprocess
899 extensions::. The PID is formatted as a big-endian hex string.
903 The process terminated with signal AA.
905 The second form of the response, including the process ID of the
906 terminated process, can be used only when GDB has reported support
907 for multiprocess protocol extensions; see *note multiprocess
908 extensions::. The PID is formatted as a big-endian hex string.
911 'XX...' is hex encoding of ASCII data, to be written as the
912 program's console output. This can happen at any time while the
913 program is running and the debugger should continue to wait for
914 'W', 'T', etc. This reply is not permitted in non-stop mode.
916 'F CALL-ID,PARAMETER...'
917 CALL-ID is the identifier which says which host system call should
918 be called. This is just the name of the function. Translation
919 into the correct system call is only applicable as it's defined in
920 GDB. *Note File-I/O Remote Protocol Extension::, for a list of
921 implemented system calls.
923 'PARAMETER...' is a list of parameters as defined for this very
926 The target replies with this packet when it expects GDB to call a
927 host system call on behalf of the target. GDB replies with an
928 appropriate 'F' packet and keeps up waiting for the next reply
929 packet from the target. The latest 'C', 'c', 'S' or 's' action is
930 expected to be continued. *Note File-I/O Remote Protocol
931 Extension::, for more details.
934 File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol
936 E.4 General Query Packets
937 =========================
939 Packets starting with 'q' are "general query packets"; packets starting
940 with 'Q' are "general set packets". General query and set packets are a
941 semi-unified form for retrieving and sending information to and from the
944 The initial letter of a query or set packet is followed by a name
945 indicating what sort of thing the packet applies to. For example, GDB
946 may use a 'qSymbol' packet to exchange symbol definitions with the stub.
947 These packet names follow some conventions:
949 * The name must not contain commas, colons or semicolons.
950 * Most GDB query and set packets have a leading upper case letter.
951 * The names of custom vendor packets should use a company prefix, in
952 lower case, followed by a period. For example, packets designed at
953 the Acme Corporation might begin with 'qacme.foo' (for querying
954 foos) or 'Qacme.bar' (for setting bars).
956 The name of a query or set packet should be separated from any
957 parameters by a ':'; the parameters themselves should be separated by
958 ',' or ';'. Stubs must be careful to match the full packet name, and
959 check for a separator or the end of the packet, in case two packet names
960 share a common prefix. New packets should not begin with 'qC', 'qP', or
963 Like the descriptions of the other packets, each description here has
964 a template showing the packet's overall syntax, followed by an
965 explanation of the packet's meaning. We include spaces in some of the
966 templates for clarity; these are not part of the packet's syntax. No
967 GDB packet uses spaces to separate its components.
969 Here are the currently defined query and set packets:
973 Turn on or off the agent as a helper to perform some debugging
974 operations delegated from GDB (*note Control Agent::).
977 Specify which operations GDB expects to request of the target, as a
978 semicolon-separated list of operation name and value pairs.
979 Possible values for OP include 'WriteReg', 'WriteMem',
980 'InsertBreak', 'InsertTrace', 'InsertFastTrace', and 'Stop'. VAL
981 is either 0, indicating that GDB will not request the operation, or
982 1, indicating that it may. (The target can then use this to set up
983 its own internals optimally, for instance if the debugger never
984 expects to insert breakpoints, it may not need to install its own
988 Return the current thread ID.
992 Where THREAD-ID is a thread ID as documented in *note
995 Any other reply implies the old thread ID.
998 Compute the CRC checksum of a block of memory using CRC-32 defined
999 in IEEE 802.3. The CRC is computed byte at a time, taking the most
1000 significant bit of each byte first. The initial pattern code
1001 '0xffffffff' is used to ensure leading zeros affect the CRC.
1003 _Note:_ This is the same CRC used in validating separate debug
1004 files (*note Debugging Information in Separate Files: Separate
1005 Debug Files.). However the algorithm is slightly different. When
1006 validating separate debug files, the CRC is computed taking the
1007 _least_ significant bit of each byte first, and the final result is
1008 inverted to detect trailing zeros.
1012 An error (such as memory fault)
1014 The specified memory region's checksum is CRC32.
1016 'QDisableRandomization:VALUE'
1017 Some target operating systems will randomize the virtual address
1018 space of the inferior process as a security feature, but provide a
1019 feature to disable such randomization, e.g. to allow for a more
1020 deterministic debugging experience. On such systems, this packet
1021 with a VALUE of 1 directs the target to disable address space
1022 randomization for processes subsequently started via 'vRun'
1023 packets, while a packet with a VALUE of 0 tells the target to
1024 enable address space randomization.
1026 This packet is only available in extended mode (*note extended
1031 The request succeeded.
1034 An error occurred. The error number NN is given as hex
1038 An empty reply indicates that 'QDisableRandomization' is not
1039 supported by the stub.
1041 This packet is not probed by default; the remote stub must request
1042 it, by supplying an appropriate 'qSupported' response (*note
1043 qSupported::). This should only be done on targets that actually
1044 support disabling address space randomization.
1048 Obtain a list of all active thread IDs from the target (OS). Since
1049 there may be too many active threads to fit into one reply packet,
1050 this query works iteratively: it may require more than one
1051 query/reply sequence to obtain the entire list of threads. The
1052 first query of the sequence will be the 'qfThreadInfo' query;
1053 subsequent queries in the sequence will be the 'qsThreadInfo'
1056 NOTE: This packet replaces the 'qL' query (see below).
1061 'm THREAD-ID,THREAD-ID...'
1062 a comma-separated list of thread IDs
1064 (lower case letter 'L') denotes end of list.
1066 In response to each query, the target will reply with a list of one
1067 or more thread IDs, separated by commas. GDB will respond to each
1068 reply with a request for more thread ids (using the 'qs' form of
1069 the query), until the target responds with 'l' (lower-case ell, for
1070 "last"). Refer to *note thread-id syntax::, for the format of the
1073 _Note: GDB will send the 'qfThreadInfo' query during the initial
1074 connection with the remote target, and the very first thread ID
1075 mentioned in the reply will be stopped by GDB in a subsequent
1076 message. Therefore, the stub should ensure that the first thread
1077 ID in the 'qfThreadInfo' reply is suitable for being stopped by
1080 'qGetTLSAddr:THREAD-ID,OFFSET,LM'
1081 Fetch the address associated with thread local storage specified by
1082 THREAD-ID, OFFSET, and LM.
1084 THREAD-ID is the thread ID associated with the thread for which to
1085 fetch the TLS address. *Note thread-id syntax::.
1087 OFFSET is the (big endian, hex encoded) offset associated with the
1088 thread local variable. (This offset is obtained from the debug
1089 information associated with the variable.)
1091 LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
1092 load module associated with the thread local storage. For example,
1093 a GNU/Linux system will pass the link map address of the shared
1094 object associated with the thread local storage under
1095 consideration. Other operating environments may choose to
1096 represent the load module differently, so the precise meaning of
1097 this parameter will vary.
1101 Hex encoded (big endian) bytes representing the address of the
1102 thread local storage requested.
1105 An error occurred. The error number NN is given as hex
1109 An empty reply indicates that 'qGetTLSAddr' is not supported
1112 'qGetTIBAddr:THREAD-ID'
1113 Fetch address of the Windows OS specific Thread Information Block.
1115 THREAD-ID is the thread ID associated with the thread.
1119 Hex encoded (big endian) bytes representing the linear address
1120 of the thread information block.
1123 An error occured. This means that either the thread was not
1124 found, or the address could not be retrieved.
1127 An empty reply indicates that 'qGetTIBAddr' is not supported
1130 'qL STARTFLAG THREADCOUNT NEXTTHREAD'
1131 Obtain thread information from RTOS. Where: STARTFLAG (one hex
1132 digit) is one to indicate the first query and zero to indicate a
1133 subsequent query; THREADCOUNT (two hex digits) is the maximum
1134 number of threads the response packet can contain; and NEXTTHREAD
1135 (eight hex digits), for subsequent queries (STARTFLAG is zero), is
1136 returned in the response as ARGTHREAD.
1138 Don't use this packet; use the 'qfThreadInfo' query instead (see
1142 'qM COUNT DONE ARGTHREAD THREAD...'
1143 Where: COUNT (two hex digits) is the number of threads being
1144 returned; DONE (one hex digit) is zero to indicate more
1145 threads and one indicates no further threads; ARGTHREADID
1146 (eight hex digits) is NEXTTHREAD from the request packet;
1147 THREAD... is a sequence of thread IDs, THREADID (eight hex
1148 digits), from the target. See
1149 'remote.c:parse_threadlist_response()'.
1152 Get section offsets that the target used when relocating the
1156 'Text=XXX;Data=YYY[;Bss=ZZZ]'
1157 Relocate the 'Text' section by XXX from its original address.
1158 Relocate the 'Data' section by YYY from its original address.
1159 If the object file format provides segment information (e.g.
1160 ELF 'PT_LOAD' program headers), GDB will relocate entire
1161 segments by the supplied offsets.
1163 _Note: while a 'Bss' offset may be included in the response,
1164 GDB ignores this and instead applies the 'Data' offset to the
1167 'TextSeg=XXX[;DataSeg=YYY]'
1168 Relocate the first segment of the object file, which
1169 conventionally contains program code, to a starting address of
1170 XXX. If 'DataSeg' is specified, relocate the second segment,
1171 which conventionally contains modifiable data, to a starting
1172 address of YYY. GDB will report an error if the object file
1173 does not contain segment information, or does not contain at
1174 least as many segments as mentioned in the reply. Extra
1175 segments are kept at fixed offsets relative to the last
1179 Returns information on THREAD-ID. Where: MODE is a hex encoded 32
1180 bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).
1182 Don't use this packet; use the 'qThreadExtraInfo' query instead
1185 Reply: see 'remote.c:remote_unpack_thread_info_response()'.
1189 Enter non-stop ('QNonStop:1') or all-stop ('QNonStop:0') mode.
1190 *Note Remote Non-Stop::, for more information.
1194 The request succeeded.
1197 An error occurred. The error number NN is given as hex
1201 An empty reply indicates that 'QNonStop' is not supported by
1204 This packet is not probed by default; the remote stub must request
1205 it, by supplying an appropriate 'qSupported' response (*note
1206 qSupported::). Use of this packet is controlled by the 'set
1207 non-stop' command; *note Non-Stop Mode::.
1209 'QPassSignals: SIGNAL [;SIGNAL]...'
1210 Each listed SIGNAL should be passed directly to the inferior
1211 process. Signals are numbered identically to continue packets and
1212 stop replies (*note Stop Reply Packets::). Each SIGNAL list item
1213 should be strictly greater than the previous item. These signals
1214 do not need to stop the inferior, or be reported to GDB. All other
1215 signals should be reported to GDB. Multiple 'QPassSignals' packets
1216 do not combine; any earlier 'QPassSignals' list is completely
1217 replaced by the new list. This packet improves performance when
1218 using 'handle SIGNAL nostop noprint pass'.
1222 The request succeeded.
1225 An error occurred. The error number NN is given as hex
1229 An empty reply indicates that 'QPassSignals' is not supported
1232 Use of this packet is controlled by the 'set remote pass-signals'
1233 command (*note set remote pass-signals: Remote Configuration.).
1234 This packet is not probed by default; the remote stub must request
1235 it, by supplying an appropriate 'qSupported' response (*note
1238 'QProgramSignals: SIGNAL [;SIGNAL]...'
1239 Each listed SIGNAL may be delivered to the inferior process.
1240 Others should be silently discarded.
1242 In some cases, the remote stub may need to decide whether to
1243 deliver a signal to the program or not without GDB involvement.
1244 One example of that is while detaching -- the program's threads may
1245 have stopped for signals that haven't yet had a chance of being
1246 reported to GDB, and so the remote stub can use the signal list
1247 specified by this packet to know whether to deliver or ignore those
1250 This does not influence whether to deliver a signal as requested by
1251 a resumption packet (*note vCont packet::).
1253 Signals are numbered identically to continue packets and stop
1254 replies (*note Stop Reply Packets::). Each SIGNAL list item should
1255 be strictly greater than the previous item. Multiple
1256 'QProgramSignals' packets do not combine; any earlier
1257 'QProgramSignals' list is completely replaced by the new list.
1261 The request succeeded.
1264 An error occurred. The error number NN is given as hex
1268 An empty reply indicates that 'QProgramSignals' is not
1269 supported by the stub.
1271 Use of this packet is controlled by the 'set remote
1272 program-signals' command (*note set remote program-signals: Remote
1273 Configuration.). This packet is not probed by default; the remote
1274 stub must request it, by supplying an appropriate 'qSupported'
1275 response (*note qSupported::).
1278 COMMAND (hex encoded) is passed to the local interpreter for
1279 execution. Invalid commands should be reported using the output
1280 string. Before the final result packet, the target may also
1281 respond with a number of intermediate 'OOUTPUT' console output
1282 packets. _Implementors should note that providing access to a
1283 stubs's interpreter may have security implications_.
1287 A command response with no output.
1289 A command response with the hex encoded output string OUTPUT.
1291 Indicate a badly formed request.
1293 An empty reply indicates that 'qRcmd' is not recognized.
1295 (Note that the 'qRcmd' packet's name is separated from the command
1296 by a ',', not a ':', contrary to the naming conventions above.
1297 Please don't use this packet as a model for new packets.)
1299 'qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'
1300 Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. Both ADDRESS
1301 and LENGTH are encoded in hex; SEARCH-PATTERN is a sequence of
1302 bytes, also hex encoded.
1306 The pattern was not found.
1308 The pattern was found at ADDRESS.
1310 A badly formed request or an error was encountered while
1313 An empty reply indicates that 'qSearch:memory' is not
1317 Request that the remote stub disable the normal '+'/'-' protocol
1318 acknowledgments (*note Packet Acknowledgment::).
1322 The stub has switched to no-acknowledgment mode. GDB
1323 acknowledges this reponse, but neither the stub nor GDB shall
1324 send or expect further '+'/'-' acknowledgments in the current
1327 An empty reply indicates that the stub does not support
1328 no-acknowledgment mode.
1330 'qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
1331 Tell the remote stub about features supported by GDB, and query the
1332 stub for features it supports. This packet allows GDB and the
1333 remote stub to take advantage of each others' features.
1334 'qSupported' also consolidates multiple feature probes at startup,
1335 to improve GDB performance--a single larger packet performs better
1336 than multiple smaller probe packets on high-latency links. Some
1337 features may enable behavior which must not be on by default, e.g.
1338 because it would confuse older clients or stubs. Other features
1339 may describe packets which could be automatically probed for, but
1340 are not. These features must be reported before GDB will use them.
1341 This "default unsupported" behavior is not appropriate for all
1342 packets, but it helps to keep the initial connection time under
1343 control with new versions of GDB which support increasing numbers
1347 'STUBFEATURE [;STUBFEATURE]...'
1348 The stub supports or does not support each returned
1349 STUBFEATURE, depending on the form of each STUBFEATURE (see
1350 below for the possible forms).
1352 An empty reply indicates that 'qSupported' is not recognized,
1353 or that no features needed to be reported to GDB.
1355 The allowed forms for each feature (either a GDBFEATURE in the
1356 'qSupported' packet, or a STUBFEATURE in the response) are:
1359 The remote protocol feature NAME is supported, and associated
1360 with the specified VALUE. The format of VALUE depends on the
1361 feature, but it must not include a semicolon.
1363 The remote protocol feature NAME is supported, and does not
1364 need an associated value.
1366 The remote protocol feature NAME is not supported.
1368 The remote protocol feature NAME may be supported, and GDB
1369 should auto-detect support in some other way when it is
1370 needed. This form will not be used for GDBFEATURE
1371 notifications, but may be used for STUBFEATURE responses.
1373 Whenever the stub receives a 'qSupported' request, the supplied set
1374 of GDB features should override any previous request. This allows
1375 GDB to put the stub in a known state, even if the stub had
1376 previously been communicating with a different version of GDB.
1378 The following values of GDBFEATURE (for the packet sent by GDB) are
1382 This feature indicates whether GDB supports multiprocess
1383 extensions to the remote protocol. GDB does not use such
1384 extensions unless the stub also reports that it supports them
1385 by including 'multiprocess+' in its 'qSupported' reply. *Note
1386 multiprocess extensions::, for details.
1389 This feature indicates that GDB supports the XML target
1390 description. If the stub sees 'xmlRegisters=' with target
1391 specific strings separated by a comma, it will report register
1395 This feature indicates whether GDB supports the 'qRelocInsn'
1396 packet (*note Relocate instruction reply packet: Tracepoint
1399 Stubs should ignore any unknown values for GDBFEATURE. Any GDB
1400 which sends a 'qSupported' packet supports receiving packets of
1401 unlimited length (earlier versions of GDB may reject overly long
1402 responses). Additional values for GDBFEATURE may be defined in the
1403 future to let the stub take advantage of new features in GDB, e.g.
1404 incompatible improvements in the remote protocol--the
1405 'multiprocess' feature is an example of such a feature. The stub's
1406 reply should be independent of the GDBFEATURE entries sent by GDB;
1407 first GDB describes all the features it supports, and then the stub
1408 replies with all the features it supports.
1410 Similarly, GDB will silently ignore unrecognized stub feature
1411 responses, as long as each response uses one of the standard forms.
1413 Some features are flags. A stub which supports a flag feature
1414 should respond with a '+' form response. Other features require
1415 values, and the stub should respond with an '=' form response.
1417 Each feature has a default value, which GDB will use if
1418 'qSupported' is not available or if the feature is not mentioned in
1419 the 'qSupported' response. The default values are fixed; a stub is
1420 free to omit any feature responses that match the defaults.
1422 Not all features can be probed, but for those which can, the
1423 probing mechanism is useful: in some cases, a stub's internal
1424 architecture may not allow the protocol layer to know some
1425 information about the underlying target in advance. This is
1426 especially common in stubs which may be configured for multiple
1429 These are the currently defined stub features and their properties:
1431 Feature Name Value Default Probe
1434 'PacketSize' Yes '-' No
1436 'qXfer:auxv:read' No '-' Yes
1438 'qXfer:btrace:read' No '-' Yes
1440 'qXfer:features:read' No '-' Yes
1442 'qXfer:libraries:read' No '-' Yes
1444 'qXfer:libraries-svr4:read'No '-' Yes
1446 'augmented-libraries-svr4-read'No '-' No
1448 'qXfer:memory-map:read' No '-' Yes
1450 'qXfer:sdata:read' No '-' Yes
1452 'qXfer:spu:read' No '-' Yes
1454 'qXfer:spu:write' No '-' Yes
1456 'qXfer:siginfo:read' No '-' Yes
1458 'qXfer:siginfo:write' No '-' Yes
1460 'qXfer:threads:read' No '-' Yes
1462 'qXfer:traceframe-info:read'No '-' Yes
1464 'qXfer:uib:read' No '-' Yes
1466 'qXfer:fdpic:read' No '-' Yes
1468 'Qbtrace:off' Yes '-' Yes
1470 'Qbtrace:bts' Yes '-' Yes
1472 'QNonStop' No '-' Yes
1474 'QPassSignals' No '-' Yes
1476 'QStartNoAckMode' No '-' Yes
1478 'multiprocess' No '-' No
1480 'ConditionalBreakpoints' No '-' No
1482 'ConditionalTracepoints' No '-' No
1484 'ReverseContinue' No '-' No
1486 'ReverseStep' No '-' No
1488 'TracepointSource' No '-' No
1494 'QDisableRandomization' No '-' No
1496 'EnableDisableTracepoints'No '-' No
1498 'QTBuffer:size' No '-' No
1502 'BreakpointCommands' No '-' No
1505 These are the currently defined stub features, in more detail:
1508 The remote stub can accept packets up to at least BYTES in
1509 length. GDB will send packets up to this size for bulk
1510 transfers, and will never send larger packets. This is a
1511 limit on the data characters in the packet, including the
1512 frame and checksum. There is no trailing NUL byte in a remote
1513 protocol packet; if the stub stores packets in a
1514 NUL-terminated format, it should allow an extra byte in its
1515 buffer for the NUL. If this stub feature is not supported, GDB
1516 guesses based on the size of the 'g' packet response.
1519 The remote stub understands the 'qXfer:auxv:read' packet
1520 (*note qXfer auxiliary vector read::).
1523 The remote stub understands the 'qXfer:btrace:read' packet
1524 (*note qXfer btrace read::).
1526 'qXfer:features:read'
1527 The remote stub understands the 'qXfer:features:read' packet
1528 (*note qXfer target description read::).
1530 'qXfer:libraries:read'
1531 The remote stub understands the 'qXfer:libraries:read' packet
1532 (*note qXfer library list read::).
1534 'qXfer:libraries-svr4:read'
1535 The remote stub understands the 'qXfer:libraries-svr4:read'
1536 packet (*note qXfer svr4 library list read::).
1538 'augmented-libraries-svr4-read'
1539 The remote stub understands the augmented form of the
1540 'qXfer:libraries-svr4:read' packet (*note qXfer svr4 library
1543 'qXfer:memory-map:read'
1544 The remote stub understands the 'qXfer:memory-map:read' packet
1545 (*note qXfer memory map read::).
1548 The remote stub understands the 'qXfer:sdata:read' packet
1549 (*note qXfer sdata read::).
1552 The remote stub understands the 'qXfer:spu:read' packet (*note
1556 The remote stub understands the 'qXfer:spu:write' packet
1557 (*note qXfer spu write::).
1559 'qXfer:siginfo:read'
1560 The remote stub understands the 'qXfer:siginfo:read' packet
1561 (*note qXfer siginfo read::).
1563 'qXfer:siginfo:write'
1564 The remote stub understands the 'qXfer:siginfo:write' packet
1565 (*note qXfer siginfo write::).
1567 'qXfer:threads:read'
1568 The remote stub understands the 'qXfer:threads:read' packet
1569 (*note qXfer threads read::).
1571 'qXfer:traceframe-info:read'
1572 The remote stub understands the 'qXfer:traceframe-info:read'
1573 packet (*note qXfer traceframe info read::).
1576 The remote stub understands the 'qXfer:uib:read' packet (*note
1577 qXfer unwind info block::).
1580 The remote stub understands the 'qXfer:fdpic:read' packet
1581 (*note qXfer fdpic loadmap read::).
1584 The remote stub understands the 'QNonStop' packet (*note
1588 The remote stub understands the 'QPassSignals' packet (*note
1592 The remote stub understands the 'QStartNoAckMode' packet and
1593 prefers to operate in no-acknowledgment mode. *Note Packet
1597 The remote stub understands the multiprocess extensions to the
1598 remote protocol syntax. The multiprocess extensions affect
1599 the syntax of thread IDs in both packets and replies (*note
1600 thread-id syntax::), and add process IDs to the 'D' packet and
1601 'W' and 'X' replies. Note that reporting this feature
1602 indicates support for the syntactic extensions only, not that
1603 the stub necessarily supports debugging of more than one
1604 process at a time. The stub must not use multiprocess
1605 extensions in packet replies unless GDB has also indicated it
1606 supports them in its 'qSupported' request.
1609 The remote stub understands the 'qXfer:osdata:read' packet
1610 ((*note qXfer osdata read::).
1612 'ConditionalBreakpoints'
1613 The target accepts and implements evaluation of conditional
1614 expressions defined for breakpoints. The target will only
1615 report breakpoint triggers when such conditions are true
1616 (*note Break Conditions: Conditions.).
1618 'ConditionalTracepoints'
1619 The remote stub accepts and implements conditional expressions
1620 defined for tracepoints (*note Tracepoint Conditions::).
1623 The remote stub accepts and implements the reverse continue
1624 packet (*note bc::).
1627 The remote stub accepts and implements the reverse step packet
1631 The remote stub understands the 'QTDPsrc' packet that supplies
1632 the source form of tracepoint definitions.
1635 The remote stub understands the 'QAgent' packet.
1638 The remote stub understands the 'QAllow' packet.
1640 'QDisableRandomization'
1641 The remote stub understands the 'QDisableRandomization'
1645 The remote stub supports static tracepoints.
1648 The remote stub supports installing tracepoint in tracing.
1650 'EnableDisableTracepoints'
1651 The remote stub supports the 'QTEnable' (*note QTEnable::) and
1652 'QTDisable' (*note QTDisable::) packets that allow tracepoints
1653 to be enabled and disabled while a trace experiment is
1657 The remote stub supports the 'QTBuffer:size' (*note
1658 QTBuffer-size::) packet that allows to change the size of the
1662 The remote stub supports the 'tracenz' bytecode for collecting
1663 strings. See *note Bytecode Descriptions:: for details about
1666 'BreakpointCommands'
1667 The remote stub supports running a breakpoint's command list
1668 itself, rather than reporting the hit to GDB.
1671 The remote stub understands the 'Qbtrace:off' packet.
1674 The remote stub understands the 'Qbtrace:bts' packet.
1677 Notify the target that GDB is prepared to serve symbol lookup
1678 requests. Accept requests from the target for the values of
1683 The target does not need to look up any (more) symbols.
1685 The target requests the value of symbol SYM_NAME (hex
1686 encoded). GDB may provide the value by using the
1687 'qSymbol:SYM_VALUE:SYM_NAME' message, described below.
1689 'qSymbol:SYM_VALUE:SYM_NAME'
1690 Set the value of SYM_NAME to SYM_VALUE.
1692 SYM_NAME (hex encoded) is the name of a symbol whose value the
1693 target has previously requested.
1695 SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot
1696 supply a value for SYM_NAME, then this field will be empty.
1700 The target does not need to look up any (more) symbols.
1702 The target requests the value of a new symbol SYM_NAME (hex
1703 encoded). GDB will continue to supply the values of symbols
1704 (if available), until the target ceases to request them.
1717 *Note Tracepoint Packets::.
1719 'qThreadExtraInfo,THREAD-ID'
1720 Obtain from the target OS a printable string description of thread
1721 attributes for the thread THREAD-ID; see *note thread-id syntax::,
1722 for the forms of THREAD-ID. This string may contain anything that
1723 the target OS thinks is interesting for GDB to tell the user about
1724 the thread. The string is displayed in GDB's 'info threads'
1725 display. Some examples of possible thread extra info strings are
1726 'Runnable', or 'Blocked on Mutex'.
1730 Where 'XX...' is a hex encoding of ASCII data, comprising the
1731 printable string containing the extra information about the
1732 thread's attributes.
1734 (Note that the 'qThreadExtraInfo' packet's name is separated from
1735 the command by a ',', not a ':', contrary to the naming conventions
1736 above. Please don't use this packet as a model for new packets.)
1754 *Note Tracepoint Packets::.
1756 'qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
1757 Read uninterpreted bytes from the target's special data area
1758 identified by the keyword OBJECT. Request LENGTH bytes starting at
1759 OFFSET bytes into the data. The content and encoding of ANNEX is
1760 specific to OBJECT; it can supply additional details about what
1763 Here are the specific requests of this form defined so far. All
1764 'qXfer:OBJECT:read:...' requests use the same reply formats, listed
1767 'qXfer:auxv:read::OFFSET,LENGTH'
1768 Access the target's "auxiliary vector". *Note auxiliary
1769 vector: OS Information. Note ANNEX must be empty.
1771 This packet is not probed by default; the remote stub must
1772 request it, by supplying an appropriate 'qSupported' response
1773 (*note qSupported::).
1775 'qXfer:btrace:read:ANNEX:OFFSET,LENGTH'
1777 Return a description of the current branch trace. *Note
1778 Branch Trace Format::. The annex part of the generic 'qXfer'
1779 packet may have one of the following values:
1782 Returns all available branch trace.
1785 Returns all available branch trace if the branch trace
1786 changed since the last read request.
1789 Returns the new branch trace since the last read request.
1790 Adds a new block to the end of the trace that begins at
1791 zero and ends at the source location of the first branch
1792 in the trace buffer. This extra block is used to stitch
1795 If the trace buffer overflowed, returns an error
1796 indicating the overflow.
1798 This packet is not probed by default; the remote stub must
1799 request it by supplying an appropriate 'qSupported' response
1800 (*note qSupported::).
1802 'qXfer:features:read:ANNEX:OFFSET,LENGTH'
1803 Access the "target description". *Note Target Descriptions::.
1804 The annex specifies which XML document to access. The main
1805 description is always loaded from the 'target.xml' annex.
1807 This packet is not probed by default; the remote stub must
1808 request it, by supplying an appropriate 'qSupported' response
1809 (*note qSupported::).
1811 'qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
1812 Access the target's list of loaded libraries. *Note Library
1813 List Format::. The annex part of the generic 'qXfer' packet
1814 must be empty (*note qXfer read::).
1816 Targets which maintain a list of libraries in the program's
1817 memory do not need to implement this packet; it is designed
1818 for platforms where the operating system manages the list of
1821 This packet is not probed by default; the remote stub must
1822 request it, by supplying an appropriate 'qSupported' response
1823 (*note qSupported::).
1825 'qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH'
1826 Access the target's list of loaded libraries when the target
1827 is an SVR4 platform. *Note Library List Format for SVR4
1828 Targets::. The annex part of the generic 'qXfer' packet must
1829 be empty unless the remote stub indicated it supports the
1830 augmented form of this packet by supplying an appropriate
1831 'qSupported' response (*note qXfer read::, *note
1834 This packet is optional for better performance on SVR4
1835 targets. GDB uses memory read packets to read the SVR4
1836 library list otherwise.
1838 This packet is not probed by default; the remote stub must
1839 request it, by supplying an appropriate 'qSupported' response
1840 (*note qSupported::).
1842 If the remote stub indicates it supports the augmented form of
1843 this packet then the annex part of the generic 'qXfer' packet
1844 may contain a semicolon-separated list of 'NAME=VALUE'
1845 arguments. The currently supported arguments are:
1848 A hexadecimal number specifying the address of the
1849 'struct link_map' to start reading the library list from.
1850 If unset or zero then the first 'struct link_map' in the
1851 library list will be chosen as the starting point.
1854 A hexadecimal number specifying the address of the
1855 'struct link_map' immediately preceding the 'struct
1856 link_map' specified by the 'start' argument. If unset or
1857 zero then the remote stub will expect that no 'struct
1858 link_map' exists prior to the starting point.
1860 Arguments that are not understood by the remote stub will be
1863 'qXfer:memory-map:read::OFFSET,LENGTH'
1864 Access the target's "memory-map". *Note Memory Map Format::.
1865 The annex part of the generic 'qXfer' packet must be empty
1866 (*note qXfer read::).
1868 This packet is not probed by default; the remote stub must
1869 request it, by supplying an appropriate 'qSupported' response
1870 (*note qSupported::).
1872 'qXfer:sdata:read::OFFSET,LENGTH'
1874 Read contents of the extra collected static tracepoint marker
1875 information. The annex part of the generic 'qXfer' packet
1876 must be empty (*note qXfer read::). *Note Tracepoint Action
1877 Lists: Tracepoint Actions.
1879 This packet is not probed by default; the remote stub must
1880 request it, by supplying an appropriate 'qSupported' response
1881 (*note qSupported::).
1883 'qXfer:siginfo:read::OFFSET,LENGTH'
1884 Read contents of the extra signal information on the target
1885 system. The annex part of the generic 'qXfer' packet must be
1886 empty (*note qXfer read::).
1888 This packet is not probed by default; the remote stub must
1889 request it, by supplying an appropriate 'qSupported' response
1890 (*note qSupported::).
1892 'qXfer:spu:read:ANNEX:OFFSET,LENGTH'
1893 Read contents of an 'spufs' file on the target system. The
1894 annex specifies which file to read; it must be of the form
1895 'ID/NAME', where ID specifies an SPU context ID in the target
1896 process, and NAME identifes the 'spufs' file in that context
1899 This packet is not probed by default; the remote stub must
1900 request it, by supplying an appropriate 'qSupported' response
1901 (*note qSupported::).
1903 'qXfer:threads:read::OFFSET,LENGTH'
1904 Access the list of threads on target. *Note Thread List
1905 Format::. The annex part of the generic 'qXfer' packet must
1906 be empty (*note qXfer read::).
1908 This packet is not probed by default; the remote stub must
1909 request it, by supplying an appropriate 'qSupported' response
1910 (*note qSupported::).
1912 'qXfer:traceframe-info:read::OFFSET,LENGTH'
1914 Return a description of the current traceframe's contents.
1915 *Note Traceframe Info Format::. The annex part of the generic
1916 'qXfer' packet must be empty (*note qXfer read::).
1918 This packet is not probed by default; the remote stub must
1919 request it, by supplying an appropriate 'qSupported' response
1920 (*note qSupported::).
1922 'qXfer:uib:read:PC:OFFSET,LENGTH'
1924 Return the unwind information block for PC. This packet is
1925 used on OpenVMS/ia64 to ask the kernel unwind information.
1927 This packet is not probed by default.
1929 'qXfer:fdpic:read:ANNEX:OFFSET,LENGTH'
1930 Read contents of 'loadmap's on the target system. The annex,
1931 either 'exec' or 'interp', specifies which 'loadmap',
1932 executable 'loadmap' or interpreter 'loadmap' to read.
1934 This packet is not probed by default; the remote stub must
1935 request it, by supplying an appropriate 'qSupported' response
1936 (*note qSupported::).
1938 'qXfer:osdata:read::OFFSET,LENGTH'
1939 Access the target's "operating system information". *Note
1940 Operating System Information::.
1944 Data DATA (*note Binary Data::) has been read from the target.
1945 There may be more data at a higher address (although it is
1946 permitted to return 'm' even for the last valid block of data,
1947 as long as at least one byte of data was read). It is
1948 possible for DATA to have fewer bytes than the LENGTH in the
1952 Data DATA (*note Binary Data::) has been read from the target.
1953 There is no more data to be read. It is possible for DATA to
1954 have fewer bytes than the LENGTH in the request.
1957 The OFFSET in the request is at the end of the data. There is
1958 no more data to be read.
1961 The request was malformed, or ANNEX was invalid.
1964 The offset was invalid, or there was an error encountered
1965 reading the data. The NN part is a hex-encoded 'errno' value.
1968 An empty reply indicates the OBJECT string was not recognized
1969 by the stub, or that the object does not support reading.
1971 'qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
1972 Write uninterpreted bytes into the target's special data area
1973 identified by the keyword OBJECT, starting at OFFSET bytes into the
1974 data. The binary-encoded data (*note Binary Data::) to be written
1975 is given by DATA.... The content and encoding of ANNEX is specific
1976 to OBJECT; it can supply additional details about what data to
1979 Here are the specific requests of this form defined so far. All
1980 'qXfer:OBJECT:write:...' requests use the same reply formats,
1983 'qXfer:siginfo:write::OFFSET:DATA...'
1984 Write DATA to the extra signal information on the target
1985 system. The annex part of the generic 'qXfer' packet must be
1986 empty (*note qXfer write::).
1988 This packet is not probed by default; the remote stub must
1989 request it, by supplying an appropriate 'qSupported' response
1990 (*note qSupported::).
1992 'qXfer:spu:write:ANNEX:OFFSET:DATA...'
1993 Write DATA to an 'spufs' file on the target system. The annex
1994 specifies which file to write; it must be of the form
1995 'ID/NAME', where ID specifies an SPU context ID in the target
1996 process, and NAME identifes the 'spufs' file in that context
1999 This packet is not probed by default; the remote stub must
2000 request it, by supplying an appropriate 'qSupported' response
2001 (*note qSupported::).
2005 NN (hex encoded) is the number of bytes written. This may be
2006 fewer bytes than supplied in the request.
2009 The request was malformed, or ANNEX was invalid.
2012 The offset was invalid, or there was an error encountered
2013 writing the data. The NN part is a hex-encoded 'errno' value.
2016 An empty reply indicates the OBJECT string was not recognized
2017 by the stub, or that the object does not support writing.
2019 'qXfer:OBJECT:OPERATION:...'
2020 Requests of this form may be added in the future. When a stub does
2021 not recognize the OBJECT keyword, or its support for OBJECT does
2022 not recognize the OPERATION keyword, the stub must respond with an
2026 Return an indication of whether the remote server attached to an
2027 existing process or created a new process. When the multiprocess
2028 protocol extensions are supported (*note multiprocess
2029 extensions::), PID is an integer in hexadecimal format identifying
2030 the target process. Otherwise, GDB will omit the PID field and the
2031 query packet will be simplified as 'qAttached'.
2033 This query is used, for example, to know whether the remote process
2034 should be detached or killed when a GDB session is ended with the
2039 The remote server attached to an existing process.
2041 The remote server created a new process.
2043 A badly formed request or an error was encountered.
2046 Enable branch tracing for the current thread using bts tracing.
2050 Branch tracing has been enabled.
2052 A badly formed request or an error was encountered.
2055 Disable branch tracing for the current thread.
2059 Branch tracing has been disabled.
2061 A badly formed request or an error was encountered.
2063 ---------- Footnotes ----------
2065 (1) The 'qP' and 'qL' packets predate these conventions, and have
2066 arguments without any terminator for the packet name; we suspect they
2067 are in widespread use in places that are difficult to upgrade. The 'qC'
2068 packet has no arguments, but some existing stubs (e.g. RedBoot) are
2069 known to not check for the end of the packet.
2072 File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol
2074 E.5 Architecture-Specific Protocol Details
2075 ==========================================
2077 This section describes how the remote protocol is applied to specific
2078 target architectures. Also see *note Standard Target Features::, for
2079 details of XML target descriptions for each architecture.
2083 * ARM-Specific Protocol Details::
2084 * MIPS-Specific Protocol Details::
2087 File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details
2089 E.5.1 ARM-specific Protocol Details
2090 -----------------------------------
2094 * ARM Breakpoint Kinds::
2097 File: gdb.info, Node: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details
2099 E.5.1.1 ARM Breakpoint Kinds
2100 ............................
2102 These breakpoint kinds are defined for the 'Z0' and 'Z1' packets.
2105 16-bit Thumb mode breakpoint.
2108 32-bit Thumb mode (Thumb-2) breakpoint.
2111 32-bit ARM mode breakpoint.
2114 File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details
2116 E.5.2 MIPS-specific Protocol Details
2117 ------------------------------------
2121 * MIPS Register packet Format::
2122 * MIPS Breakpoint Kinds::
2125 File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details
2127 E.5.2.1 MIPS Register Packet Format
2128 ...................................
2130 The following 'g'/'G' packets have previously been defined. In the
2131 below, some thirty-two bit registers are transferred as sixty-four bits.
2132 Those registers should be zero/sign extended (which?) to fill the space
2133 allocated. Register bytes are transferred in target byte order. The
2134 two nibbles within a register byte are transferred most-significant -
2138 All registers are transferred as thirty-two bit quantities in the
2139 order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
2140 floating-point registers; fsr; fir; fp.
2143 All registers are transferred as sixty-four bit quantities
2144 (including thirty-two bit registers such as 'sr'). The ordering is
2145 the same as 'MIPS32'.
2148 File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details
2150 E.5.2.2 MIPS Breakpoint Kinds
2151 .............................
2153 These breakpoint kinds are defined for the 'Z0' and 'Z1' packets.
2156 16-bit MIPS16 mode breakpoint.
2159 16-bit microMIPS mode breakpoint.
2162 32-bit standard MIPS mode breakpoint.
2165 32-bit microMIPS mode breakpoint.
2168 File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol
2170 E.6 Tracepoint Packets
2171 ======================
2173 Here we describe the packets GDB uses to implement tracepoints (*note
2176 'QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
2177 Create a new tracepoint, number N, at ADDR. If ENA is 'E', then
2178 the tracepoint is enabled; if it is 'D', then the tracepoint is
2179 disabled. The STEP gives the tracepoint's step count, and PASS
2180 gives its pass count. If an 'F' is present, then the tracepoint is
2181 to be a fast tracepoint, and the FLEN is the number of bytes that
2182 the target should copy elsewhere to make room for the tracepoint.
2183 If an 'X' is present, it introduces a tracepoint condition, which
2184 consists of a hexadecimal length, followed by a comma and
2185 hex-encoded bytes, in a manner similar to action encodings as
2186 described below. If the trailing '-' is present, further 'QTDP'
2187 packets will follow to specify this tracepoint's actions.
2191 The packet was understood and carried out.
2193 *Note Relocate instruction reply packet: Tracepoint Packets.
2195 The packet was not recognized.
2197 'QTDP:-N:ADDR:[S]ACTION...[-]'
2198 Define actions to be taken when a tracepoint is hit. The N and
2199 ADDR must be the same as in the initial 'QTDP' packet for this
2200 tracepoint. This packet may only be sent immediately after another
2201 'QTDP' packet that ended with a '-'. If the trailing '-' is
2202 present, further 'QTDP' packets will follow, specifying more
2203 actions for this tracepoint.
2205 In the series of action packets for a given tracepoint, at most one
2206 can have an 'S' before its first ACTION. If such a packet is sent,
2207 it and the following packets define "while-stepping" actions. Any
2208 prior packets define ordinary actions -- that is, those taken when
2209 the tracepoint is first hit. If no action packet has an 'S', then
2210 all the packets in the series specify ordinary tracepoint actions.
2212 The 'ACTION...' portion of the packet is a series of actions,
2213 concatenated without separators. Each action has one of the
2217 Collect the registers whose bits are set in MASK, a
2218 hexadecimal number whose I'th bit is set if register number I
2219 should be collected. (The least significant bit is numbered
2220 zero.) Note that MASK may be any number of digits long; it
2221 may not fit in a 32-bit word.
2223 'M BASEREG,OFFSET,LEN'
2224 Collect LEN bytes of memory starting at the address in
2225 register number BASEREG, plus OFFSET. If BASEREG is '-1',
2226 then the range has a fixed address: OFFSET is the address of
2227 the lowest byte to collect. The BASEREG, OFFSET, and LEN
2228 parameters are all unsigned hexadecimal values (the '-1' value
2229 for BASEREG is a special case).
2232 Evaluate EXPR, whose length is LEN, and collect memory as it
2233 directs. The agent expression EXPR is as described in *note
2234 Agent Expressions::. Each byte of the expression is encoded
2235 as a two-digit hex number in the packet; LEN is the number of
2236 bytes in the expression (and thus one-half the number of hex
2237 digits in the packet).
2239 Any number of actions may be packed together in a single 'QTDP'
2240 packet, as long as the packet does not exceed the maximum packet
2241 length (400 bytes, for many stubs). There may be only one 'R'
2242 action per tracepoint, and it must precede any 'M' or 'X' actions.
2243 Any registers referred to by 'M' and 'X' actions must be collected
2244 by a preceding 'R' action. (The "while-stepping" actions are
2245 treated as if they were attached to a separate tracepoint, as far
2246 as these restrictions are concerned.)
2250 The packet was understood and carried out.
2252 *Note Relocate instruction reply packet: Tracepoint Packets.
2254 The packet was not recognized.
2256 'QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES'
2257 Specify a source string of tracepoint N at address ADDR. This is
2258 useful to get accurate reproduction of the tracepoints originally
2259 downloaded at the beginning of the trace run. The TYPE is the name
2260 of the tracepoint part, such as 'cond' for the tracepoint's
2261 conditional expression (see below for a list of types), while BYTES
2262 is the string, encoded in hexadecimal.
2264 START is the offset of the BYTES within the overall source string,
2265 while SLEN is the total length of the source string. This is
2266 intended for handling source strings that are longer than will fit
2269 The available string types are 'at' for the location, 'cond' for
2270 the conditional, and 'cmd' for an action command. GDB sends a
2271 separate packet for each command in the action list, in the same
2272 order in which the commands are stored in the list.
2274 The target does not need to do anything with source strings except
2275 report them back as part of the replies to the 'qTfP'/'qTsP' query
2278 Although this packet is optional, and GDB will only send it if the
2279 target replies with 'TracepointSource' *Note General Query
2280 Packets::, it makes both disconnected tracing and trace files much
2281 easier to use. Otherwise the user must be careful that the
2282 tracepoints in effect while looking at trace frames are identical
2283 to the ones in effect during the trace run; even a small
2284 discrepancy could cause 'tdump' not to work, or a particular trace
2288 Create a new trace state variable, number N, with an initial value
2289 of VALUE, which is a 64-bit signed integer. Both N and VALUE are
2290 encoded as hexadecimal values. GDB has the option of not using
2291 this packet for initial values of zero; the target should simply
2292 create the trace state variables as they are mentioned in
2296 Select the N'th tracepoint frame from the buffer, and use the
2297 register and memory contents recorded there to answer subsequent
2298 request packets from GDB.
2300 A successful reply from the stub indicates that the stub has found
2301 the requested frame. The response is a series of parts,
2302 concatenated without separators, describing the frame we selected.
2303 Each part has one of the following forms:
2306 The selected frame is number N in the trace frame buffer; F is
2307 a hexadecimal number. If F is '-1', then there was no frame
2308 matching the criteria in the request packet.
2311 The selected trace frame records a hit of tracepoint number T;
2312 T is a hexadecimal number.
2315 Like 'QTFrame:N', but select the first tracepoint frame after the
2316 currently selected frame whose PC is ADDR; ADDR is a hexadecimal
2320 Like 'QTFrame:N', but select the first tracepoint frame after the
2321 currently selected frame that is a hit of tracepoint T; T is a
2324 'QTFrame:range:START:END'
2325 Like 'QTFrame:N', but select the first tracepoint frame after the
2326 currently selected frame whose PC is between START (inclusive) and
2327 END (inclusive); START and END are hexadecimal numbers.
2329 'QTFrame:outside:START:END'
2330 Like 'QTFrame:range:START:END', but select the first frame
2331 _outside_ the given range of addresses (exclusive).
2334 This packet requests the minimum length of instruction at which a
2335 fast tracepoint (*note Set Tracepoints::) may be placed. For
2336 instance, on the 32-bit x86 architecture, it is possible to use a
2337 4-byte jump, but it depends on the target system being able to
2338 create trampolines in the first 64K of memory, which might or might
2339 not be possible for that system. So the reply to this packet will
2340 be 4 if it is able to arrange for that.
2345 The minimum instruction length is currently unknown.
2347 The minimum instruction length is LENGTH, where LENGTH is a
2348 hexadecimal number greater or equal to 1. A reply of 1 means
2349 that a fast tracepoint may be placed on any instruction
2352 An error has occurred.
2354 An empty reply indicates that the request is not supported by
2358 Begin the tracepoint experiment. Begin collecting data from
2359 tracepoint hits in the trace frame buffer. This packet supports
2360 the 'qRelocInsn' reply (*note Relocate instruction reply packet:
2361 Tracepoint Packets.).
2364 End the tracepoint experiment. Stop collecting trace frames.
2367 Enable tracepoint N at address ADDR in a started tracepoint
2368 experiment. If the tracepoint was previously disabled, then
2369 collection of data from it will resume.
2372 Disable tracepoint N at address ADDR in a started tracepoint
2373 experiment. No more data will be collected from the tracepoint
2374 unless 'QTEnable:N:ADDR' is subsequently issued.
2377 Clear the table of tracepoints, and empty the trace frame buffer.
2379 'QTro:START1,END1:START2,END2:...'
2380 Establish the given ranges of memory as "transparent". The stub
2381 will answer requests for these ranges from memory's current
2382 contents, if they were not collected as part of the tracepoint hit.
2384 GDB uses this to mark read-only regions of memory, like those
2385 containing program code. Since these areas never change, they
2386 should still have the same contents they did when the tracepoint
2387 was hit, so there's no reason for the stub to refuse to provide
2390 'QTDisconnected:VALUE'
2391 Set the choice to what to do with the tracing run when GDB
2392 disconnects from the target. A VALUE of 1 directs the target to
2393 continue the tracing run, while 0 tells the target to stop tracing
2394 if GDB is no longer in the picture.
2397 Ask the stub if there is a trace experiment running right now.
2399 The reply has the form:
2401 'TRUNNING[;FIELD]...'
2402 RUNNING is a single digit '1' if the trace is presently
2403 running, or '0' if not. It is followed by semicolon-separated
2404 optional fields that an agent may use to report additional
2407 If the trace is not running, the agent may report any of several
2408 explanations as one of the optional fields:
2411 No trace has been run yet.
2414 The trace was stopped by a user-originated stop command. The
2415 optional TEXT field is a user-supplied string supplied as part
2416 of the stop command (for instance, an explanation of why the
2417 trace was stopped manually). It is hex-encoded.
2420 The trace stopped because the trace buffer filled up.
2423 The trace stopped because GDB disconnected from the target.
2426 The trace stopped because tracepoint TPNUM exceeded its pass
2430 The trace stopped because tracepoint TPNUM had an error. The
2431 string TEXT is available to describe the nature of the error
2432 (for instance, a divide by zero in the condition expression);
2436 The trace stopped for some other reason.
2438 Additional optional fields supply statistical and other
2439 information. Although not required, they are extremely useful for
2440 users monitoring the progress of a trace run. If a trace has
2441 stopped, and these numbers are reported, they must reflect the
2442 state of the just-stopped trace.
2445 The number of trace frames in the buffer.
2448 The total number of trace frames created during the run. This
2449 may be larger than the trace frame count, if the buffer is
2453 The total size of the trace buffer, in bytes.
2456 The number of bytes still unused in the buffer.
2459 The value of the circular trace buffer flag. '1' means that
2460 the trace buffer is circular and old trace frames will be
2461 discarded if necessary to make room, '0' means that the trace
2462 buffer is linear and may fill up.
2465 The value of the disconnected tracing flag. '1' means that
2466 tracing will continue after GDB disconnects, '0' means that
2467 the trace run will stop.
2470 Ask the stub for the current state of tracepoint number TP at
2475 The tracepoint has been hit HITS times so far during the trace
2476 run, and accounts for USAGE in the trace buffer. Note that
2477 'while-stepping' steps are not counted as separate hits, but
2478 the steps' space consumption is added into the usage number.
2481 Ask the stub for the value of the trace state variable number VAR.
2485 The value of the variable is VALUE. This will be the current
2486 value of the variable if the user is examining a running
2487 target, or a saved value if the variable was collected in the
2488 trace frame that the user is looking at. Note that multiple
2489 requests may result in different reply values, such as when
2490 requesting values while the program is running.
2493 The value of the variable is unknown. This would occur, for
2494 example, if the user is examining a trace frame in which the
2495 requested variable was not collected.
2499 These packets request data about tracepoints that are being used by
2500 the target. GDB sends 'qTfP' to get the first piece of data, and
2501 multiple 'qTsP' to get additional pieces. Replies to these packets
2502 generally take the form of the 'QTDP' packets that define
2503 tracepoints. (FIXME add detailed syntax)
2507 These packets request data about trace state variables that are on
2508 the target. GDB sends 'qTfV' to get the first vari of data, and
2509 multiple 'qTsV' to get additional variables. Replies to these
2510 packets follow the syntax of the 'QTDV' packets that define trace
2515 These packets request data about static tracepoint markers that
2516 exist in the target program. GDB sends 'qTfSTM' to get the first
2517 piece of data, and multiple 'qTsSTM' to get additional pieces.
2518 Replies to these packets take the following form:
2521 'm ADDRESS:ID:EXTRA'
2523 'm ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...'
2524 a comma-separated list of markers
2526 (lower case letter 'L') denotes end of list.
2528 An error occurred. The error number NN is given as hex
2531 An empty reply indicates that the request is not supported by
2534 The ADDRESS is encoded in hex; ID and EXTRA are strings encoded in
2537 In response to each query, the target will reply with a list of one
2538 or more markers, separated by commas. GDB will respond to each
2539 reply with a request for more markers (using the 'qs' form of the
2540 query), until the target responds with 'l' (lower-case ell, for
2544 This packets requests data about static tracepoint markers in the
2545 target program at ADDRESS. Replies to this packet follow the
2546 syntax of the 'qTfSTM' and 'qTsSTM' packets that list static
2550 This packet directs the target to save trace data to the file name
2551 FILENAME in the target's filesystem. The FILENAME is encoded as a
2552 hex string; the interpretation of the file name (relative vs
2553 absolute, wild cards, etc) is up to the target.
2555 'qTBuffer:OFFSET,LEN'
2556 Return up to LEN bytes of the current contents of trace buffer,
2557 starting at OFFSET. The trace buffer is treated as if it were a
2558 contiguous collection of traceframes, as per the trace file format.
2559 The reply consists as many hex-encoded bytes as the target can
2560 deliver in a packet; it is not an error to return fewer than were
2561 asked for. A reply consisting of just 'l' indicates that no bytes
2564 'QTBuffer:circular:VALUE'
2565 This packet directs the target to use a circular trace buffer if
2566 VALUE is 1, or a linear buffer if the value is 0.
2568 'QTBuffer:size:SIZE'
2569 This packet directs the target to make the trace buffer be of size
2570 SIZE if possible. A value of '-1' tells the target to use whatever
2573 'QTNotes:[TYPE:TEXT][;TYPE:TEXT]...'
2574 This packet adds optional textual notes to the trace run.
2575 Allowable types include 'user', 'notes', and 'tstop', the TEXT
2576 fields are arbitrary strings, hex-encoded.
2578 E.6.1 Relocate instruction reply packet
2579 ---------------------------------------
2581 When installing fast tracepoints in memory, the target may need to
2582 relocate the instruction currently at the tracepoint address to a
2583 different address in memory. For most instructions, a simple copy is
2584 enough, but, for example, call instructions that implicitly push the
2585 return address on the stack, and relative branches or other PC-relative
2586 instructions require offset adjustment, so that the effect of executing
2587 the instruction at a different address is the same as if it had executed
2588 in the original location.
2590 In response to several of the tracepoint packets, the target may also
2591 respond with a number of intermediate 'qRelocInsn' request packets
2592 before the final result packet, to have GDB handle this relocation
2593 operation. If a packet supports this mechanism, its documentation will
2594 explicitly say so. See for example the above descriptions for the
2595 'QTStart' and 'QTDP' packets. The format of the request is:
2597 'qRelocInsn:FROM;TO'
2599 This requests GDB to copy instruction at address FROM to address
2600 TO, possibly adjusted so that executing the instruction at TO has
2601 the same effect as executing it at FROM. GDB writes the adjusted
2602 instruction to target memory starting at TO.
2605 'qRelocInsn:ADJUSTED_SIZE'
2606 Informs the stub the relocation is complete. The ADJUSTED_SIZE is
2607 the length in bytes of resulting relocated instruction sequence.
2609 A badly formed request was detected, or an error was encountered
2610 while relocating the instruction.
2613 File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol
2615 E.7 Host I/O Packets
2616 ====================
2618 The "Host I/O" packets allow GDB to perform I/O operations on the far
2619 side of a remote link. For example, Host I/O is used to upload and
2620 download files to a remote target with its own filesystem. Host I/O
2621 uses the same constant values and data structure layout as the
2622 target-initiated File-I/O protocol. However, the Host I/O packets are
2623 structured differently. The target-initiated protocol relies on target
2624 memory to store parameters and buffers. Host I/O requests are initiated
2625 by GDB, and the target's memory is not involved. *Note File-I/O Remote
2626 Protocol Extension::, for more details on the target-initiated protocol.
2628 The Host I/O request packets all encode a single operation along with
2629 its arguments. They have this format:
2631 'vFile:OPERATION: PARAMETER...'
2632 OPERATION is the name of the particular request; the target should
2633 compare the entire packet name up to the second colon when checking
2634 for a supported operation. The format of PARAMETER depends on the
2635 operation. Numbers are always passed in hexadecimal. Negative
2636 numbers have an explicit minus sign (i.e. two's complement is not
2637 used). Strings (e.g. filenames) are encoded as a series of
2638 hexadecimal bytes. The last argument to a system call may be a
2639 buffer of escaped binary data (*note Binary Data::).
2641 The valid responses to Host I/O packets are:
2643 'F RESULT [, ERRNO] [; ATTACHMENT]'
2644 RESULT is the integer value returned by this operation, usually
2645 non-negative for success and -1 for errors. If an error has
2646 occured, ERRNO will be included in the result specifying a value
2647 defined by the File-I/O protocol (*note Errno Values::). For
2648 operations which return data, ATTACHMENT supplies the data as a
2649 binary buffer. Binary buffers in response packets are escaped in
2650 the normal way (*note Binary Data::). See the individual packet
2651 documentation for the interpretation of RESULT and ATTACHMENT.
2654 An empty response indicates that this operation is not recognized.
2656 These are the supported Host I/O operations:
2658 'vFile:open: FILENAME, FLAGS, MODE'
2659 Open a file at FILENAME and return a file descriptor for it, or
2660 return -1 if an error occurs. The FILENAME is a string, FLAGS is
2661 an integer indicating a mask of open flags (*note Open Flags::),
2662 and MODE is an integer indicating a mask of mode bits to use if the
2663 file is created (*note mode_t Values::). *Note open::, for details
2664 of the open flags and mode values.
2667 Close the open file corresponding to FD and return 0, or -1 if an
2670 'vFile:pread: FD, COUNT, OFFSET'
2671 Read data from the open file corresponding to FD. Up to COUNT
2672 bytes will be read from the file, starting at OFFSET relative to
2673 the start of the file. The target may read fewer bytes; common
2674 reasons include packet size limits and an end-of-file condition.
2675 The number of bytes read is returned. Zero should only be returned
2676 for a successful read at the end of the file, or if COUNT was zero.
2678 The data read should be returned as a binary attachment on success.
2679 If zero bytes were read, the response should include an empty
2680 binary attachment (i.e. a trailing semicolon). The return value is
2681 the number of target bytes read; the binary attachment may be
2682 longer if some characters were escaped.
2684 'vFile:pwrite: FD, OFFSET, DATA'
2685 Write DATA (a binary buffer) to the open file corresponding to FD.
2686 Start the write at OFFSET from the start of the file. Unlike many
2687 'write' system calls, there is no separate COUNT argument; the
2688 length of DATA in the packet is used. 'vFile:write' returns the
2689 number of bytes written, which may be shorter than the length of
2690 DATA, or -1 if an error occurred.
2692 'vFile:unlink: FILENAME'
2693 Delete the file at FILENAME on the target. Return 0, or -1 if an
2694 error occurs. The FILENAME is a string.
2696 'vFile:readlink: FILENAME'
2697 Read value of symbolic link FILENAME on the target. Return the
2698 number of bytes read, or -1 if an error occurs.
2700 The data read should be returned as a binary attachment on success.
2701 If zero bytes were read, the response should include an empty
2702 binary attachment (i.e. a trailing semicolon). The return value is
2703 the number of target bytes read; the binary attachment may be
2704 longer if some characters were escaped.
2707 File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol
2712 When a program on the remote target is running, GDB may attempt to
2713 interrupt it by sending a 'Ctrl-C', 'BREAK' or a 'BREAK' followed by
2714 'g', control of which is specified via GDB's 'interrupt-sequence'.
2716 The precise meaning of 'BREAK' is defined by the transport mechanism
2717 and may, in fact, be undefined. GDB does not currently define a 'BREAK'
2718 mechanism for any of the network interfaces except for TCP, in which
2719 case GDB sends the 'telnet' BREAK sequence.
2721 'Ctrl-C', on the other hand, is defined and implemented for all
2722 transport mechanisms. It is represented by sending the single byte
2723 '0x03' without any of the usual packet overhead described in the
2724 Overview section (*note Overview::). When a '0x03' byte is transmitted
2725 as part of a packet, it is considered to be packet data and does _not_
2726 represent an interrupt. E.g., an 'X' packet (*note X packet::), used
2727 for binary downloads, may include an unescaped '0x03' as part of its
2730 'BREAK' followed by 'g' is also known as Magic SysRq g. When Linux
2731 kernel receives this sequence from serial port, it stops execution and
2734 Stubs are not required to recognize these interrupt mechanisms and
2735 the precise meaning associated with receipt of the interrupt is
2736 implementation defined. If the target supports debugging of multiple
2737 threads and/or processes, it should attempt to interrupt all
2738 currently-executing threads and processes. If the stub is successful at
2739 interrupting the running program, it should send one of the stop reply
2740 packets (*note Stop Reply Packets::) to GDB as a result of successfully
2741 stopping the program in all-stop mode, and a stop reply for each stopped
2742 thread in non-stop mode. Interrupts received while the program is
2743 stopped are discarded.
2746 File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol
2748 E.9 Notification Packets
2749 ========================
2751 The GDB remote serial protocol includes "notifications", packets that
2752 require no acknowledgment. Both the GDB and the stub may send
2753 notifications (although the only notifications defined at present are
2754 sent by the stub). Notifications carry information without incurring
2755 the round-trip latency of an acknowledgment, and so are useful for
2756 low-impact communications where occasional packet loss is not a problem.
2758 A notification packet has the form '% DATA # CHECKSUM', where DATA is
2759 the content of the notification, and CHECKSUM is a checksum of DATA,
2760 computed and formatted as for ordinary GDB packets. A notification's
2761 DATA never contains '$', '%' or '#' characters. Upon receiving a
2762 notification, the recipient sends no '+' or '-' to acknowledge the
2763 notification's receipt or to report its corruption.
2765 Every notification's DATA begins with a name, which contains no colon
2766 characters, followed by a colon character.
2768 Recipients should silently ignore corrupted notifications and
2769 notifications they do not understand. Recipients should restart timeout
2770 periods on receipt of a well-formed notification, whether or not they
2773 Senders should only send the notifications described here when this
2774 protocol description specifies that they are permitted. In the future,
2775 we may extend the protocol to permit existing notifications in new
2776 contexts; this rule helps older senders avoid confusing newer
2779 (Older versions of GDB ignore bytes received until they see the '$'
2780 byte that begins an ordinary packet, so new stubs may transmit
2781 notifications without fear of confusing older clients. There are no
2782 notifications defined for GDB to send at the moment, but we assume that
2783 most older stubs would ignore them, as well.)
2785 Each notification is comprised of three parts:
2787 The notification packet is sent by the side that initiates the
2788 exchange (currently, only the stub does that), with EVENT carrying
2789 the specific information about the notification, and NAME
2790 specifying the name of the notification.
2792 The acknowledge sent by the other side, usually GDB, to acknowledge
2793 the exchange and request the event.
2795 The purpose of an asynchronous notification mechanism is to report to
2796 GDB that something interesting happened in the remote stub.
2798 The remote stub may send notification NAME:EVENT at any time, but GDB
2799 acknowledges the notification when appropriate. The notification event
2800 is pending before GDB acknowledges. Only one notification at a time may
2801 be pending; if additional events occur before GDB has acknowledged the
2802 previous notification, they must be queued by the stub for later
2803 synchronous transmission in response to ACK packets from GDB. Because
2804 the notification mechanism is unreliable, the stub is permitted to
2805 resend a notification if it believes GDB may not have received it.
2807 Specifically, notifications may appear when GDB is not otherwise
2808 reading input from the stub, or when GDB is expecting to read a normal
2809 synchronous response or a '+'/'-' acknowledgment to a packet it has
2810 sent. Notification packets are distinct from any other communication
2811 from the stub so there is no ambiguity.
2813 After receiving a notification, GDB shall acknowledge it by sending a
2814 ACK packet as a regular, synchronous request to the stub. Such
2815 acknowledgment is not required to happen immediately, as GDB is
2816 permitted to send other, unrelated packets to the stub first, which the
2817 stub should process normally.
2819 Upon receiving a ACK packet, if the stub has other queued events to
2820 report to GDB, it shall respond by sending a normal EVENT. GDB shall
2821 then send another ACK packet to solicit further responses; again, it is
2822 permitted to send other, unrelated packets as well which the stub should
2825 If the stub receives a ACK packet and there are no additional EVENT
2826 to report, the stub shall return an 'OK' response. At this point, GDB
2827 has finished processing a notification and the stub has completed
2828 sending any queued events. GDB won't accept any new notifications until
2829 the final 'OK' is received . If further notification events occur, the
2830 stub shall send a new notification, GDB shall accept the notification,
2831 and the process shall be repeated.
2833 The process of asynchronous notification can be illustrated by the
2835 <- %%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;
2838 <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;
2840 <- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;
2844 The following notifications are defined:
2846 NotificationAck Event Description
2848 Stop vStopped REPLY. The REPLY has the Report an asynchronous
2849 form of a stop reply, as stop event in non-stop
2850 described in *note Stop mode.
2851 Reply Packets::. Refer
2854 information on how these
2856 acknowledged by GDB.
2859 File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol
2861 E.10 Remote Protocol Support for Non-Stop Mode
2862 ==============================================
2864 GDB's remote protocol supports non-stop debugging of multi-threaded
2865 programs, as described in *note Non-Stop Mode::. If the stub supports
2866 non-stop mode, it should report that to GDB by including 'QNonStop+' in
2867 its 'qSupported' response (*note qSupported::).
2869 GDB typically sends a 'QNonStop' packet only when establishing a new
2870 connection with the stub. Entering non-stop mode does not alter the
2871 state of any currently-running threads, but targets must stop all
2872 threads in any already-attached processes when entering all-stop mode.
2873 GDB uses the '?' packet as necessary to probe the target state after a
2876 In non-stop mode, when an attached process encounters an event that
2877 would otherwise be reported with a stop reply, it uses the asynchronous
2878 notification mechanism (*note Notification Packets::) to inform GDB. In
2879 contrast to all-stop mode, where all threads in all processes are
2880 stopped when a stop reply is sent, in non-stop mode only the thread
2881 reporting the stop event is stopped. That is, when reporting a 'S' or
2882 'T' response to indicate completion of a step operation, hitting a
2883 breakpoint, or a fault, only the affected thread is stopped; any other
2884 still-running threads continue to run. When reporting a 'W' or 'X'
2885 response, all running threads belonging to other attached processes
2888 In non-stop mode, the target shall respond to the '?' packet as
2889 follows. First, any incomplete stop reply notification/'vStopped'
2890 sequence in progress is abandoned. The target must begin a new sequence
2891 reporting stop events for all stopped threads, whether or not it has
2892 previously reported those events to GDB. The first stop reply is sent
2893 as a synchronous reply to the '?' packet, and subsequent stop replies
2894 are sent as responses to 'vStopped' packets using the mechanism
2895 described above. The target must not send asynchronous stop reply
2896 notifications until the sequence is complete. If all threads are
2897 running when the target receives the '?' packet, or if the target is not
2898 attached to any process, it shall respond 'OK'.
2901 File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol
2903 E.11 Packet Acknowledgment
2904 ==========================
2906 By default, when either the host or the target machine receives a
2907 packet, the first response expected is an acknowledgment: either '+' (to
2908 indicate the package was received correctly) or '-' (to request
2909 retransmission). This mechanism allows the GDB remote protocol to
2910 operate over unreliable transport mechanisms, such as a serial line.
2912 In cases where the transport mechanism is itself reliable (such as a
2913 pipe or TCP connection), the '+'/'-' acknowledgments are redundant. It
2914 may be desirable to disable them in that case to reduce communication
2915 overhead, or for other reasons. This can be accomplished by means of
2916 the 'QStartNoAckMode' packet; *note QStartNoAckMode::.
2918 When in no-acknowledgment mode, neither the stub nor GDB shall send
2919 or expect '+'/'-' protocol acknowledgments. The packet and response
2920 format still includes the normal checksum, as described in *note
2921 Overview::, but the checksum may be ignored by the receiver.
2923 If the stub supports 'QStartNoAckMode' and prefers to operate in
2924 no-acknowledgment mode, it should report that to GDB by including
2925 'QStartNoAckMode+' in its response to 'qSupported'; *note qSupported::.
2926 If GDB also supports 'QStartNoAckMode' and it has not been disabled via
2927 the 'set remote noack-packet off' command (*note Remote
2928 Configuration::), GDB may then send a 'QStartNoAckMode' packet to the
2929 stub. Only then may the stub actually turn off packet acknowledgments.
2930 GDB sends a final '+' acknowledgment of the stub's 'OK' response, which
2931 can be safely ignored by the stub.
2933 Note that 'set remote noack-packet' command only affects negotiation
2934 between GDB and the stub when subsequent connections are made; it does
2935 not affect the protocol acknowledgment state for any current connection.
2936 Since '+'/'-' acknowledgments are enabled by default when a new
2937 connection is established, there is also no protocol request to
2938 re-enable the acknowledgments for the current connection, once disabled.
2941 File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol
2946 Example sequence of a target being re-started. Notice how the restart
2947 does not get any direct output:
2954 <- T001:1234123412341234
2957 Example sequence of a target being stepped by a single instruction:
2964 <- T001:1234123412341234
2972 File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol
2974 E.13 File-I/O Remote Protocol Extension
2975 =======================================
2979 * File-I/O Overview::
2981 * The F Request Packet::
2982 * The F Reply Packet::
2983 * The Ctrl-C Message::
2985 * List of Supported Calls::
2986 * Protocol-specific Representation of Datatypes::
2988 * File-I/O Examples::
2991 File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension
2993 E.13.1 File-I/O Overview
2994 ------------------------
2996 The "File I/O remote protocol extension" (short: File-I/O) allows the
2997 target to use the host's file system and console I/O to perform various
2998 system calls. System calls on the target system are translated into a
2999 remote protocol packet to the host system, which then performs the
3000 needed actions and returns a response packet to the target system. This
3001 simulates file system operations even on targets that lack file systems.
3003 The protocol is defined to be independent of both the host and target
3004 systems. It uses its own internal representation of datatypes and
3005 values. Both GDB and the target's GDB stub are responsible for
3006 translating the system-dependent value representations into the internal
3007 protocol representations when data is transmitted.
3009 The communication is synchronous. A system call is possible only
3010 when GDB is waiting for a response from the 'C', 'c', 'S' or 's'
3011 packets. While GDB handles the request for a system call, the target is
3012 stopped to allow deterministic access to the target's memory. Therefore
3013 File-I/O is not interruptible by target signals. On the other hand, it
3014 is possible to interrupt File-I/O by a user interrupt ('Ctrl-C') within
3017 The target's request to perform a host system call does not finish
3018 the latest 'C', 'c', 'S' or 's' action. That means, after finishing the
3019 system call, the target returns to continuing the previous activity
3020 (continue, step). No additional continue or step request from GDB is
3024 <- target requests 'system call X'
3025 target is stopped, GDB executes system call
3026 -> GDB returns result
3027 ... target continues, GDB returns to wait for the target
3028 <- target hits breakpoint and sends a Txx packet
3030 The protocol only supports I/O on the console and to regular files on
3031 the host file system. Character or block special devices, pipes, named
3032 pipes, sockets or any other communication method on the host system are
3033 not supported by this protocol.
3035 File I/O is not supported in non-stop mode.
3038 File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension
3040 E.13.2 Protocol Basics
3041 ----------------------
3043 The File-I/O protocol uses the 'F' packet as the request as well as
3044 reply packet. Since a File-I/O system call can only occur when GDB is
3045 waiting for a response from the continuing or stepping target, the
3046 File-I/O request is a reply that GDB has to expect as a result of a
3047 previous 'C', 'c', 'S' or 's' packet. This 'F' packet contains all
3048 information needed to allow GDB to call the appropriate host system
3051 * A unique identifier for the requested system call.
3053 * All parameters to the system call. Pointers are given as addresses
3054 in the target memory address space. Pointers to strings are given
3055 as pointer/length pair. Numerical values are given as they are.
3056 Numerical control flags are given in a protocol-specific
3059 At this point, GDB has to perform the following actions.
3061 * If the parameters include pointer values to data needed as input to
3062 a system call, GDB requests this data from the target with a
3063 standard 'm' packet request. This additional communication has to
3064 be expected by the target implementation and is handled as any
3067 * GDB translates all value from protocol representation to host
3068 representation as needed. Datatypes are coerced into the host
3071 * GDB calls the system call.
3073 * It then coerces datatypes back to protocol representation.
3075 * If the system call is expected to return data in buffer space
3076 specified by pointer parameters to the call, the data is
3077 transmitted to the target using a 'M' or 'X' packet. This packet
3078 has to be expected by the target implementation and is handled as
3079 any other 'M' or 'X' packet.
3081 Eventually GDB replies with another 'F' packet which contains all
3082 necessary information for the target to continue. This at least
3087 * 'errno', if has been changed by the system call.
3091 After having done the needed type and value coercion, the target
3092 continues the latest continue or step action.
3095 File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension
3097 E.13.3 The 'F' Request Packet
3098 -----------------------------
3100 The 'F' request packet has the following format:
3102 'FCALL-ID,PARAMETER...'
3104 CALL-ID is the identifier to indicate the host system call to be
3105 called. This is just the name of the function.
3107 PARAMETER... are the parameters to the system call. Parameters are
3108 hexadecimal integer values, either the actual values in case of
3109 scalar datatypes, pointers to target buffer space in case of
3110 compound datatypes and unspecified memory areas, or pointer/length
3111 pairs in case of string parameters. These are appended to the
3112 CALL-ID as a comma-delimited list. All values are transmitted in
3113 ASCII string representation, pointer/length pairs separated by a
3117 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
3119 E.13.4 The 'F' Reply Packet
3120 ---------------------------
3122 The 'F' reply packet has the following format:
3124 'FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
3126 RETCODE is the return code of the system call as hexadecimal value.
3128 ERRNO is the 'errno' set by the call, in protocol-specific
3129 representation. This parameter can be omitted if the call was
3132 CTRL-C FLAG is only sent if the user requested a break. In this
3133 case, ERRNO must be sent as well, even if the call was successful.
3134 The CTRL-C FLAG itself consists of the character 'C':
3138 or, if the call was interrupted before the host call has been
3143 assuming 4 is the protocol-specific representation of 'EINTR'.
3146 File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension
3148 E.13.5 The 'Ctrl-C' Message
3149 ---------------------------
3151 If the 'Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
3152 Packet::), the target should behave as if it had gotten a break message.
3153 The meaning for the target is "system call interrupted by 'SIGINT'".
3154 Consequentially, the target should actually stop (as with a break
3155 message) and return to GDB with a 'T02' packet.
3157 It's important for the target to know in which state the system call
3158 was interrupted. There are two possible cases:
3160 * The system call hasn't been performed on the host yet.
3162 * The system call on the host has been finished.
3164 These two states can be distinguished by the target by the value of
3165 the returned 'errno'. If it's the protocol representation of 'EINTR',
3166 the system call hasn't been performed. This is equivalent to the
3167 'EINTR' handling on POSIX systems. In any other case, the target may
3168 presume that the system call has been finished -- successfully or not --
3169 and should behave as if the break message arrived right after the system
3172 GDB must behave reliably. If the system call has not been called
3173 yet, GDB may send the 'F' reply immediately, setting 'EINTR' as 'errno'
3174 in the packet. If the system call on the host has been finished before
3175 the user requests a break, the full action must be finished by GDB.
3176 This requires sending 'M' or 'X' packets as necessary. The 'F' packet
3177 may only be sent when either nothing has happened or the full action has
3181 File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension
3186 By default and if not explicitly closed by the target system, the file
3187 descriptors 0, 1 and 2 are connected to the GDB console. Output on the
3188 GDB console is handled as any other file output operation ('write(1,
3189 ...)' or 'write(2, ...)'). Console input is handled by GDB so that
3190 after the target read request from file descriptor 0 all following
3191 typing is buffered until either one of the following conditions is met:
3193 * The user types 'Ctrl-c'. The behaviour is as explained above, and
3194 the 'read' system call is treated as finished.
3196 * The user presses <RET>. This is treated as end of input with a
3199 * The user types 'Ctrl-d'. This is treated as end of input. No
3200 trailing character (neither newline nor 'Ctrl-D') is appended to
3203 If the user has typed more characters than fit in the buffer given to
3204 the 'read' call, the trailing characters are buffered in GDB until
3205 either another 'read(0, ...)' is requested by the target, or debugging
3206 is stopped at the user's request.
3209 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
3211 E.13.7 List of Supported Calls
3212 ------------------------------
3229 File: gdb.info, Node: open, Next: close, Up: List of Supported Calls
3235 int open(const char *pathname, int flags);
3236 int open(const char *pathname, int flags, mode_t mode);
3239 'Fopen,PATHPTR/LEN,FLAGS,MODE'
3241 FLAGS is the bitwise 'OR' of the following values:
3244 If the file does not exist it will be created. The host rules
3245 apply as far as file ownership and time stamps are concerned.
3248 When used with 'O_CREAT', if the file already exists it is an
3249 error and open() fails.
3252 If the file already exists and the open mode allows writing
3253 ('O_RDWR' or 'O_WRONLY' is given) it will be truncated to zero
3257 The file is opened in append mode.
3260 The file is opened for reading only.
3263 The file is opened for writing only.
3266 The file is opened for reading and writing.
3268 Other bits are silently ignored.
3270 MODE is the bitwise 'OR' of the following values:
3273 User has read permission.
3276 User has write permission.
3279 Group has read permission.
3282 Group has write permission.
3285 Others have read permission.
3288 Others have write permission.
3290 Other bits are silently ignored.
3293 'open' returns the new file descriptor or -1 if an error occurred.
3298 PATHNAME already exists and 'O_CREAT' and 'O_EXCL' were used.
3301 PATHNAME refers to a directory.
3304 The requested access is not allowed.
3307 PATHNAME was too long.
3310 A directory component in PATHNAME does not exist.
3313 PATHNAME refers to a device, pipe, named pipe or socket.
3316 PATHNAME refers to a file on a read-only filesystem and write
3317 access was requested.
3320 PATHNAME is an invalid pointer value.
3323 No space on device to create the file.
3326 The process already has the maximum number of files open.
3329 The limit on the total number of files open on the system has
3333 The call was interrupted by the user.
3336 File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls
3348 'close' returns zero on success, or -1 if an error occurred.
3353 FD isn't a valid open file descriptor.
3356 The call was interrupted by the user.
3359 File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls
3365 int read(int fd, void *buf, unsigned int count);
3368 'Fread,FD,BUFPTR,COUNT'
3371 On success, the number of bytes read is returned. Zero indicates
3372 end of file. If count is zero, read returns zero as well. On
3373 error, -1 is returned.
3378 FD is not a valid file descriptor or is not open for reading.
3381 BUFPTR is an invalid pointer value.
3384 The call was interrupted by the user.
3387 File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls
3393 int write(int fd, const void *buf, unsigned int count);
3396 'Fwrite,FD,BUFPTR,COUNT'
3399 On success, the number of bytes written are returned. Zero
3400 indicates nothing was written. On error, -1 is returned.
3405 FD is not a valid file descriptor or is not open for writing.
3408 BUFPTR is an invalid pointer value.
3411 An attempt was made to write a file that exceeds the
3412 host-specific maximum file size allowed.
3415 No space on device to write the data.
3418 The call was interrupted by the user.
3421 File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls
3427 long lseek (int fd, long offset, int flag);
3430 'Flseek,FD,OFFSET,FLAG'
3435 The offset is set to OFFSET bytes.
3438 The offset is set to its current location plus OFFSET bytes.
3441 The offset is set to the size of the file plus OFFSET bytes.
3444 On success, the resulting unsigned offset in bytes from the
3445 beginning of the file is returned. Otherwise, a value of -1 is
3451 FD is not a valid open file descriptor.
3454 FD is associated with the GDB console.
3457 FLAG is not a proper value.
3460 The call was interrupted by the user.
3463 File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls
3469 int rename(const char *oldpath, const char *newpath);
3472 'Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
3475 On success, zero is returned. On error, -1 is returned.
3480 NEWPATH is an existing directory, but OLDPATH is not a
3484 NEWPATH is a non-empty directory.
3487 OLDPATH or NEWPATH is a directory that is in use by some
3491 An attempt was made to make a directory a subdirectory of
3495 A component used as a directory in OLDPATH or new path is not
3496 a directory. Or OLDPATH is a directory and NEWPATH exists but
3500 OLDPATHPTR or NEWPATHPTR are invalid pointer values.
3503 No access to the file or the path of the file.
3507 OLDPATH or NEWPATH was too long.
3510 A directory component in OLDPATH or NEWPATH does not exist.
3513 The file is on a read-only filesystem.
3516 The device containing the file has no room for the new
3520 The call was interrupted by the user.
3523 File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls
3529 int unlink(const char *pathname);
3532 'Funlink,PATHNAMEPTR/LEN'
3535 On success, zero is returned. On error, -1 is returned.
3540 No access to the file or the path of the file.
3543 The system does not allow unlinking of directories.
3546 The file PATHNAME cannot be unlinked because it's being used
3550 PATHNAMEPTR is an invalid pointer value.
3553 PATHNAME was too long.
3556 A directory component in PATHNAME does not exist.
3559 A component of the path is not a directory.
3562 The file is on a read-only filesystem.
3565 The call was interrupted by the user.
3568 File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls
3574 int stat(const char *pathname, struct stat *buf);
3575 int fstat(int fd, struct stat *buf);
3578 'Fstat,PATHNAMEPTR/LEN,BUFPTR'
3582 On success, zero is returned. On error, -1 is returned.
3587 FD is not a valid open file.
3590 A directory component in PATHNAME does not exist or the path
3594 A component of the path is not a directory.
3597 PATHNAMEPTR is an invalid pointer value.
3600 No access to the file or the path of the file.
3603 PATHNAME was too long.
3606 The call was interrupted by the user.
3609 File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls
3615 int gettimeofday(struct timeval *tv, void *tz);
3618 'Fgettimeofday,TVPTR,TZPTR'
3621 On success, 0 is returned, -1 otherwise.
3626 TZ is a non-NULL pointer.
3629 TVPTR and/or TZPTR is an invalid pointer value.
3632 File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls
3644 Returns 1 if FD refers to the GDB console, 0 otherwise.
3649 The call was interrupted by the user.
3651 Note that the 'isatty' call is treated as a special case: it returns
3652 1 to the target if the file descriptor is attached to the GDB console, 0
3653 otherwise. Implementing through system calls would require implementing
3654 'ioctl' and would be more complex than needed.
3657 File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls
3663 int system(const char *command);
3666 'Fsystem,COMMANDPTR/LEN'
3669 If LEN is zero, the return value indicates whether a shell is
3670 available. A zero return value indicates a shell is not available.
3671 For non-zero LEN, the value returned is -1 on error and the return
3672 status of the command otherwise. Only the exit status of the
3673 command is returned, which is extracted from the host's 'system'
3674 return value by calling 'WEXITSTATUS(retval)'. In case '/bin/sh'
3675 could not be executed, 127 is returned.
3680 The call was interrupted by the user.
3682 GDB takes over the full task of calling the necessary host calls to
3683 perform the 'system' call. The return value of 'system' on the host is
3684 simplified before it's returned to the target. Any termination signal
3685 information from the child process is discarded, and the return value
3686 consists entirely of the exit status of the called command.
3688 Due to security concerns, the 'system' call is by default refused by
3689 GDB. The user has to allow this call explicitly with the 'set remote
3690 system-call-allowed 1' command.
3692 'set remote system-call-allowed'
3693 Control whether to allow the 'system' calls in the File I/O
3694 protocol for the remote target. The default is zero (disabled).
3696 'show remote system-call-allowed'
3697 Show whether the 'system' calls are allowed in the File I/O
3701 File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension
3703 E.13.8 Protocol-specific Representation of Datatypes
3704 ----------------------------------------------------
3708 * Integral Datatypes::
3715 File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes
3720 The integral datatypes used in the system calls are 'int', 'unsigned
3721 int', 'long', 'unsigned long', 'mode_t', and 'time_t'.
3723 'int', 'unsigned int', 'mode_t' and 'time_t' are implemented as 32
3724 bit values in this protocol.
3726 'long' and 'unsigned long' are implemented as 64 bit types.
3728 *Note Limits::, for corresponding MIN and MAX values (similar to
3729 those in 'limits.h') to allow range checking on host and target.
3731 'time_t' datatypes are defined as seconds since the Epoch.
3733 All integral datatypes transferred as part of a memory read or write
3734 of a structured datatype e.g. a 'struct stat' have to be given in big
3738 File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes
3743 Pointers to target data are transmitted as they are. An exception is
3744 made for pointers to buffers for which the length isn't transmitted as
3745 part of the function call, namely strings. Strings are transmitted as a
3746 pointer/length pair, both as hex values, e.g.
3750 which is a pointer to data of length 18 bytes at position 0x1aaf. The
3751 length is defined as the full string length in bytes, including the
3752 trailing null byte. For example, the string '"hello world"' at address
3753 0x123456 is transmitted as
3758 File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes
3763 Structured data which is transferred using a memory read or write (for
3764 example, a 'struct stat') is expected to be in a protocol-specific
3765 format with all scalar multibyte datatypes being big endian.
3766 Translation to this representation needs to be done both by the target
3767 before the 'F' packet is sent, and by GDB before it transfers memory to
3768 the target. Transferred pointers to structured data should point to the
3769 already-coerced data at any time.
3772 File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes
3777 The buffer of type 'struct stat' used by the target and GDB is defined
3781 unsigned int st_dev; /* device */
3782 unsigned int st_ino; /* inode */
3783 mode_t st_mode; /* protection */
3784 unsigned int st_nlink; /* number of hard links */
3785 unsigned int st_uid; /* user ID of owner */
3786 unsigned int st_gid; /* group ID of owner */
3787 unsigned int st_rdev; /* device type (if inode device) */
3788 unsigned long st_size; /* total size, in bytes */
3789 unsigned long st_blksize; /* blocksize for filesystem I/O */
3790 unsigned long st_blocks; /* number of blocks allocated */
3791 time_t st_atime; /* time of last access */
3792 time_t st_mtime; /* time of last modification */
3793 time_t st_ctime; /* time of last change */
3796 The integral datatypes conform to the definitions given in the
3797 appropriate section (see *note Integral Datatypes::, for details) so
3798 this structure is of size 64 bytes.
3800 The values of several fields have a restricted meaning and/or range
3804 A value of 0 represents a file, 1 the console.
3807 No valid meaning for the target. Transmitted unchanged.
3810 Valid mode bits are described in *note Constants::. Any other bits
3811 have currently no meaning for the target.
3816 No valid meaning for the target. Transmitted unchanged.
3821 These values have a host and file system dependent accuracy.
3822 Especially on Windows hosts, the file system may not support exact
3825 The target gets a 'struct stat' of the above representation and is
3826 responsible for coercing it to the target representation before
3829 Note that due to size differences between the host, target, and
3830 protocol representations of 'struct stat' members, these members could
3831 eventually get truncated on the target.
3834 File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes
3839 The buffer of type 'struct timeval' used by the File-I/O protocol is
3843 time_t tv_sec; /* second */
3844 long tv_usec; /* microsecond */
3847 The integral datatypes conform to the definitions given in the
3848 appropriate section (see *note Integral Datatypes::, for details) so
3849 this structure is of size 8 bytes.
3852 File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension
3857 The following values are used for the constants inside of the protocol.
3858 GDB and target are responsible for translating these values before and
3859 after the call as needed.
3870 File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants
3875 All values are given in hexadecimal representation.
3886 File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants
3891 All values are given in octal representation.
3906 File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants
3911 All values are given in decimal representation.
3934 'EUNKNOWN' is used as a fallback error value if a host system returns
3935 any error value not in the list of supported error numbers.
3938 File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants
3948 File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants
3953 All values are given in decimal representation.
3958 LONG_MIN -9223372036854775808
3959 LONG_MAX 9223372036854775807
3960 ULONG_MAX 18446744073709551615
3963 File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension
3965 E.13.10 File-I/O Examples
3966 -------------------------
3968 Example sequence of a write call, file descriptor 3, buffer is at target
3969 address 0x1234, 6 bytes should be written:
3972 _request memory read from target_
3975 _return "6 bytes written"_
3978 Example sequence of a read call, file descriptor 3, buffer is at
3979 target address 0x1234, 6 bytes should be read:
3982 _request memory write to target_
3984 _return "6 bytes read"_
3987 Example sequence of a read call, call fails on the host due to
3988 invalid file descriptor ('EBADF'):
3993 Example sequence of a read call, user presses 'Ctrl-c' before syscall
4000 Example sequence of a read call, user presses 'Ctrl-c' after syscall
4008 File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol
4010 E.14 Library List Format
4011 ========================
4013 On some platforms, a dynamic loader (e.g. 'ld.so') runs in the same
4014 process as your application to manage libraries. In this case, GDB can
4015 use the loader's symbol table and normal memory operations to maintain a
4016 list of shared libraries. On other platforms, the operating system
4017 manages loaded libraries. GDB can not retrieve the list of currently
4018 loaded libraries through memory operations, so it uses the
4019 'qXfer:libraries:read' packet (*note qXfer library list read::) instead.
4020 The remote stub queries the target's operating system and reports which
4021 libraries are loaded.
4023 The 'qXfer:libraries:read' packet returns an XML document which lists
4024 loaded libraries and their offsets. Each library has an associated name
4025 and one or more segment or section base addresses, which report where
4026 the library was loaded in memory.
4028 For the common case of libraries that are fully linked binaries, the
4029 library should have a list of segments. If the target supports dynamic
4030 linking of a relocatable object file, its library XML element should
4031 instead include a list of allocated sections. The segment or section
4032 bases are start addresses, not relocation offsets; they do not depend on
4033 the library's link-time base addresses.
4035 GDB must be linked with the Expat library to support XML library
4036 lists. *Note Expat::.
4038 A simple memory map, with one loaded library relocated by a single
4039 offset, looks like this:
4042 <library name="/lib/libc.so.6">
4043 <segment address="0x10000000"/>
4047 Another simple memory map, with one loaded library with three
4048 allocated sections (.text, .data, .bss), looks like this:
4051 <library name="sharedlib.o">
4052 <section address="0x10000000"/>
4053 <section address="0x20000000"/>
4054 <section address="0x30000000"/>
4058 The format of a library list is described by this DTD:
4060 <!-- library-list: Root element with versioning -->
4061 <!ELEMENT library-list (library)*>
4062 <!ATTLIST library-list version CDATA #FIXED "1.0">
4063 <!ELEMENT library (segment*, section*)>
4064 <!ATTLIST library name CDATA #REQUIRED>
4065 <!ELEMENT segment EMPTY>
4066 <!ATTLIST segment address CDATA #REQUIRED>
4067 <!ELEMENT section EMPTY>
4068 <!ATTLIST section address CDATA #REQUIRED>
4070 In addition, segments and section descriptors cannot be mixed within
4071 a single library element, and you must supply at least one segment or
4072 section for each library.
4075 File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol
4077 E.15 Library List Format for SVR4 Targets
4078 =========================================
4080 On SVR4 platforms GDB can use the symbol table of a dynamic loader (e.g.
4081 'ld.so') and normal memory operations to maintain a list of shared
4082 libraries. Still a special library list provided by this packet is more
4083 efficient for the GDB remote protocol.
4085 The 'qXfer:libraries-svr4:read' packet returns an XML document which
4086 lists loaded libraries and their SVR4 linker parameters. For each
4087 library on SVR4 target, the following parameters are reported:
4089 - 'name', the absolute file name from the 'l_name' field of 'struct
4091 - 'lm' with address of 'struct link_map' used for TLS (Thread Local
4093 - 'l_addr', the displacement as read from the field 'l_addr' of
4094 'struct link_map'. For prelinked libraries this is not an absolute
4095 memory address. It is a displacement of absolute memory address
4096 against address the file was prelinked to during the library load.
4097 - 'l_ld', which is memory address of the 'PT_DYNAMIC' segment
4099 Additionally the single 'main-lm' attribute specifies address of
4100 'struct link_map' used for the main executable. This parameter is used
4101 for TLS access and its presence is optional.
4103 GDB must be linked with the Expat library to support XML SVR4 library
4104 lists. *Note Expat::.
4106 A simple memory map, with two loaded libraries (which do not use
4107 prelink), looks like this:
4109 <library-list-svr4 version="1.0" main-lm="0xe4f8f8">
4110 <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
4112 <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
4116 The format of an SVR4 library list is described by this DTD:
4118 <!-- library-list-svr4: Root element with versioning -->
4119 <!ELEMENT library-list-svr4 (library)*>
4120 <!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
4121 <!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
4122 <!ELEMENT library EMPTY>
4123 <!ATTLIST library name CDATA #REQUIRED>
4124 <!ATTLIST library lm CDATA #REQUIRED>
4125 <!ATTLIST library l_addr CDATA #REQUIRED>
4126 <!ATTLIST library l_ld CDATA #REQUIRED>
4129 File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol
4131 E.16 Memory Map Format
4132 ======================
4134 To be able to write into flash memory, GDB needs to obtain a memory map
4135 from the target. This section describes the format of the memory map.
4137 The memory map is obtained using the 'qXfer:memory-map:read' (*note
4138 qXfer memory map read::) packet and is an XML document that lists memory
4141 GDB must be linked with the Expat library to support XML memory maps.
4144 The top-level structure of the document is shown below:
4146 <?xml version="1.0"?>
4147 <!DOCTYPE memory-map
4148 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
4149 "http://sourceware.org/gdb/gdb-memory-map.dtd">
4154 Each region can be either:
4156 * A region of RAM starting at ADDR and extending for LENGTH bytes
4159 <memory type="ram" start="ADDR" length="LENGTH"/>
4161 * A region of read-only memory:
4163 <memory type="rom" start="ADDR" length="LENGTH"/>
4165 * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
4168 <memory type="flash" start="ADDR" length="LENGTH">
4169 <property name="blocksize">BLOCKSIZE</property>
4172 Regions must not overlap. GDB assumes that areas of memory not
4173 covered by the memory map are RAM, and uses the ordinary 'M' and 'X'
4174 packets to write to addresses in such ranges.
4176 The formal DTD for memory map format is given below:
4178 <!-- ................................................... -->
4179 <!-- Memory Map XML DTD ................................ -->
4180 <!-- File: memory-map.dtd .............................. -->
4181 <!-- .................................... .............. -->
4182 <!-- memory-map.dtd -->
4183 <!-- memory-map: Root element with versioning -->
4184 <!ELEMENT memory-map (memory | property)>
4185 <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
4186 <!ELEMENT memory (property)>
4187 <!-- memory: Specifies a memory region,
4188 and its type, or device. -->
4189 <!ATTLIST memory type CDATA #REQUIRED
4190 start CDATA #REQUIRED
4191 length CDATA #REQUIRED
4192 device CDATA #IMPLIED>
4193 <!-- property: Generic attribute tag -->
4194 <!ELEMENT property (#PCDATA | property)*>
4195 <!ATTLIST property name CDATA #REQUIRED>
4198 File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol
4200 E.17 Thread List Format
4201 =======================
4203 To efficiently update the list of threads and their attributes, GDB
4204 issues the 'qXfer:threads:read' packet (*note qXfer threads read::) and
4205 obtains the XML document with the following structure:
4207 <?xml version="1.0"?>
4209 <thread id="id" core="0">
4214 Each 'thread' element must have the 'id' attribute that identifies
4215 the thread (*note thread-id syntax::). The 'core' attribute, if
4216 present, specifies which processor core the thread was last executing
4217 on. The content of the of 'thread' element is interpreted as
4218 human-readable auxilliary information.
4221 File: gdb.info, Node: Traceframe Info Format, Next: Branch Trace Format, Prev: Thread List Format, Up: Remote Protocol
4223 E.18 Traceframe Info Format
4224 ===========================
4226 To be able to know which objects in the inferior can be examined when
4227 inspecting a tracepoint hit, GDB needs to obtain the list of memory
4228 ranges, registers and trace state variables that have been collected in
4231 This list is obtained using the 'qXfer:traceframe-info:read' (*note
4232 qXfer traceframe info read::) packet and is an XML document.
4234 GDB must be linked with the Expat library to support XML traceframe
4235 info discovery. *Note Expat::.
4237 The top-level structure of the document is shown below:
4239 <?xml version="1.0"?>
4240 <!DOCTYPE traceframe-info
4241 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
4242 "http://sourceware.org/gdb/gdb-traceframe-info.dtd">
4247 Each traceframe block can be either:
4249 * A region of collected memory starting at ADDR and extending for
4250 LENGTH bytes from there:
4252 <memory start="ADDR" length="LENGTH"/>
4254 * A block indicating trace state variable numbered NUMBER has been
4259 The formal DTD for the traceframe info format is given below:
4261 <!ELEMENT traceframe-info (memory | tvar)* >
4262 <!ATTLIST traceframe-info version CDATA #FIXED "1.0">
4264 <!ELEMENT memory EMPTY>
4265 <!ATTLIST memory start CDATA #REQUIRED
4266 length CDATA #REQUIRED>
4268 <!ATTLIST tvar id CDATA #REQUIRED>
4271 File: gdb.info, Node: Branch Trace Format, Prev: Traceframe Info Format, Up: Remote Protocol
4273 E.19 Branch Trace Format
4274 ========================
4276 In order to display the branch trace of an inferior thread, GDB needs to
4277 obtain the list of branches. This list is represented as list of
4278 sequential code blocks that are connected via branches. The code in
4279 each block has been executed sequentially.
4281 This list is obtained using the 'qXfer:btrace:read' (*note qXfer
4282 btrace read::) packet and is an XML document.
4284 GDB must be linked with the Expat library to support XML traceframe
4285 info discovery. *Note Expat::.
4287 The top-level structure of the document is shown below:
4289 <?xml version="1.0"?>
4291 PUBLIC "+//IDN gnu.org//DTD GDB Branch Trace V1.0//EN"
4292 "http://sourceware.org/gdb/gdb-btrace.dtd">
4297 * A block of sequentially executed instructions starting at BEGIN and
4300 <block begin="BEGIN" end="END"/>
4302 The formal DTD for the branch trace format is given below:
4304 <!ELEMENT btrace (block)* >
4305 <!ATTLIST btrace version CDATA #FIXED "1.0">
4307 <!ELEMENT block EMPTY>
4308 <!ATTLIST block begin CDATA #REQUIRED
4309 end CDATA #REQUIRED>
4312 File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top
4314 Appendix F The GDB Agent Expression Mechanism
4315 *********************************************
4317 In some applications, it is not feasible for the debugger to interrupt
4318 the program's execution long enough for the developer to learn anything
4319 helpful about its behavior. If the program's correctness depends on its
4320 real-time behavior, delays introduced by a debugger might cause the
4321 program to fail, even when the code itself is correct. It is useful to
4322 be able to observe the program's behavior without interrupting it.
4324 Using GDB's 'trace' and 'collect' commands, the user can specify
4325 locations in the program, and arbitrary expressions to evaluate when
4326 those locations are reached. Later, using the 'tfind' command, she can
4327 examine the values those expressions had when the program hit the trace
4328 points. The expressions may also denote objects in memory -- structures
4329 or arrays, for example -- whose values GDB should record; while visiting
4330 a particular tracepoint, the user may inspect those objects as if they
4331 were in memory at that moment. However, because GDB records these
4332 values without interacting with the user, it can do so quickly and
4333 unobtrusively, hopefully not disturbing the program's behavior.
4335 When GDB is debugging a remote target, the GDB "agent" code running
4336 on the target computes the values of the expressions itself. To avoid
4337 having a full symbolic expression evaluator on the agent, GDB translates
4338 expressions in the source language into a simpler bytecode language, and
4339 then sends the bytecode to the agent; the agent then executes the
4340 bytecode, and records the values for GDB to retrieve later.
4342 The bytecode language is simple; there are forty-odd opcodes, the
4343 bulk of which are the usual vocabulary of C operands (addition,
4344 subtraction, shifts, and so on) and various sizes of literals and memory
4345 reference operations. The bytecode interpreter operates strictly on
4346 machine-level values -- various sizes of integers and floating point
4347 numbers -- and requires no information about types or symbols; thus, the
4348 interpreter's internal data structures are simple, and each bytecode
4349 requires only a few native machine instructions to implement it. The
4350 interpreter is small, and strict limits on the memory and time required
4351 to evaluate an expression are easy to determine, making it suitable for
4352 use by the debugging agent in real-time applications.
4356 * General Bytecode Design:: Overview of the interpreter.
4357 * Bytecode Descriptions:: What each one does.
4358 * Using Agent Expressions:: How agent expressions fit into the big picture.
4359 * Varying Target Capabilities:: How to discover what the target can do.
4360 * Rationale:: Why we did it this way.
4363 File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions
4365 F.1 General Bytecode Design
4366 ===========================
4368 The agent represents bytecode expressions as an array of bytes. Each
4369 instruction is one byte long (thus the term "bytecode"). Some
4370 instructions are followed by operand bytes; for example, the 'goto'
4371 instruction is followed by a destination for the jump.
4373 The bytecode interpreter is a stack-based machine; most instructions
4374 pop their operands off the stack, perform some operation, and push the
4375 result back on the stack for the next instruction to consume. Each
4376 element of the stack may contain either a integer or a floating point
4377 value; these values are as many bits wide as the largest integer that
4378 can be directly manipulated in the source language. Stack elements
4379 carry no record of their type; bytecode could push a value as an
4380 integer, then pop it as a floating point value. However, GDB will not
4381 generate code which does this. In C, one might define the type of a
4382 stack element as follows:
4387 where 'LONGEST' and 'DOUBLEST' are 'typedef' names for the largest
4388 integer and floating point types on the machine.
4390 By the time the bytecode interpreter reaches the end of the
4391 expression, the value of the expression should be the only value left on
4392 the stack. For tracing applications, 'trace' bytecodes in the
4393 expression will have recorded the necessary data, and the value on the
4394 stack may be discarded. For other applications, like conditional
4395 breakpoints, the value may be useful.
4397 Separate from the stack, the interpreter has two registers:
4399 The address of the next bytecode to execute.
4402 The address of the start of the bytecode expression, necessary for
4403 interpreting the 'goto' and 'if_goto' instructions.
4405 Neither of these registers is directly visible to the bytecode language
4406 itself, but they are useful for defining the meanings of the bytecode
4409 There are no instructions to perform side effects on the running
4410 program, or call the program's functions; we assume that these
4411 expressions are only used for unobtrusive debugging, not for patching
4414 Most bytecode instructions do not distinguish between the various
4415 sizes of values, and operate on full-width values; the upper bits of the
4416 values are simply ignored, since they do not usually make a difference
4417 to the value computed. The exceptions to this rule are:
4419 memory reference instructions ('ref'N)
4420 There are distinct instructions to fetch different word sizes from
4421 memory. Once on the stack, however, the values are treated as
4422 full-size integers. They may need to be sign-extended; the 'ext'
4423 instruction exists for this purpose.
4425 the sign-extension instruction ('ext' N)
4426 These clearly need to know which portion of their operand is to be
4427 extended to occupy the full length of the word.
4429 If the interpreter is unable to evaluate an expression completely for
4430 some reason (a memory location is inaccessible, or a divisor is zero,
4431 for example), we say that interpretation "terminates with an error".
4432 This means that the problem is reported back to the interpreter's caller
4433 in some helpful way. In general, code using agent expressions should
4434 assume that they may attempt to divide by zero, fetch arbitrary memory
4435 locations, and misbehave in other ways.
4437 Even complicated C expressions compile to a few bytecode
4438 instructions; for example, the expression 'x + y * z' would typically
4439 produce code like the following, assuming that 'x' and 'y' live in
4440 registers, and 'z' is a global variable holding a 32-bit 'int':
4443 const32 address of z
4450 In detail, these mean:
4453 Push the value of register 1 (presumably holding 'x') onto the
4457 Push the value of register 2 (holding 'y').
4459 'const32 address of z'
4460 Push the address of 'z' onto the stack.
4463 Fetch a 32-bit word from the address at the top of the stack;
4464 replace the address on the stack with the value. Thus, we replace
4465 the address of 'z' with 'z''s value.
4468 Sign-extend the value on the top of the stack from 32 bits to full
4469 length. This is necessary because 'z' is a signed integer.
4472 Pop the top two numbers on the stack, multiply them, and push their
4473 product. Now the top of the stack contains the value of the
4477 Pop the top two numbers, add them, and push the sum. Now the top
4478 of the stack contains the value of 'x + y * z'.
4481 Stop executing; the value left on the stack top is the value to be
4485 File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions
4487 F.2 Bytecode Descriptions
4488 =========================
4490 Each bytecode description has the following form:
4492 'add' (0x02): A B => A+B
4494 Pop the top two stack items, A and B, as integers; push their sum,
4497 In this example, 'add' is the name of the bytecode, and '(0x02)' is
4498 the one-byte value used to encode the bytecode, in hexadecimal. The
4499 phrase "A B => A+B" shows the stack before and after the bytecode
4500 executes. Beforehand, the stack must contain at least two values, A and
4501 B; since the top of the stack is to the right, B is on the top of the
4502 stack, and A is underneath it. After execution, the bytecode will have
4503 popped A and B from the stack, and replaced them with a single value,
4504 A+B. There may be other values on the stack below those shown, but the
4505 bytecode affects only those shown.
4507 Here is another example:
4509 'const8' (0x22) N: => N
4510 Push the 8-bit integer constant N on the stack, without sign
4513 In this example, the bytecode 'const8' takes an operand N directly
4514 from the bytecode stream; the operand follows the 'const8' bytecode
4515 itself. We write any such operands immediately after the name of the
4516 bytecode, before the colon, and describe the exact encoding of the
4517 operand in the bytecode stream in the body of the bytecode description.
4519 For the 'const8' bytecode, there are no stack items given before the
4520 =>; this simply means that the bytecode consumes no values from the
4521 stack. If a bytecode consumes no values, or produces no values, the
4522 list on either side of the => may be empty.
4524 If a value is written as A, B, or N, then the bytecode treats it as
4525 an integer. If a value is written is ADDR, then the bytecode treats it
4528 We do not fully describe the floating point operations here; although
4529 this design can be extended in a clean way to handle floating point
4530 values, they are not of immediate interest to the customer, so we avoid
4531 describing them, to save time.
4535 Prefix for floating-point bytecodes. Not implemented yet.
4537 'add' (0x02): A B => A+B
4538 Pop two integers from the stack, and push their sum, as an integer.
4540 'sub' (0x03): A B => A-B
4541 Pop two integers from the stack, subtract the top value from the
4542 next-to-top value, and push the difference.
4544 'mul' (0x04): A B => A*B
4545 Pop two integers from the stack, multiply them, and push the
4546 product on the stack. Note that, when one multiplies two N-bit
4547 numbers yielding another N-bit number, it is irrelevant whether the
4548 numbers are signed or not; the results are the same.
4550 'div_signed' (0x05): A B => A/B
4551 Pop two signed integers from the stack; divide the next-to-top
4552 value by the top value, and push the quotient. If the divisor is
4553 zero, terminate with an error.
4555 'div_unsigned' (0x06): A B => A/B
4556 Pop two unsigned integers from the stack; divide the next-to-top
4557 value by the top value, and push the quotient. If the divisor is
4558 zero, terminate with an error.
4560 'rem_signed' (0x07): A B => A MODULO B
4561 Pop two signed integers from the stack; divide the next-to-top
4562 value by the top value, and push the remainder. If the divisor is
4563 zero, terminate with an error.
4565 'rem_unsigned' (0x08): A B => A MODULO B
4566 Pop two unsigned integers from the stack; divide the next-to-top
4567 value by the top value, and push the remainder. If the divisor is
4568 zero, terminate with an error.
4570 'lsh' (0x09): A B => A<<B
4571 Pop two integers from the stack; let A be the next-to-top value,
4572 and B be the top value. Shift A left by B bits, and push the
4575 'rsh_signed' (0x0a): A B => '(signed)'A>>B
4576 Pop two integers from the stack; let A be the next-to-top value,
4577 and B be the top value. Shift A right by B bits, inserting copies
4578 of the top bit at the high end, and push the result.
4580 'rsh_unsigned' (0x0b): A B => A>>B
4581 Pop two integers from the stack; let A be the next-to-top value,
4582 and B be the top value. Shift A right by B bits, inserting zero
4583 bits at the high end, and push the result.
4585 'log_not' (0x0e): A => !A
4586 Pop an integer from the stack; if it is zero, push the value one;
4587 otherwise, push the value zero.
4589 'bit_and' (0x0f): A B => A&B
4590 Pop two integers from the stack, and push their bitwise 'and'.
4592 'bit_or' (0x10): A B => A|B
4593 Pop two integers from the stack, and push their bitwise 'or'.
4595 'bit_xor' (0x11): A B => A^B
4596 Pop two integers from the stack, and push their bitwise
4599 'bit_not' (0x12): A => ~A
4600 Pop an integer from the stack, and push its bitwise complement.
4602 'equal' (0x13): A B => A=B
4603 Pop two integers from the stack; if they are equal, push the value
4604 one; otherwise, push the value zero.
4606 'less_signed' (0x14): A B => A<B
4607 Pop two signed integers from the stack; if the next-to-top value is
4608 less than the top value, push the value one; otherwise, push the
4611 'less_unsigned' (0x15): A B => A<B
4612 Pop two unsigned integers from the stack; if the next-to-top value
4613 is less than the top value, push the value one; otherwise, push the
4616 'ext' (0x16) N: A => A, sign-extended from N bits
4617 Pop an unsigned value from the stack; treating it as an N-bit
4618 twos-complement value, extend it to full length. This means that
4619 all bits to the left of bit N-1 (where the least significant bit is
4620 bit 0) are set to the value of bit N-1. Note that N may be larger
4621 than or equal to the width of the stack elements of the bytecode
4622 engine; in this case, the bytecode should have no effect.
4624 The number of source bits to preserve, N, is encoded as a single
4625 byte unsigned integer following the 'ext' bytecode.
4627 'zero_ext' (0x2a) N: A => A, zero-extended from N bits
4628 Pop an unsigned value from the stack; zero all but the bottom N
4629 bits. This means that all bits to the left of bit N-1 (where the
4630 least significant bit is bit 0) are set to the value of bit N-1.
4632 The number of source bits to preserve, N, is encoded as a single
4633 byte unsigned integer following the 'zero_ext' bytecode.
4635 'ref8' (0x17): ADDR => A
4636 'ref16' (0x18): ADDR => A
4637 'ref32' (0x19): ADDR => A
4638 'ref64' (0x1a): ADDR => A
4639 Pop an address ADDR from the stack. For bytecode 'ref'N, fetch an
4640 N-bit value from ADDR, using the natural target endianness. Push
4641 the fetched value as an unsigned integer.
4643 Note that ADDR may not be aligned in any particular way; the 'refN'
4644 bytecodes should operate correctly for any address.
4646 If attempting to access memory at ADDR would cause a processor
4647 exception of some sort, terminate with an error.
4649 'ref_float' (0x1b): ADDR => D
4650 'ref_double' (0x1c): ADDR => D
4651 'ref_long_double' (0x1d): ADDR => D
4652 'l_to_d' (0x1e): A => D
4653 'd_to_l' (0x1f): D => A
4654 Not implemented yet.
4656 'dup' (0x28): A => A A
4657 Push another copy of the stack's top element.
4659 'swap' (0x2b): A B => B A
4660 Exchange the top two items on the stack.
4663 Discard the top value on the stack.
4665 'pick' (0x32) N: A ... B => A ... B A
4666 Duplicate an item from the stack and push it on the top of the
4667 stack. N, a single byte, indicates the stack item to copy. If N
4668 is zero, this is the same as 'dup'; if N is one, it copies the item
4669 under the top item, etc. If N exceeds the number of items on the
4670 stack, terminate with an error.
4672 'rot' (0x33): A B C => C B A
4673 Rotate the top three items on the stack.
4675 'if_goto' (0x20) OFFSET: A =>
4676 Pop an integer off the stack; if it is non-zero, branch to the
4677 given offset in the bytecode string. Otherwise, continue to the
4678 next instruction in the bytecode stream. In other words, if A is
4679 non-zero, set the 'pc' register to 'start' + OFFSET. Thus, an
4680 offset of zero denotes the beginning of the expression.
4682 The OFFSET is stored as a sixteen-bit unsigned value, stored
4683 immediately following the 'if_goto' bytecode. It is always stored
4684 most significant byte first, regardless of the target's normal
4685 endianness. The offset is not guaranteed to fall at any particular
4686 alignment within the bytecode stream; thus, on machines where
4687 fetching a 16-bit on an unaligned address raises an exception, you
4688 should fetch the offset one byte at a time.
4690 'goto' (0x21) OFFSET: =>
4691 Branch unconditionally to OFFSET; in other words, set the 'pc'
4692 register to 'start' + OFFSET.
4694 The offset is stored in the same way as for the 'if_goto' bytecode.
4696 'const8' (0x22) N: => N
4697 'const16' (0x23) N: => N
4698 'const32' (0x24) N: => N
4699 'const64' (0x25) N: => N
4700 Push the integer constant N on the stack, without sign extension.
4701 To produce a small negative value, push a small twos-complement
4702 value, and then sign-extend it using the 'ext' bytecode.
4704 The constant N is stored in the appropriate number of bytes
4705 following the 'const'B bytecode. The constant N is always stored
4706 most significant byte first, regardless of the target's normal
4707 endianness. The constant is not guaranteed to fall at any
4708 particular alignment within the bytecode stream; thus, on machines
4709 where fetching a 16-bit on an unaligned address raises an
4710 exception, you should fetch N one byte at a time.
4712 'reg' (0x26) N: => A
4713 Push the value of register number N, without sign extension. The
4714 registers are numbered following GDB's conventions.
4716 The register number N is encoded as a 16-bit unsigned integer
4717 immediately following the 'reg' bytecode. It is always stored most
4718 significant byte first, regardless of the target's normal
4719 endianness. The register number is not guaranteed to fall at any
4720 particular alignment within the bytecode stream; thus, on machines
4721 where fetching a 16-bit on an unaligned address raises an
4722 exception, you should fetch the register number one byte at a time.
4724 'getv' (0x2c) N: => V
4725 Push the value of trace state variable number N, without sign
4728 The variable number N is encoded as a 16-bit unsigned integer
4729 immediately following the 'getv' bytecode. It is always stored
4730 most significant byte first, regardless of the target's normal
4731 endianness. The variable number is not guaranteed to fall at any
4732 particular alignment within the bytecode stream; thus, on machines
4733 where fetching a 16-bit on an unaligned address raises an
4734 exception, you should fetch the register number one byte at a time.
4736 'setv' (0x2d) N: V => V
4737 Set trace state variable number N to the value found on the top of
4738 the stack. The stack is unchanged, so that the value is readily
4739 available if the assignment is part of a larger expression. The
4740 handling of N is as described for 'getv'.
4742 'trace' (0x0c): ADDR SIZE =>
4743 Record the contents of the SIZE bytes at ADDR in a trace buffer,
4744 for later retrieval by GDB.
4746 'trace_quick' (0x0d) SIZE: ADDR => ADDR
4747 Record the contents of the SIZE bytes at ADDR in a trace buffer,
4748 for later retrieval by GDB. SIZE is a single byte unsigned integer
4749 following the 'trace' opcode.
4751 This bytecode is equivalent to the sequence 'dup const8 SIZE
4752 trace', but we provide it anyway to save space in bytecode strings.
4754 'trace16' (0x30) SIZE: ADDR => ADDR
4755 Identical to trace_quick, except that SIZE is a 16-bit big-endian
4756 unsigned integer, not a single byte. This should probably have
4757 been named 'trace_quick16', for consistency.
4759 'tracev' (0x2e) N: => A
4760 Record the value of trace state variable number N in the trace
4761 buffer. The handling of N is as described for 'getv'.
4763 'tracenz' (0x2f) ADDR SIZE =>
4764 Record the bytes at ADDR in a trace buffer, for later retrieval by
4765 GDB. Stop at either the first zero byte, or when SIZE bytes have
4766 been recorded, whichever occurs first.
4768 'printf' (0x34) NUMARGS STRING =>
4769 Do a formatted print, in the style of the C function 'printf').
4770 The value of NUMARGS is the number of arguments to expect on the
4771 stack, while STRING is the format string, prefixed with a two-byte
4772 length. The last byte of the string must be zero, and is included
4773 in the length. The format string includes escaped sequences just
4774 as it appears in C source, so for instance the format string
4775 '"\t%d\n"' is six characters long, and the output will consist of a
4776 tab character, a decimal number, and a newline. At the top of the
4777 stack, above the values to be printed, this bytecode will pop a
4778 "function" and "channel". If the function is nonzero, then the
4779 target may treat it as a function and call it, passing the channel
4780 as a first argument, as with the C function 'fprintf'. If the
4781 function is zero, then the target may simply call a standard
4782 formatted print function of its choice. In all, this bytecode pops
4783 2 + NUMARGS stack elements, and pushes nothing.
4786 Stop executing bytecode; the result should be the top element of
4787 the stack. If the purpose of the expression was to compute an
4788 lvalue or a range of memory, then the next-to-top of the stack is
4789 the lvalue's address, and the top of the stack is the lvalue's
4793 File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions
4795 F.3 Using Agent Expressions
4796 ===========================
4798 Agent expressions can be used in several different ways by GDB, and the
4799 debugger can generate different bytecode sequences as appropriate.
4801 One possibility is to do expression evaluation on the target rather
4802 than the host, such as for the conditional of a conditional tracepoint.
4803 In such a case, GDB compiles the source expression into a bytecode
4804 sequence that simply gets values from registers or memory, does
4805 arithmetic, and returns a result.
4807 Another way to use agent expressions is for tracepoint data
4808 collection. GDB generates a different bytecode sequence for collection;
4809 in addition to bytecodes that do the calculation, GDB adds 'trace'
4810 bytecodes to save the pieces of memory that were used.
4812 * The user selects trace points in the program's code at which GDB
4813 should collect data.
4815 * The user specifies expressions to evaluate at each trace point.
4816 These expressions may denote objects in memory, in which case those
4817 objects' contents are recorded as the program runs, or computed
4818 values, in which case the values themselves are recorded.
4820 * GDB transmits the tracepoints and their associated expressions to
4821 the GDB agent, running on the debugging target.
4823 * The agent arranges to be notified when a trace point is hit.
4825 * When execution on the target reaches a trace point, the agent
4826 evaluates the expressions associated with that trace point, and
4827 records the resulting values and memory ranges.
4829 * Later, when the user selects a given trace event and inspects the
4830 objects and expression values recorded, GDB talks to the agent to
4831 retrieve recorded data as necessary to meet the user's requests.
4832 If the user asks to see an object whose contents have not been
4833 recorded, GDB reports an error.
4836 File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions
4838 F.4 Varying Target Capabilities
4839 ===============================
4841 Some targets don't support floating-point, and some would rather not
4842 have to deal with 'long long' operations. Also, different targets will
4843 have different stack sizes, and different bytecode buffer lengths.
4845 Thus, GDB needs a way to ask the target about itself. We haven't
4846 worked out the details yet, but in general, GDB should be able to send
4847 the target a packet asking it to describe itself. The reply should be a
4848 packet whose length is explicit, so we can add new information to the
4849 packet in future revisions of the agent, without confusing old versions
4850 of GDB, and it should contain a version number. It should contain at
4851 least the following information:
4853 * whether floating point is supported
4855 * whether 'long long' is supported
4857 * maximum acceptable size of bytecode stack
4859 * maximum acceptable length of bytecode expressions
4861 * which registers are actually available for collection
4863 * whether the target supports disabled tracepoints
4866 File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions
4871 Some of the design decisions apparent above are arguable.
4873 What about stack overflow/underflow?
4874 GDB should be able to query the target to discover its stack size.
4875 Given that information, GDB can determine at translation time
4876 whether a given expression will overflow the stack. But this spec
4877 isn't about what kinds of error-checking GDB ought to do.
4879 Why are you doing everything in LONGEST?
4881 Speed isn't important, but agent code size is; using LONGEST brings
4882 in a bunch of support code to do things like division, etc. So
4883 this is a serious concern.
4885 First, note that you don't need different bytecodes for different
4886 operand sizes. You can generate code without _knowing_ how big the
4887 stack elements actually are on the target. If the target only
4888 supports 32-bit ints, and you don't send any 64-bit bytecodes,
4889 everything just works. The observation here is that the MIPS and
4890 the Alpha have only fixed-size registers, and you can still get C's
4891 semantics even though most instructions only operate on full-sized
4892 words. You just need to make sure everything is properly
4893 sign-extended at the right times. So there is no need for 32- and
4894 64-bit variants of the bytecodes. Just implement everything using
4895 the largest size you support.
4897 GDB should certainly check to see what sizes the target supports,
4898 so the user can get an error earlier, rather than later. But this
4899 information is not necessary for correctness.
4901 Why don't you have '>' or '<=' operators?
4902 I want to keep the interpreter small, and we don't need them. We
4903 can combine the 'less_' opcodes with 'log_not', and swap the order
4904 of the operands, yielding all four asymmetrical comparison
4905 operators. For example, '(x <= y)' is '! (x > y)', which is '! (y
4908 Why do you have 'log_not'?
4909 Why do you have 'ext'?
4910 Why do you have 'zero_ext'?
4911 These are all easily synthesized from other instructions, but I
4912 expect them to be used frequently, and they're simple, so I include
4913 them to keep bytecode strings short.
4915 'log_not' is equivalent to 'const8 0 equal'; it's used in half the
4916 relational operators.
4918 'ext N' is equivalent to 'const8 S-N lsh const8 S-N rsh_signed',
4919 where S is the size of the stack elements; it follows 'refM' and
4920 REG bytecodes when the value should be signed. See the next
4923 'zero_ext N' is equivalent to 'constM MASK log_and'; it's used
4924 whenever we push the value of a register, because we can't assume
4925 the upper bits of the register aren't garbage.
4927 Why not have sign-extending variants of the 'ref' operators?
4928 Because that would double the number of 'ref' operators, and we
4929 need the 'ext' bytecode anyway for accessing bitfields.
4931 Why not have constant-address variants of the 'ref' operators?
4932 Because that would double the number of 'ref' operators again, and
4933 'const32 ADDRESS ref32' is only one byte longer.
4935 Why do the 'refN' operators have to support unaligned fetches?
4936 GDB will generate bytecode that fetches multi-byte values at
4937 unaligned addresses whenever the executable's debugging information
4938 tells it to. Furthermore, GDB does not know the value the pointer
4939 will have when GDB generates the bytecode, so it cannot determine
4940 whether a particular fetch will be aligned or not.
4942 In particular, structure bitfields may be several bytes long, but
4943 follow no alignment rules; members of packed structures are not
4944 necessarily aligned either.
4946 In general, there are many cases where unaligned references occur
4947 in correct C code, either at the programmer's explicit request, or
4948 at the compiler's discretion. Thus, it is simpler to make the GDB
4949 agent bytecodes work correctly in all circumstances than to make
4950 GDB guess in each case whether the compiler did the usual thing.
4952 Why are there no side-effecting operators?
4953 Because our current client doesn't want them? That's a cheap
4954 answer. I think the real answer is that I'm afraid of implementing
4955 function calls. We should re-visit this issue after the present
4956 contract is delivered.
4958 Why aren't the 'goto' ops PC-relative?
4959 The interpreter has the base address around anyway for PC bounds
4960 checking, and it seemed simpler.
4962 Why is there only one offset size for the 'goto' ops?
4963 Offsets are currently sixteen bits. I'm not happy with this
4966 Suppose we have multiple branch ops with different offset sizes.
4967 As I generate code left-to-right, all my jumps are forward jumps
4968 (there are no loops in expressions), so I never know the target
4969 when I emit the jump opcode. Thus, I have to either always assume
4970 the largest offset size, or do jump relaxation on the code after I
4971 generate it, which seems like a big waste of time.
4973 I can imagine a reasonable expression being longer than 256 bytes.
4974 I can't imagine one being longer than 64k. Thus, we need 16-bit
4975 offsets. This kind of reasoning is so bogus, but relaxation is
4978 The other approach would be to generate code right-to-left. Then
4979 I'd always know my offset size. That might be fun.
4981 Where is the function call bytecode?
4983 When we add side-effects, we should add this.
4985 Why does the 'reg' bytecode take a 16-bit register number?
4987 Intel's IA-64 architecture has 128 general-purpose registers, and
4988 128 floating-point registers, and I'm sure it has some random
4991 Why do we need 'trace' and 'trace_quick'?
4992 Because GDB needs to record all the memory contents and registers
4993 an expression touches. If the user wants to evaluate an expression
4994 'x->y->z', the agent must record the values of 'x' and 'x->y' as
4995 well as the value of 'x->y->z'.
4997 Don't the 'trace' bytecodes make the interpreter less general?
4998 They do mean that the interpreter contains special-purpose code,
4999 but that doesn't mean the interpreter can only be used for that
5000 purpose. If an expression doesn't use the 'trace' bytecodes, they
5001 don't get in its way.
5003 Why doesn't 'trace_quick' consume its arguments the way everything else does?
5004 In general, you do want your operators to consume their arguments;
5005 it's consistent, and generally reduces the amount of stack
5006 rearrangement necessary. However, 'trace_quick' is a kludge to
5007 save space; it only exists so we needn't write 'dup const8 SIZE
5008 trace' before every memory reference. Therefore, it's okay for it
5009 not to consume its arguments; it's meant for a specific context in
5010 which we know exactly what it should do with the stack. If we're
5011 going to have a kludge, it should be an effective kludge.
5013 Why does 'trace16' exist?
5014 That opcode was added by the customer that contracted Cygnus for
5015 the data tracing work. I personally think it is unnecessary;
5016 objects that large will be quite rare, so it is okay to use 'dup
5017 const16 SIZE trace' in those cases.
5019 Whatever we decide to do with 'trace16', we should at least leave
5020 opcode 0x30 reserved, to remain compatible with the customer who
5024 File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top
5026 Appendix G Target Descriptions
5027 ******************************
5029 One of the challenges of using GDB to debug embedded systems is that
5030 there are so many minor variants of each processor architecture in use.
5031 It is common practice for vendors to start with a standard processor
5032 core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
5033 adapt it to a particular market niche. Some architectures have hundreds
5034 of variants, available from dozens of vendors. This leads to a number
5037 * With so many different customized processors, it is difficult for
5038 the GDB maintainers to keep up with the changes.
5039 * Since individual variants may have short lifetimes or limited
5040 audiences, it may not be worthwhile to carry information about
5041 every variant in the GDB source tree.
5042 * When GDB does support the architecture of the embedded system at
5043 hand, the task of finding the correct architecture name to give the
5044 'set architecture' command can be error-prone.
5046 To address these problems, the GDB remote protocol allows a target
5047 system to not only identify itself to GDB, but to actually describe its
5048 own features. This lets GDB support processor variants it has never
5049 seen before -- to the extent that the descriptions are accurate, and
5050 that GDB understands them.
5052 GDB must be linked with the Expat library to support XML target
5053 descriptions. *Note Expat::.
5057 * Retrieving Descriptions:: How descriptions are fetched from a target.
5058 * Target Description Format:: The contents of a target description.
5059 * Predefined Target Types:: Standard types available for target
5061 * Standard Target Features:: Features GDB knows about.
5064 File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions
5066 G.1 Retrieving Descriptions
5067 ===========================
5069 Target descriptions can be read from the target automatically, or
5070 specified by the user manually. The default behavior is to read the
5071 description from the target. GDB retrieves it via the remote protocol
5072 using 'qXfer' requests (*note qXfer: General Query Packets.). The ANNEX
5073 in the 'qXfer' packet will be 'target.xml'. The contents of the
5074 'target.xml' annex are an XML document, of the form described in *note
5075 Target Description Format::.
5077 Alternatively, you can specify a file to read for the target
5078 description. If a file is set, the target will not be queried. The
5079 commands to specify a file are:
5081 'set tdesc filename PATH'
5082 Read the target description from PATH.
5084 'unset tdesc filename'
5085 Do not read the XML target description from a file. GDB will use
5086 the description supplied by the current target.
5088 'show tdesc filename'
5089 Show the filename to read for a target description, if any.
5092 File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions
5094 G.2 Target Description Format
5095 =============================
5097 A target description annex is an XML (http://www.w3.org/XML/) document
5098 which complies with the Document Type Definition provided in the GDB
5099 sources in 'gdb/features/gdb-target.dtd'. This means you can use
5100 generally available tools like 'xmllint' to check that your feature
5101 descriptions are well-formed and valid. However, to help people
5102 unfamiliar with XML write descriptions for their targets, we also
5103 describe the grammar here.
5105 Target descriptions can identify the architecture of the remote
5106 target and (for some architectures) provide information about custom
5107 register sets. They can also identify the OS ABI of the remote target.
5108 GDB can use this information to autoconfigure for your target, or to
5109 warn you if you connect to an unsupported target.
5111 Here is a simple target description:
5113 <target version="1.0">
5114 <architecture>i386:x86-64</architecture>
5117 This minimal description only says that the target uses the x86-64
5120 A target description has the following overall form, with [ ] marking
5121 optional elements and ... marking repeatable elements. The elements are
5122 explained further below.
5124 <?xml version="1.0"?>
5125 <!DOCTYPE target SYSTEM "gdb-target.dtd">
5126 <target version="1.0">
5133 The description is generally insensitive to whitespace and line breaks,
5134 under the usual common-sense rules. The XML version declaration and
5135 document type declaration can generally be omitted (GDB does not require
5136 them), but specifying them may be useful for XML validation tools. The
5137 'version' attribute for '<target>' may also be omitted, but we recommend
5138 including it; if future versions of GDB use an incompatible revision of
5139 'gdb-target.dtd', they will detect and report the version mismatch.
5144 It can sometimes be valuable to split a target description up into
5145 several different annexes, either for organizational purposes, or to
5146 share files between different possible target descriptions. You can
5147 divide a description into multiple files by replacing any element of the
5148 target description with an inclusion directive of the form:
5150 <xi:include href="DOCUMENT"/>
5152 When GDB encounters an element of this form, it will retrieve the named
5153 XML DOCUMENT, and replace the inclusion directive with the contents of
5154 that document. If the current description was read using 'qXfer', then
5155 so will be the included document; DOCUMENT will be interpreted as the
5156 name of an annex. If the current description was read from a file, GDB
5157 will look for DOCUMENT as a file in the same directory where it found
5158 the original description.
5163 An '<architecture>' element has this form:
5165 <architecture>ARCH</architecture>
5167 ARCH is one of the architectures from the set accepted by 'set
5168 architecture' (*note Specifying a Debugging Target: Targets.).
5173 This optional field was introduced in GDB version 7.0. Previous
5174 versions of GDB ignore it.
5176 An '<osabi>' element has this form:
5178 <osabi>ABI-NAME</osabi>
5180 ABI-NAME is an OS ABI name from the same selection accepted by 'set osabi'
5181 (*note Configuring the Current ABI: ABI.).
5183 G.2.4 Compatible Architecture
5184 -----------------------------
5186 This optional field was introduced in GDB version 7.0. Previous
5187 versions of GDB ignore it.
5189 A '<compatible>' element has this form:
5191 <compatible>ARCH</compatible>
5193 ARCH is one of the architectures from the set accepted by 'set
5194 architecture' (*note Specifying a Debugging Target: Targets.).
5196 A '<compatible>' element is used to specify that the target is able
5197 to run binaries in some other than the main target architecture given by
5198 the '<architecture>' element. For example, on the Cell Broadband
5199 Engine, the main architecture is 'powerpc:common' or 'powerpc:common64',
5200 but the system is able to run binaries in the 'spu' architecture as
5201 well. The way to describe this capability with '<compatible>' is as
5204 <architecture>powerpc:common</architecture>
5205 <compatible>spu</compatible>
5210 Each '<feature>' describes some logical portion of the target system.
5211 Features are currently used to describe available CPU registers and the
5212 types of their contents. A '<feature>' element has this form:
5214 <feature name="NAME">
5219 Each feature's name should be unique within the description. The name
5220 of a feature does not matter unless GDB has some special knowledge of
5221 the contents of that feature; if it does, the feature should have its
5222 standard name. *Note Standard Target Features::.
5227 Any register's value is a collection of bits which GDB must interpret.
5228 The default interpretation is a two's complement integer, but other
5229 types can be requested by name in the register description. Some
5230 predefined types are provided by GDB (*note Predefined Target Types::),
5231 and the description can define additional composite types.
5233 Each type element must have an 'id' attribute, which gives a unique
5234 (within the containing '<feature>') name to the type. Types must be
5235 defined before they are used.
5237 Some targets offer vector registers, which can be treated as arrays
5238 of scalar elements. These types are written as '<vector>' elements,
5239 specifying the array element type, TYPE, and the number of elements,
5242 <vector id="ID" type="TYPE" count="COUNT"/>
5244 If a register's value is usefully viewed in multiple ways, define it
5245 with a union type containing the useful representations. The '<union>'
5246 element contains one or more '<field>' elements, each of which has a
5250 <field name="NAME" type="TYPE"/>
5254 If a register's value is composed from several separate values,
5255 define it with a structure type. There are two forms of the '<struct>'
5256 element; a '<struct>' element must either contain only bitfields or
5257 contain no bitfields. If the structure contains only bitfields, its
5258 total size in bytes must be specified, each bitfield must have an
5259 explicit start and end, and bitfields are automatically assigned an
5260 integer type. The field's START should be less than or equal to its
5261 END, and zero represents the least significant bit.
5263 <struct id="ID" size="SIZE">
5264 <field name="NAME" start="START" end="END"/>
5268 If the structure contains no bitfields, then each field has an
5269 explicit type, and no implicit padding is added.
5272 <field name="NAME" type="TYPE"/>
5276 If a register's value is a series of single-bit flags, define it with
5277 a flags type. The '<flags>' element has an explicit SIZE and contains
5278 one or more '<field>' elements. Each field has a NAME, a START, and an
5279 END. Only single-bit flags are supported.
5281 <flags id="ID" size="SIZE">
5282 <field name="NAME" start="START" end="END"/>
5289 Each register is represented as an element with this form:
5294 [save-restore="SAVE-RESTORE"]
5298 The components are as follows:
5301 The register's name; it must be unique within the target
5305 The register's size, in bits.
5308 The register's number. If omitted, a register's number is one
5309 greater than that of the previous register (either in the current
5310 feature or in a preceding feature); the first register in the
5311 target description defaults to zero. This register number is used
5312 to read or write the register; e.g. it is used in the remote 'p'
5313 and 'P' packets, and registers appear in the 'g' and 'G' packets in
5314 order of increasing register number.
5317 Whether the register should be preserved across inferior function
5318 calls; this must be either 'yes' or 'no'. The default is 'yes',
5319 which is appropriate for most registers except for some system
5320 control registers; this is not related to the target's ABI.
5323 The type of the register. It may be a predefined type, a type
5324 defined in the current feature, or one of the special types 'int'
5325 and 'float'. 'int' is an integer type of the correct size for
5326 BITSIZE, and 'float' is a floating point type (in the
5327 architecture's normal floating point format) of the correct size
5328 for BITSIZE. The default is 'int'.
5331 The register group to which this register belongs. It must be
5332 either 'general', 'float', or 'vector'. If no GROUP is specified,
5333 GDB will not display the register in 'info registers'.
5336 File: gdb.info, Node: Predefined Target Types, Next: Standard Target Features, Prev: Target Description Format, Up: Target Descriptions
5338 G.3 Predefined Target Types
5339 ===========================
5341 Type definitions in the self-description can build up composite types
5342 from basic building blocks, but can not define fundamental types.
5343 Instead, standard identifiers are provided by GDB for the fundamental
5344 types. The currently supported types are:
5351 Signed integer types holding the specified number of bits.
5358 Unsigned integer types holding the specified number of bits.
5362 Pointers to unspecified code and data. The program counter and any
5363 dedicated return address register may be marked as code pointers;
5364 printing a code pointer converts it into a symbolic address. The
5365 stack pointer and any dedicated address registers may be marked as
5369 Single precision IEEE floating point.
5372 Double precision IEEE floating point.
5375 The 12-byte extended precision format used by ARM FPA registers.
5378 The 10-byte extended precision format used by x87 registers.
5381 32bit EFLAGS register used by x86.
5384 32bit MXCSR register used by x86.
5387 File: gdb.info, Node: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions
5389 G.4 Standard Target Features
5390 ============================
5392 A target description must contain either no registers or all the
5393 target's registers. If the description contains no registers, then GDB
5394 will assume a default register layout, selected based on the
5395 architecture. If the description contains any registers, the default
5396 layout will not be used; the standard registers must be described in the
5397 target description, in such a way that GDB can recognize them.
5399 This is accomplished by giving specific names to feature elements
5400 which contain standard registers. GDB will look for features with those
5401 names and verify that they contain the expected registers; if any known
5402 feature is missing required registers, or if any required feature is
5403 missing, GDB will reject the target description. You can add additional
5404 registers to any of the standard features -- GDB will display them just
5405 as if they were added to an unrecognized feature.
5407 This section lists the known features and their expected contents.
5408 Sample XML documents for these features are included in the GDB source
5409 tree, in the directory 'gdb/features'.
5411 Names recognized by GDB should include the name of the company or
5412 organization which selected the name, and the overall architecture to
5413 which the feature applies; so e.g. the feature containing ARM core
5414 registers is named 'org.gnu.gdb.arm.core'.
5416 The names of registers are not case sensitive for the purpose of
5417 recognizing standard features, but GDB will only display registers using
5418 the capitalization used in the description.
5422 * AArch64 Features::
5425 * MicroBlaze Features::
5428 * Nios II Features::
5429 * PowerPC Features::
5430 * S/390 and System z Features::
5434 File: gdb.info, Node: AArch64 Features, Next: ARM Features, Up: Standard Target Features
5436 G.4.1 AArch64 Features
5437 ----------------------
5439 The 'org.gnu.gdb.aarch64.core' feature is required for AArch64 targets.
5440 It should contain registers 'x0' through 'x30', 'sp', 'pc', and 'cpsr'.
5442 The 'org.gnu.gdb.aarch64.fpu' feature is optional. If present, it
5443 should contain registers 'v0' through 'v31', 'fpsr', and 'fpcr'.
5446 File: gdb.info, Node: ARM Features, Next: i386 Features, Prev: AArch64 Features, Up: Standard Target Features
5451 The 'org.gnu.gdb.arm.core' feature is required for non-M-profile ARM
5452 targets. It should contain registers 'r0' through 'r13', 'sp', 'lr',
5455 For M-profile targets (e.g. Cortex-M3), the 'org.gnu.gdb.arm.core'
5456 feature is replaced by 'org.gnu.gdb.arm.m-profile'. It should contain
5457 registers 'r0' through 'r13', 'sp', 'lr', 'pc', and 'xpsr'.
5459 The 'org.gnu.gdb.arm.fpa' feature is optional. If present, it should
5460 contain registers 'f0' through 'f7' and 'fps'.
5462 The 'org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, it
5463 should contain at least registers 'wR0' through 'wR15' and 'wCGR0'
5464 through 'wCGR3'. The 'wCID', 'wCon', 'wCSSF', and 'wCASF' registers are
5467 The 'org.gnu.gdb.arm.vfp' feature is optional. If present, it should
5468 contain at least registers 'd0' through 'd15'. If they are present,
5469 'd16' through 'd31' should also be included. GDB will synthesize the
5470 single-precision registers from halves of the double-precision
5473 The 'org.gnu.gdb.arm.neon' feature is optional. It does not need to
5474 contain registers; it instructs GDB to display the VFP double-precision
5475 registers as vectors and to synthesize the quad-precision registers from
5476 pairs of double-precision registers. If this feature is present,
5477 'org.gnu.gdb.arm.vfp' must also be present and include 32
5478 double-precision registers.
5481 File: gdb.info, Node: i386 Features, Next: MicroBlaze Features, Prev: ARM Features, Up: Standard Target Features
5486 The 'org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.
5487 It should describe the following registers:
5489 - 'eax' through 'edi' plus 'eip' for i386
5490 - 'rax' through 'r15' plus 'rip' for amd64
5491 - 'eflags', 'cs', 'ss', 'ds', 'es', 'fs', 'gs'
5492 - 'st0' through 'st7'
5493 - 'fctrl', 'fstat', 'ftag', 'fiseg', 'fioff', 'foseg', 'fooff' and
5496 The register sets may be different, depending on the target.
5498 The 'org.gnu.gdb.i386.sse' feature is optional. It should describe
5501 - 'xmm0' through 'xmm7' for i386
5502 - 'xmm0' through 'xmm15' for amd64
5505 The 'org.gnu.gdb.i386.avx' feature is optional and requires the
5506 'org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits
5509 - 'ymm0h' through 'ymm7h' for i386
5510 - 'ymm0h' through 'ymm15h' for amd64
5512 The 'org.gnu.gdb.i386.mpx' is an optional feature representing
5513 Intel(R) Memory Protection Extension (MPX). It should describe the
5514 following registers:
5516 - 'bnd0raw' through 'bnd3raw' for i386 and amd64.
5517 - 'bndcfgu' and 'bndstatus' for i386 and amd64.
5519 The 'org.gnu.gdb.i386.linux' feature is optional. It should describe
5520 a single register, 'orig_eax'.
5522 The 'org.gnu.gdb.i386.avx512' feature is optional and requires the
5523 'org.gnu.gdb.i386.avx' feature. It should describe additional XMM
5526 - 'xmm16h' through 'xmm31h', only valid for amd64.
5528 It should describe the upper 128 bits of additional YMM registers:
5530 - 'ymm16h' through 'ymm31h', only valid for amd64.
5532 It should describe the upper 256 bits of ZMM registers:
5534 - 'zmm0h' through 'zmm7h' for i386.
5535 - 'zmm0h' through 'zmm15h' for amd64.
5537 It should describe the additional ZMM registers:
5539 - 'zmm16h' through 'zmm31h', only valid for amd64.
5542 File: gdb.info, Node: MicroBlaze Features, Next: MIPS Features, Prev: i386 Features, Up: Standard Target Features
5544 G.4.4 MicroBlaze Features
5545 -------------------------
5547 The 'org.gnu.gdb.microblaze.core' feature is required for MicroBlaze
5548 targets. It should contain registers 'r0' through 'r31', 'rpc', 'rmsr',
5549 'rear', 'resr', 'rfsr', 'rbtr', 'rpvr', 'rpvr1' through 'rpvr11',
5550 'redr', 'rpid', 'rzpr', 'rtlbx', 'rtlbsx', 'rtlblo', and 'rtlbhi'.
5552 The 'org.gnu.gdb.microblaze.stack-protect' feature is optional. If
5553 present, it should contain registers 'rshr' and 'rslr'
5556 File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: MicroBlaze Features, Up: Standard Target Features
5561 The 'org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It
5562 should contain registers 'r0' through 'r31', 'lo', 'hi', and 'pc'. They
5563 may be 32-bit or 64-bit depending on the target.
5565 The 'org.gnu.gdb.mips.cp0' feature is also required. It should
5566 contain at least the 'status', 'badvaddr', and 'cause' registers. They
5567 may be 32-bit or 64-bit depending on the target.
5569 The 'org.gnu.gdb.mips.fpu' feature is currently required, though it
5570 may be optional in a future version of GDB. It should contain registers
5571 'f0' through 'f31', 'fcsr', and 'fir'. They may be 32-bit or 64-bit
5572 depending on the target.
5574 The 'org.gnu.gdb.mips.dsp' feature is optional. It should contain
5575 registers 'hi1' through 'hi3', 'lo1' through 'lo3', and 'dspctl'. The
5576 'dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit
5577 depending on the target.
5579 The 'org.gnu.gdb.mips.linux' feature is optional. It should contain
5580 a single register, 'restart', which is used by the Linux kernel to
5581 control restartable syscalls.
5584 File: gdb.info, Node: M68K Features, Next: Nios II Features, Prev: MIPS Features, Up: Standard Target Features
5589 ''org.gnu.gdb.m68k.core''
5590 ''org.gnu.gdb.coldfire.core''
5591 ''org.gnu.gdb.fido.core''
5592 One of those features must be always present. The feature that is
5593 present determines which flavor of m68k is used. The feature that
5594 is present should contain registers 'd0' through 'd7', 'a0' through
5595 'a5', 'fp', 'sp', 'ps' and 'pc'.
5597 ''org.gnu.gdb.coldfire.fp''
5598 This feature is optional. If present, it should contain registers
5599 'fp0' through 'fp7', 'fpcontrol', 'fpstatus' and 'fpiaddr'.
5602 File: gdb.info, Node: Nios II Features, Next: PowerPC Features, Prev: M68K Features, Up: Standard Target Features
5604 G.4.7 Nios II Features
5605 ----------------------
5607 The 'org.gnu.gdb.nios2.cpu' feature is required for Nios II targets. It
5608 should contain the 32 core registers ('zero', 'at', 'r2' through 'r23',
5609 'et' through 'ra'), 'pc', and the 16 control registers ('status' through
5613 File: gdb.info, Node: PowerPC Features, Next: S/390 and System z Features, Prev: Nios II Features, Up: Standard Target Features
5615 G.4.8 PowerPC Features
5616 ----------------------
5618 The 'org.gnu.gdb.power.core' feature is required for PowerPC targets.
5619 It should contain registers 'r0' through 'r31', 'pc', 'msr', 'cr', 'lr',
5620 'ctr', and 'xer'. They may be 32-bit or 64-bit depending on the target.
5622 The 'org.gnu.gdb.power.fpu' feature is optional. It should contain
5623 registers 'f0' through 'f31' and 'fpscr'.
5625 The 'org.gnu.gdb.power.altivec' feature is optional. It should
5626 contain registers 'vr0' through 'vr31', 'vscr', and 'vrsave'.
5628 The 'org.gnu.gdb.power.vsx' feature is optional. It should contain
5629 registers 'vs0h' through 'vs31h'. GDB will combine these registers with
5630 the floating point registers ('f0' through 'f31') and the altivec
5631 registers ('vr0' through 'vr31') to present the 128-bit wide registers
5632 'vs0' through 'vs63', the set of vector registers for POWER7.
5634 The 'org.gnu.gdb.power.spe' feature is optional. It should contain
5635 registers 'ev0h' through 'ev31h', 'acc', and 'spefscr'. SPE targets
5636 should provide 32-bit registers in 'org.gnu.gdb.power.core' and provide
5637 the upper halves in 'ev0h' through 'ev31h'. GDB will combine these to
5638 present registers 'ev0' through 'ev31' to the user.
5641 File: gdb.info, Node: S/390 and System z Features, Next: TIC6x Features, Prev: PowerPC Features, Up: Standard Target Features
5643 G.4.9 S/390 and System z Features
5644 ---------------------------------
5646 The 'org.gnu.gdb.s390.core' feature is required for S/390 and System z
5647 targets. It should contain the PSW and the 16 general registers. In
5648 particular, System z targets should provide the 64-bit registers 'pswm',
5649 'pswa', and 'r0' through 'r15'. S/390 targets should provide the 32-bit
5650 versions of these registers. A System z target that runs in 31-bit
5651 addressing mode should provide 32-bit versions of 'pswm' and 'pswa', as
5652 well as the general register's upper halves 'r0h' through 'r15h', and
5653 their lower halves 'r0l' through 'r15l'.
5655 The 'org.gnu.gdb.s390.fpr' feature is required. It should contain
5656 the 64-bit registers 'f0' through 'f15', and 'fpc'.
5658 The 'org.gnu.gdb.s390.acr' feature is required. It should contain
5659 the 32-bit registers 'acr0' through 'acr15'.
5661 The 'org.gnu.gdb.s390.linux' feature is optional. It should contain
5662 the register 'orig_r2', which is 64-bit wide on System z targets and
5663 32-bit otherwise. In addition, the feature may contain the 'last_break'
5664 register, whose width depends on the addressing mode, as well as the
5665 'system_call' register, which is always 32-bit wide.
5667 The 'org.gnu.gdb.s390.tdb' feature is optional. It should contain
5668 the 64-bit registers 'tdb0', 'tac', 'tct', 'atia', and 'tr0' through
5672 File: gdb.info, Node: TIC6x Features, Prev: S/390 and System z Features, Up: Standard Target Features
5674 G.4.10 TMS320C6x Features
5675 -------------------------
5677 The 'org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets.
5678 It should contain registers 'A0' through 'A15', registers 'B0' through
5679 'B15', 'CSR' and 'PC'.
5681 The 'org.gnu.gdb.tic6x.gp' feature is optional. It should contain
5682 registers 'A16' through 'A31' and 'B16' through 'B31'.
5684 The 'org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain
5685 registers 'TSR', 'ILC' and 'RILC'.
5688 File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top
5690 Appendix H Operating System Information
5691 ***************************************
5697 Users of GDB often wish to obtain information about the state of the
5698 operating system running on the target--for example the list of
5699 processes, or the list of open files. This section describes the
5700 mechanism that makes it possible. This mechanism is similar to the
5701 target features mechanism (*note Target Descriptions::), but focuses on
5702 a different aspect of target.
5704 Operating system information is retrived from the target via the
5705 remote protocol, using 'qXfer' requests (*note qXfer osdata read::).
5706 The object name in the request should be 'osdata', and the ANNEX
5707 identifies the data to be fetched.
5710 File: gdb.info, Node: Process list, Up: Operating System Information
5715 When requesting the process list, the ANNEX field in the 'qXfer' request
5716 should be 'processes'. The returned data is an XML document. The
5717 formal syntax of this document is defined in 'gdb/features/osdata.dtd'.
5719 An example document is:
5721 <?xml version="1.0"?>
5722 <!DOCTYPE target SYSTEM "osdata.dtd">
5723 <osdata type="processes">
5725 <column name="pid">1</column>
5726 <column name="user">root</column>
5727 <column name="command">/sbin/init</column>
5728 <column name="cores">1,2,3</column>
5732 Each item should include a column whose name is 'pid'. The value of
5733 that column should identify the process on the target. The 'user' and
5734 'command' columns are optional, and will be displayed by GDB. The
5735 'cores' column, if present, should contain a comma-separated list of
5736 cores that this process is running on. Target may provide additional
5737 columns, which GDB currently ignores.
5740 File: gdb.info, Node: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top
5742 Appendix I Trace File Format
5743 ****************************
5745 The trace file comes in three parts: a header, a textual description
5746 section, and a trace frame section with binary data.
5748 The header has the form '\x7fTRACE0\n'. The first byte is '0x7f' so
5749 as to indicate that the file contains binary data, while the '0' is a
5750 version number that may have different values in the future.
5752 The description section consists of multiple lines of ASCII text
5753 separated by newline characters ('0xa'). The lines may include a
5754 variety of optional descriptive or context-setting information, such as
5755 tracepoint definitions or register set size. GDB will ignore any line
5756 that it does not recognize. An empty line marks the end of this
5759 The trace frame section consists of a number of consecutive frames.
5760 Each frame begins with a two-byte tracepoint number, followed by a
5761 four-byte size giving the amount of data in the frame. The data in the
5762 frame consists of a number of blocks, each introduced by a character
5763 indicating its type (at least register, memory, and trace state
5764 variable). The data in this section is raw binary, not a hexadecimal or
5765 other encoding; its endianness matches the target's endianness.
5768 Register block. The number and ordering of bytes matches that of a
5769 'g' packet in the remote protocol. Note that these are the actual
5770 bytes, in target order and GDB register order, not a hexadecimal
5773 'M ADDRESS LENGTH BYTES...'
5774 Memory block. This is a contiguous block of memory, at the 8-byte
5775 address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH
5779 Trace state variable block. This records the 8-byte signed value
5780 VALUE of trace state variable numbered NUMBER.
5782 Future enhancements of the trace file format may include additional
5786 File: gdb.info, Node: Index Section Format, Next: Man Pages, Prev: Trace File Format, Up: Top
5788 Appendix J '.gdb_index' section format
5789 **************************************
5791 This section documents the index section that is created by 'save
5792 gdb-index' (*note Index Files::). The index section is DWARF-specific;
5793 some knowledge of DWARF is assumed in this description.
5795 The mapped index file format is designed to be directly 'mmap'able on
5796 any architecture. In most cases, a datum is represented using a
5797 little-endian 32-bit integer value, called an 'offset_type'. Big endian
5798 machines must byte-swap the values before using them. Exceptions to
5799 this rule are noted. The data is laid out such that alignment is always
5802 A mapped index consists of several areas, laid out in order.
5804 1. The file header. This is a sequence of values, of 'offset_type'
5805 unless otherwise noted:
5807 1. The version number, currently 8. Versions 1, 2 and 3 are
5808 obsolete. Version 4 uses a different hashing function from
5809 versions 5 and 6. Version 6 includes symbols for inlined
5810 functions, whereas versions 4 and 5 do not. Version 7 adds
5811 attributes to the CU indices in the symbol table. Version 8
5812 specifies that symbols from DWARF type units
5813 ('DW_TAG_type_unit') refer to the type unit's symbol table and
5814 not the compilation unit ('DW_TAG_comp_unit') using the type.
5816 GDB will only read version 4, 5, or 6 indices by specifying
5817 'set use-deprecated-index-sections on'. GDB has a workaround
5818 for potentially broken version 7 indices so it is currently
5819 not flagged as deprecated.
5821 2. The offset, from the start of the file, of the CU list.
5823 3. The offset, from the start of the file, of the types CU list.
5824 Note that this area can be empty, in which case this offset
5825 will be equal to the next offset.
5827 4. The offset, from the start of the file, of the address area.
5829 5. The offset, from the start of the file, of the symbol table.
5831 6. The offset, from the start of the file, of the constant pool.
5833 2. The CU list. This is a sequence of pairs of 64-bit little-endian
5834 values, sorted by the CU offset. The first element in each pair is
5835 the offset of a CU in the '.debug_info' section. The second
5836 element in each pair is the length of that CU. References to a CU
5837 elsewhere in the map are done using a CU index, which is just the
5838 0-based index into this table. Note that if there are type CUs,
5839 then conceptually CUs and type CUs form a single list for the
5840 purposes of CU indices.
5842 3. The types CU list. This is a sequence of triplets of 64-bit
5843 little-endian values. In a triplet, the first value is the CU
5844 offset, the second value is the type offset in the CU, and the
5845 third value is the type signature. The types CU list is not
5848 4. The address area. The address area consists of a sequence of
5849 address entries. Each address entry has three elements:
5851 1. The low address. This is a 64-bit little-endian value.
5853 2. The high address. This is a 64-bit little-endian value. Like
5854 'DW_AT_high_pc', the value is one byte beyond the end.
5856 3. The CU index. This is an 'offset_type' value.
5858 5. The symbol table. This is an open-addressed hash table. The size
5859 of the hash table is always a power of 2.
5861 Each slot in the hash table consists of a pair of 'offset_type'
5862 values. The first value is the offset of the symbol's name in the
5863 constant pool. The second value is the offset of the CU vector in
5866 If both values are 0, then this slot in the hash table is empty.
5867 This is ok because while 0 is a valid constant pool index, it
5868 cannot be a valid index for both a string and a CU vector.
5870 The hash value for a table entry is computed by applying an
5871 iterative hash function to the symbol's name. Starting with an
5872 initial value of 'r = 0', each (unsigned) character 'c' in the
5873 string is incorporated into the hash using the formula depending on
5877 The formula is 'r = r * 67 + c - 113'.
5880 The formula is 'r = r * 67 + tolower (c) - 113'.
5882 The terminating '\0' is not incorporated into the hash.
5884 The step size used in the hash table is computed via '((hash * 17)
5885 & (size - 1)) | 1', where 'hash' is the hash value, and 'size' is
5886 the size of the hash table. The step size is used to find the next
5887 candidate slot when handling a hash collision.
5889 The names of C++ symbols in the hash table are canonicalized. We
5890 don't currently have a simple description of the canonicalization
5891 algorithm; if you intend to create new index sections, you must
5894 6. The constant pool. This is simply a bunch of bytes. It is
5895 organized so that alignment is correct: CU vectors are stored
5896 first, followed by strings.
5898 A CU vector in the constant pool is a sequence of 'offset_type'
5899 values. The first value is the number of CU indices in the vector.
5900 Each subsequent value is the index and symbol attributes of a CU in
5901 the CU list. This element in the hash table is used to indicate
5902 which CUs define the symbol and how the symbol is used. See below
5903 for the format of each CU index+attributes entry.
5905 A string in the constant pool is zero-terminated.
5907 Attributes were added to CU index values in '.gdb_index' version 7.
5908 If a symbol has multiple uses within a CU then there is one CU
5909 index+attributes value for each use.
5911 The format of each CU index+attributes entry is as follows (bit 0 =
5915 This is the index of the CU in the CU list.
5917 These bits are reserved for future purposes and must be zero.
5919 The kind of the symbol in the CU.
5922 This value is reserved and should not be used. By reserving
5923 zero the full 'offset_type' value is backwards compatible with
5924 previous versions of the index.
5926 The symbol is a type.
5928 The symbol is a variable or an enum value.
5930 The symbol is a function.
5932 Any other kind of symbol.
5934 These values are reserved.
5937 This bit is zero if the value is global and one if it is static.
5939 The determination of whether a symbol is global or static is
5940 complicated. The authorative reference is the file 'dwarf2read.c'
5943 This pseudo-code describes the computation of a symbol's kind and
5944 global/static attributes in the index.
5946 is_external = get_attribute (die, DW_AT_external);
5947 language = get_attribute (cu_die, DW_AT_language);
5950 case DW_TAG_typedef:
5951 case DW_TAG_base_type:
5952 case DW_TAG_subrange_type:
5956 case DW_TAG_enumerator:
5958 is_static = (language != CPLUS && language != JAVA);
5960 case DW_TAG_subprogram:
5962 is_static = ! (is_external || language == ADA);
5964 case DW_TAG_constant:
5966 is_static = ! is_external;
5968 case DW_TAG_variable:
5970 is_static = ! is_external;
5972 case DW_TAG_namespace:
5976 case DW_TAG_class_type:
5977 case DW_TAG_interface_type:
5978 case DW_TAG_structure_type:
5979 case DW_TAG_union_type:
5980 case DW_TAG_enumeration_type:
5982 is_static = (language != CPLUS && language != JAVA);
5989 File: gdb.info, Node: Man Pages, Next: Copying, Prev: Index Section Format, Up: Top
5991 Appendix K Manual pages
5992 ***********************
5996 * gdb man:: The GNU Debugger man page
5997 * gdbserver man:: Remote Server for the GNU Debugger man page
5998 * gcore man:: Generate a core file of a running program
5999 * gdbinit man:: gdbinit scripts
6002 File: gdb.info, Node: gdb man, Next: gdbserver man, Up: Man Pages
6007 gdb ['-help'] ['-nh'] ['-nx'] ['-q'] ['-batch'] ['-cd='DIR] ['-f']
6008 ['-b' BPS] ['-tty='DEV] ['-s' SYMFILE] ['-e' PROG] ['-se' PROG]
6009 ['-c' CORE] ['-p' PROCID] ['-x' CMDS] ['-d' DIR] [PROG|PROG PROCID|PROG
6012 The purpose of a debugger such as GDB is to allow you to see what is
6013 going on "inside" another program while it executes - or what another
6014 program was doing at the moment it crashed.
6016 GDB can do four main kinds of things (plus other things in support of
6017 these) to help you catch bugs in the act:
6019 * Start your program, specifying anything that might affect its
6022 * Make your program stop on specified conditions.
6024 * Examine what has happened, when your program has stopped.
6026 * Change things in your program, so you can experiment with
6027 correcting the effects of one bug and go on to learn about another.
6029 You can use GDB to debug programs written in C, C++, Fortran and
6032 GDB is invoked with the shell command 'gdb'. Once started, it reads
6033 commands from the terminal until you tell it to exit with the GDB
6034 command 'quit'. You can get online help from GDB itself by using the
6037 You can run 'gdb' with no arguments or options; but the most usual
6038 way to start GDB is with one argument or two, specifying an executable
6039 program as the argument:
6043 You can also start with both an executable program and a core file
6048 You can, instead, specify a process ID as a second argument, if you
6049 want to debug a running process:
6054 would attach GDB to process '1234' (unless you also have a file named
6055 '1234'; GDB does check for a core file first). With option '-p' you can
6056 omit the PROGRAM filename.
6058 Here are some of the most frequently needed GDB commands:
6060 'break [FILE:]FUNCTIOP'
6061 Set a breakpoint at FUNCTION (in FILE).
6064 Start your program (with ARGLIST, if specified).
6067 Backtrace: display the program stack.
6070 Display the value of an expression.
6073 Continue running your program (after stopping, e.g. at a
6077 Execute next program line (after stopping); step _over_ any
6078 function calls in the line.
6080 'edit [FILE:]FUNCTION'
6081 look at the program line where it is presently stopped.
6083 'list [FILE:]FUNCTION'
6084 type the text of the program in the vicinity of where it is
6088 Execute next program line (after stopping); step _into_ any
6089 function calls in the line.
6092 Show information about GDB command NAME, or general information
6098 Any arguments other than options specify an executable file and core
6099 file (or process ID); that is, the first argument encountered with no
6100 associated option flag is equivalent to a '-se' option, and the second,
6101 if any, is equivalent to a '-c' option if it's the name of a file. Many
6102 options have both long and short forms; both are shown here. The long
6103 forms are also recognized if you truncate them, so long as enough of the
6104 option is present to be unambiguous. (If you prefer, you can flag
6105 option arguments with '+' rather than '-', though we illustrate the more
6108 All the options and command line arguments you give are processed in
6109 sequential order. The order makes a difference when the '-x' option is
6114 List all options, with brief explanations.
6118 Read symbol table from file FILE.
6121 Enable writing into executable and core files.
6125 Use file FILE as the executable file to execute when appropriate,
6126 and for examining pure data in conjunction with a core dump.
6129 Read symbol table from file FILE and use it as the executable file.
6133 Use file FILE as a core dump to examine.
6137 Execute GDB commands from file FILE.
6140 Execute given GDB COMMAND.
6142 '-directory=DIRECTORY'
6144 Add DIRECTORY to the path to search for source files.
6147 Do not execute commands from '~/.gdbinit'.
6151 Do not execute commands from any '.gdbinit' initialization files.
6155 "Quiet". Do not print the introductory and copyright messages.
6156 These messages are also suppressed in batch mode.
6159 Run in batch mode. Exit with status '0' after processing all the
6160 command files specified with '-x' (and '.gdbinit', if not
6161 inhibited). Exit with nonzero status if an error occurs in
6162 executing the GDB commands in the command files.
6164 Batch mode may be useful for running GDB as a filter, for example
6165 to download and run a program on another computer; in order to make
6166 this more useful, the message
6168 Program exited normally.
6170 (which is ordinarily issued whenever a program running under GDB
6171 control terminates) is not issued when running in batch mode.
6174 Run GDB using DIRECTORY as its working directory, instead of the
6179 Emacs sets this option when it runs GDB as a subprocess. It tells
6180 GDB to output the full file name and line number in a standard,
6181 recognizable fashion each time a stack frame is displayed (which
6182 includes each time the program stops). This recognizable format
6183 looks like two '\032' characters, followed by the file name, line
6184 number and character position separated by colons, and a newline.
6185 The Emacs-to-GDB interface program uses the two '\032' characters
6186 as a signal to display the source code for the frame.
6189 Set the line speed (baud rate or bits per second) of any serial
6190 interface used by GDB for remote debugging.
6193 Run using DEVICE for your program's standard input and output.
6196 File: gdb.info, Node: gdbserver man, Next: gcore man, Prev: gdb man, Up: Man Pages
6201 gdbserver COMM PROG [ARGS...]
6203 gdbserver -attach COMM PID
6205 gdbserver -multi COMM
6207 'gdbserver' is a program that allows you to run GDB on a different
6208 machine than the one which is running the program being debugged.
6210 Usage (server (target) side)
6211 ----------------------------
6213 First, you need to have a copy of the program you want to debug put onto
6214 the target system. The program can be stripped to save space if needed,
6215 as 'gdbserver' doesn't care about symbols. All symbol handling is taken
6216 care of by the GDB running on the host system.
6218 To use the server, you log on to the target system, and run the
6219 'gdbserver' program. You must tell it (a) how to communicate with GDB,
6220 (b) the name of your program, and (c) its arguments. The general syntax
6223 target> gdbserver COMM PROGRAM [ARGS ...]
6225 For example, using a serial port, you might say:
6227 target> gdbserver /dev/com1 emacs foo.txt
6229 This tells 'gdbserver' to debug emacs with an argument of foo.txt,
6230 and to communicate with GDB via '/dev/com1'. 'gdbserver' now waits
6231 patiently for the host GDB to communicate with it.
6233 To use a TCP connection, you could say:
6235 target> gdbserver host:2345 emacs foo.txt
6237 This says pretty much the same thing as the last example, except that
6238 we are going to communicate with the 'host' GDB via TCP. The 'host:2345'
6239 argument means that we are expecting to see a TCP connection from 'host'
6240 to local TCP port 2345. (Currently, the 'host' part is ignored.) You
6241 can choose any number you want for the port number as long as it does
6242 not conflict with any existing TCP ports on the target system. This
6243 same port number must be used in the host GDBs 'target remote' command,
6244 which will be described shortly. Note that if you chose a port number
6245 that conflicts with another service, 'gdbserver' will print an error
6248 'gdbserver' can also attach to running programs. This is
6249 accomplished via the '--attach' argument. The syntax is:
6251 target> gdbserver --attach COMM PID
6253 PID is the process ID of a currently running process. It isn't
6254 necessary to point 'gdbserver' at a binary for the running process.
6256 To start 'gdbserver' without supplying an initial command to run or
6257 process ID to attach, use the '--multi' command line option. In such
6258 case you should connect using 'target extended-remote' to start the
6259 program you want to debug.
6261 target> gdbserver --multi COMM
6266 You need an unstripped copy of the target program on your host system,
6267 since GDB needs to examine it's symbol tables and such. Start up GDB as
6268 you normally would, with the target program as the first argument. (You
6269 may need to use the '--baud' option if the serial line is running at
6270 anything except 9600 baud.) That is 'gdb TARGET-PROG', or 'gdb --baud
6271 BAUD TARGET-PROG'. After that, the only new command you need to know
6272 about is 'target remote' (or 'target extended-remote'). Its argument is
6273 either a device name (usually a serial device, like '/dev/ttyb'), or a
6274 'HOST:PORT' descriptor. For example:
6276 (gdb) target remote /dev/ttyb
6278 communicates with the server via serial line '/dev/ttyb', and:
6280 (gdb) target remote the-target:2345
6282 communicates via a TCP connection to port 2345 on host 'the-target',
6283 where you previously started up 'gdbserver' with the same port number.
6284 Note that for TCP connections, you must start up 'gdbserver' prior to
6285 using the 'target remote' command, otherwise you may get an error that
6286 looks something like 'Connection refused'.
6288 'gdbserver' can also debug multiple inferiors at once, described in
6289 *note Inferiors and Programs::. In such case use the 'extended-remote'
6290 GDB command variant:
6292 (gdb) target extended-remote the-target:2345
6294 The 'gdbserver' option '--multi' may or may not be used in such case.
6296 There are three different modes for invoking 'gdbserver':
6298 * Debug a specific program specified by its program name:
6300 gdbserver COMM PROG [ARGS...]
6302 The COMM parameter specifies how should the server communicate with
6303 GDB; it is either a device name (to use a serial line), a TCP port
6304 number (':1234'), or '-' or 'stdio' to use stdin/stdout of
6305 'gdbserver'. Specify the name of the program to debug in PROG.
6306 Any remaining arguments will be passed to the program verbatim.
6307 When the program exits, GDB will close the connection, and
6308 'gdbserver' will exit.
6310 * Debug a specific program by specifying the process ID of a running
6313 gdbserver --attach COMM PID
6315 The COMM parameter is as described above. Supply the process ID of
6316 a running program in PID; GDB will do everything else. Like with
6317 the previous mode, when the process PID exits, GDB will close the
6318 connection, and 'gdbserver' will exit.
6320 * Multi-process mode - debug more than one program/process:
6322 gdbserver --multi COMM
6324 In this mode, GDB can instruct 'gdbserver' which command(s) to run.
6325 Unlike the other 2 modes, GDB will not close the connection when a
6326 process being debugged exits, so you can debug several processes in
6329 In each of the modes you may specify these options:
6332 List all options, with brief explanations.
6335 This option causes 'gdbserver' to print its version number and
6339 'gdbserver' will attach to a running program. The syntax is:
6341 target> gdbserver --attach COMM PID
6343 PID is the process ID of a currently running process. It isn't
6344 necessary to point 'gdbserver' at a binary for the running process.
6347 To start 'gdbserver' without supplying an initial command to run or
6348 process ID to attach, use this command line option. Then you can
6349 connect using 'target extended-remote' and start the program you
6350 want to debug. The syntax is:
6352 target> gdbserver --multi COMM
6355 Instruct 'gdbserver' to display extra status information about the
6356 debugging process. This option is intended for 'gdbserver'
6357 development and for bug reports to the developers.
6360 Instruct 'gdbserver' to display remote protocol debug output. This
6361 option is intended for 'gdbserver' development and for bug reports
6364 '--debug-format=option1[,option2,...]'
6365 Instruct 'gdbserver' to include extra information in each line of
6366 debugging output. *Note Other Command-Line Arguments for
6370 Specify a wrapper to launch programs for debugging. The option
6371 should be followed by the name of the wrapper, then any
6372 command-line arguments to pass to the wrapper, then '--' indicating
6373 the end of the wrapper arguments.
6376 By default, 'gdbserver' keeps the listening TCP port open, so that
6377 additional connections are possible. However, if you start
6378 'gdbserver' with the '--once' option, it will stop listening for
6379 any further connection attempts after connecting to the first GDB
6383 File: gdb.info, Node: gcore man, Next: gdbinit man, Prev: gdbserver man, Up: Man Pages
6388 gcore [-o FILENAME] PID
6390 Generate a core dump of a running program with process ID PID.
6391 Produced file is equivalent to a kernel produced core file as if the
6392 process crashed (and if 'ulimit -c' were used to set up an appropriate
6393 core dump limit). Unlike after a crash, after 'gcore' the program
6394 remains running without any change.
6397 The optional argument FILENAME specifies the file name where to put
6398 the core dump. If not specified, the file name defaults to
6399 'core.PID', where PID is the running program process ID.
6402 File: gdb.info, Node: gdbinit man, Prev: gcore man, Up: Man Pages
6412 These files contain GDB commands to automatically execute during GDB
6413 startup. The lines of contents are canned sequences of commands,
6414 described in *note Sequences::.
6416 Please read more in *note Startup::.
6418 '(not enabled with --with-system-gdbinit during compilation)'
6419 System-wide initialization file. It is executed unless user
6420 specified GDB option '-nx' or '-n'. See more in *note System-wide
6424 User initialization file. It is executed unless user specified GDB
6425 options '-nx', '-n' or '-nh'.
6428 Initialization file for current directory. It may need to be
6429 enabled with GDB security command 'set auto-load local-gdbinit'.
6430 See more in *note Init File in the Current Directory::.
6433 File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Man Pages, Up: Top
6435 Appendix L GNU GENERAL PUBLIC LICENSE
6436 *************************************
6438 Version 3, 29 June 2007
6440 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
6442 Everyone is permitted to copy and distribute verbatim copies of this
6443 license document, but changing it is not allowed.
6448 The GNU General Public License is a free, copyleft license for software
6449 and other kinds of works.
6451 The licenses for most software and other practical works are designed
6452 to take away your freedom to share and change the works. By contrast,
6453 the GNU General Public License is intended to guarantee your freedom to
6454 share and change all versions of a program--to make sure it remains free
6455 software for all its users. We, the Free Software Foundation, use the
6456 GNU General Public License for most of our software; it applies also to
6457 any other work released this way by its authors. You can apply it to
6460 When we speak of free software, we are referring to freedom, not
6461 price. Our General Public Licenses are designed to make sure that you
6462 have the freedom to distribute copies of free software (and charge for
6463 them if you wish), that you receive source code or can get it if you
6464 want it, that you can change the software or use pieces of it in new
6465 free programs, and that you know you can do these things.
6467 To protect your rights, we need to prevent others from denying you
6468 these rights or asking you to surrender the rights. Therefore, you have
6469 certain responsibilities if you distribute copies of the software, or if
6470 you modify it: responsibilities to respect the freedom of others.
6472 For example, if you distribute copies of such a program, whether
6473 gratis or for a fee, you must pass on to the recipients the same
6474 freedoms that you received. You must make sure that they, too, receive
6475 or can get the source code. And you must show them these terms so they
6478 Developers that use the GNU GPL protect your rights with two steps:
6479 (1) assert copyright on the software, and (2) offer you this License
6480 giving you legal permission to copy, distribute and/or modify it.
6482 For the developers' and authors' protection, the GPL clearly explains
6483 that there is no warranty for this free software. For both users' and
6484 authors' sake, the GPL requires that modified versions be marked as
6485 changed, so that their problems will not be attributed erroneously to
6486 authors of previous versions.
6488 Some devices are designed to deny users access to install or run
6489 modified versions of the software inside them, although the manufacturer
6490 can do so. This is fundamentally incompatible with the aim of
6491 protecting users' freedom to change the software. The systematic
6492 pattern of such abuse occurs in the area of products for individuals to
6493 use, which is precisely where it is most unacceptable. Therefore, we
6494 have designed this version of the GPL to prohibit the practice for those
6495 products. If such problems arise substantially in other domains, we
6496 stand ready to extend this provision to those domains in future versions
6497 of the GPL, as needed to protect the freedom of users.
6499 Finally, every program is threatened constantly by software patents.
6500 States should not allow patents to restrict development and use of
6501 software on general-purpose computers, but in those that do, we wish to
6502 avoid the special danger that patents applied to a free program could
6503 make it effectively proprietary. To prevent this, the GPL assures that
6504 patents cannot be used to render the program non-free.
6506 The precise terms and conditions for copying, distribution and
6507 modification follow.
6509 TERMS AND CONDITIONS
6510 ====================
6514 "This License" refers to version 3 of the GNU General Public
6517 "Copyright" also means copyright-like laws that apply to other
6518 kinds of works, such as semiconductor masks.
6520 "The Program" refers to any copyrightable work licensed under this
6521 License. Each licensee is addressed as "you". "Licensees" and
6522 "recipients" may be individuals or organizations.
6524 To "modify" a work means to copy from or adapt all or part of the
6525 work in a fashion requiring copyright permission, other than the
6526 making of an exact copy. The resulting work is called a "modified
6527 version" of the earlier work or a work "based on" the earlier work.
6529 A "covered work" means either the unmodified Program or a work
6530 based on the Program.
6532 To "propagate" a work means to do anything with it that, without
6533 permission, would make you directly or secondarily liable for
6534 infringement under applicable copyright law, except executing it on
6535 a computer or modifying a private copy. Propagation includes
6536 copying, distribution (with or without modification), making
6537 available to the public, and in some countries other activities as
6540 To "convey" a work means any kind of propagation that enables other
6541 parties to make or receive copies. Mere interaction with a user
6542 through a computer network, with no transfer of a copy, is not
6545 An interactive user interface displays "Appropriate Legal Notices"
6546 to the extent that it includes a convenient and prominently visible
6547 feature that (1) displays an appropriate copyright notice, and (2)
6548 tells the user that there is no warranty for the work (except to
6549 the extent that warranties are provided), that licensees may convey
6550 the work under this License, and how to view a copy of this
6551 License. If the interface presents a list of user commands or
6552 options, such as a menu, a prominent item in the list meets this
6557 The "source code" for a work means the preferred form of the work
6558 for making modifications to it. "Object code" means any non-source
6561 A "Standard Interface" means an interface that either is an
6562 official standard defined by a recognized standards body, or, in
6563 the case of interfaces specified for a particular programming
6564 language, one that is widely used among developers working in that
6567 The "System Libraries" of an executable work include anything,
6568 other than the work as a whole, that (a) is included in the normal
6569 form of packaging a Major Component, but which is not part of that
6570 Major Component, and (b) serves only to enable use of the work with
6571 that Major Component, or to implement a Standard Interface for
6572 which an implementation is available to the public in source code
6573 form. A "Major Component", in this context, means a major
6574 essential component (kernel, window system, and so on) of the
6575 specific operating system (if any) on which the executable work
6576 runs, or a compiler used to produce the work, or an object code
6577 interpreter used to run it.
6579 The "Corresponding Source" for a work in object code form means all
6580 the source code needed to generate, install, and (for an executable
6581 work) run the object code and to modify the work, including scripts
6582 to control those activities. However, it does not include the
6583 work's System Libraries, or general-purpose tools or generally
6584 available free programs which are used unmodified in performing
6585 those activities but which are not part of the work. For example,
6586 Corresponding Source includes interface definition files associated
6587 with source files for the work, and the source code for shared
6588 libraries and dynamically linked subprograms that the work is
6589 specifically designed to require, such as by intimate data
6590 communication or control flow between those subprograms and other
6593 The Corresponding Source need not include anything that users can
6594 regenerate automatically from other parts of the Corresponding
6597 The Corresponding Source for a work in source code form is that
6600 2. Basic Permissions.
6602 All rights granted under this License are granted for the term of
6603 copyright on the Program, and are irrevocable provided the stated
6604 conditions are met. This License explicitly affirms your unlimited
6605 permission to run the unmodified Program. The output from running
6606 a covered work is covered by this License only if the output, given
6607 its content, constitutes a covered work. This License acknowledges
6608 your rights of fair use or other equivalent, as provided by
6611 You may make, run and propagate covered works that you do not
6612 convey, without conditions so long as your license otherwise
6613 remains in force. You may convey covered works to others for the
6614 sole purpose of having them make modifications exclusively for you,
6615 or provide you with facilities for running those works, provided
6616 that you comply with the terms of this License in conveying all
6617 material for which you do not control copyright. Those thus making
6618 or running the covered works for you must do so exclusively on your
6619 behalf, under your direction and control, on terms that prohibit
6620 them from making any copies of your copyrighted material outside
6621 their relationship with you.
6623 Conveying under any other circumstances is permitted solely under
6624 the conditions stated below. Sublicensing is not allowed; section
6625 10 makes it unnecessary.
6627 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
6629 No covered work shall be deemed part of an effective technological
6630 measure under any applicable law fulfilling obligations under
6631 article 11 of the WIPO copyright treaty adopted on 20 December
6632 1996, or similar laws prohibiting or restricting circumvention of
6635 When you convey a covered work, you waive any legal power to forbid
6636 circumvention of technological measures to the extent such
6637 circumvention is effected by exercising rights under this License
6638 with respect to the covered work, and you disclaim any intention to
6639 limit operation or modification of the work as a means of
6640 enforcing, against the work's users, your or third parties' legal
6641 rights to forbid circumvention of technological measures.
6643 4. Conveying Verbatim Copies.
6645 You may convey verbatim copies of the Program's source code as you
6646 receive it, in any medium, provided that you conspicuously and
6647 appropriately publish on each copy an appropriate copyright notice;
6648 keep intact all notices stating that this License and any
6649 non-permissive terms added in accord with section 7 apply to the
6650 code; keep intact all notices of the absence of any warranty; and
6651 give all recipients a copy of this License along with the Program.
6653 You may charge any price or no price for each copy that you convey,
6654 and you may offer support or warranty protection for a fee.
6656 5. Conveying Modified Source Versions.
6658 You may convey a work based on the Program, or the modifications to
6659 produce it from the Program, in the form of source code under the
6660 terms of section 4, provided that you also meet all of these
6663 a. The work must carry prominent notices stating that you
6664 modified it, and giving a relevant date.
6666 b. The work must carry prominent notices stating that it is
6667 released under this License and any conditions added under
6668 section 7. This requirement modifies the requirement in
6669 section 4 to "keep intact all notices".
6671 c. You must license the entire work, as a whole, under this
6672 License to anyone who comes into possession of a copy. This
6673 License will therefore apply, along with any applicable
6674 section 7 additional terms, to the whole of the work, and all
6675 its parts, regardless of how they are packaged. This License
6676 gives no permission to license the work in any other way, but
6677 it does not invalidate such permission if you have separately
6680 d. If the work has interactive user interfaces, each must display
6681 Appropriate Legal Notices; however, if the Program has
6682 interactive interfaces that do not display Appropriate Legal
6683 Notices, your work need not make them do so.
6685 A compilation of a covered work with other separate and independent
6686 works, which are not by their nature extensions of the covered
6687 work, and which are not combined with it such as to form a larger
6688 program, in or on a volume of a storage or distribution medium, is
6689 called an "aggregate" if the compilation and its resulting
6690 copyright are not used to limit the access or legal rights of the
6691 compilation's users beyond what the individual works permit.
6692 Inclusion of a covered work in an aggregate does not cause this
6693 License to apply to the other parts of the aggregate.
6695 6. Conveying Non-Source Forms.
6697 You may convey a covered work in object code form under the terms
6698 of sections 4 and 5, provided that you also convey the
6699 machine-readable Corresponding Source under the terms of this
6700 License, in one of these ways:
6702 a. Convey the object code in, or embodied in, a physical product
6703 (including a physical distribution medium), accompanied by the
6704 Corresponding Source fixed on a durable physical medium
6705 customarily used for software interchange.
6707 b. Convey the object code in, or embodied in, a physical product
6708 (including a physical distribution medium), accompanied by a
6709 written offer, valid for at least three years and valid for as
6710 long as you offer spare parts or customer support for that
6711 product model, to give anyone who possesses the object code
6712 either (1) a copy of the Corresponding Source for all the
6713 software in the product that is covered by this License, on a
6714 durable physical medium customarily used for software
6715 interchange, for a price no more than your reasonable cost of
6716 physically performing this conveying of source, or (2) access
6717 to copy the Corresponding Source from a network server at no
6720 c. Convey individual copies of the object code with a copy of the
6721 written offer to provide the Corresponding Source. This
6722 alternative is allowed only occasionally and noncommercially,
6723 and only if you received the object code with such an offer,
6724 in accord with subsection 6b.
6726 d. Convey the object code by offering access from a designated
6727 place (gratis or for a charge), and offer equivalent access to
6728 the Corresponding Source in the same way through the same
6729 place at no further charge. You need not require recipients
6730 to copy the Corresponding Source along with the object code.
6731 If the place to copy the object code is a network server, the
6732 Corresponding Source may be on a different server (operated by
6733 you or a third party) that supports equivalent copying
6734 facilities, provided you maintain clear directions next to the
6735 object code saying where to find the Corresponding Source.
6736 Regardless of what server hosts the Corresponding Source, you
6737 remain obligated to ensure that it is available for as long as
6738 needed to satisfy these requirements.
6740 e. Convey the object code using peer-to-peer transmission,
6741 provided you inform other peers where the object code and
6742 Corresponding Source of the work are being offered to the
6743 general public at no charge under subsection 6d.
6745 A separable portion of the object code, whose source code is
6746 excluded from the Corresponding Source as a System Library, need
6747 not be included in conveying the object code work.
6749 A "User Product" is either (1) a "consumer product", which means
6750 any tangible personal property which is normally used for personal,
6751 family, or household purposes, or (2) anything designed or sold for
6752 incorporation into a dwelling. In determining whether a product is
6753 a consumer product, doubtful cases shall be resolved in favor of
6754 coverage. For a particular product received by a particular user,
6755 "normally used" refers to a typical or common use of that class of
6756 product, regardless of the status of the particular user or of the
6757 way in which the particular user actually uses, or expects or is
6758 expected to use, the product. A product is a consumer product
6759 regardless of whether the product has substantial commercial,
6760 industrial or non-consumer uses, unless such uses represent the
6761 only significant mode of use of the product.
6763 "Installation Information" for a User Product means any methods,
6764 procedures, authorization keys, or other information required to
6765 install and execute modified versions of a covered work in that
6766 User Product from a modified version of its Corresponding Source.
6767 The information must suffice to ensure that the continued
6768 functioning of the modified object code is in no case prevented or
6769 interfered with solely because modification has been made.
6771 If you convey an object code work under this section in, or with,
6772 or specifically for use in, a User Product, and the conveying
6773 occurs as part of a transaction in which the right of possession
6774 and use of the User Product is transferred to the recipient in
6775 perpetuity or for a fixed term (regardless of how the transaction
6776 is characterized), the Corresponding Source conveyed under this
6777 section must be accompanied by the Installation Information. But
6778 this requirement does not apply if neither you nor any third party
6779 retains the ability to install modified object code on the User
6780 Product (for example, the work has been installed in ROM).
6782 The requirement to provide Installation Information does not
6783 include a requirement to continue to provide support service,
6784 warranty, or updates for a work that has been modified or installed
6785 by the recipient, or for the User Product in which it has been
6786 modified or installed. Access to a network may be denied when the
6787 modification itself materially and adversely affects the operation
6788 of the network or violates the rules and protocols for
6789 communication across the network.
6791 Corresponding Source conveyed, and Installation Information
6792 provided, in accord with this section must be in a format that is
6793 publicly documented (and with an implementation available to the
6794 public in source code form), and must require no special password
6795 or key for unpacking, reading or copying.
6797 7. Additional Terms.
6799 "Additional permissions" are terms that supplement the terms of
6800 this License by making exceptions from one or more of its
6801 conditions. Additional permissions that are applicable to the
6802 entire Program shall be treated as though they were included in
6803 this License, to the extent that they are valid under applicable
6804 law. If additional permissions apply only to part of the Program,
6805 that part may be used separately under those permissions, but the
6806 entire Program remains governed by this License without regard to
6807 the additional permissions.
6809 When you convey a copy of a covered work, you may at your option
6810 remove any additional permissions from that copy, or from any part
6811 of it. (Additional permissions may be written to require their own
6812 removal in certain cases when you modify the work.) You may place
6813 additional permissions on material, added by you to a covered work,
6814 for which you have or can give appropriate copyright permission.
6816 Notwithstanding any other provision of this License, for material
6817 you add to a covered work, you may (if authorized by the copyright
6818 holders of that material) supplement the terms of this License with
6821 a. Disclaiming warranty or limiting liability differently from
6822 the terms of sections 15 and 16 of this License; or
6824 b. Requiring preservation of specified reasonable legal notices
6825 or author attributions in that material or in the Appropriate
6826 Legal Notices displayed by works containing it; or
6828 c. Prohibiting misrepresentation of the origin of that material,
6829 or requiring that modified versions of such material be marked
6830 in reasonable ways as different from the original version; or
6832 d. Limiting the use for publicity purposes of names of licensors
6833 or authors of the material; or
6835 e. Declining to grant rights under trademark law for use of some
6836 trade names, trademarks, or service marks; or
6838 f. Requiring indemnification of licensors and authors of that
6839 material by anyone who conveys the material (or modified
6840 versions of it) with contractual assumptions of liability to
6841 the recipient, for any liability that these contractual
6842 assumptions directly impose on those licensors and authors.
6844 All other non-permissive additional terms are considered "further
6845 restrictions" within the meaning of section 10. If the Program as
6846 you received it, or any part of it, contains a notice stating that
6847 it is governed by this License along with a term that is a further
6848 restriction, you may remove that term. If a license document
6849 contains a further restriction but permits relicensing or conveying
6850 under this License, you may add to a covered work material governed
6851 by the terms of that license document, provided that the further
6852 restriction does not survive such relicensing or conveying.
6854 If you add terms to a covered work in accord with this section, you
6855 must place, in the relevant source files, a statement of the
6856 additional terms that apply to those files, or a notice indicating
6857 where to find the applicable terms.
6859 Additional terms, permissive or non-permissive, may be stated in
6860 the form of a separately written license, or stated as exceptions;
6861 the above requirements apply either way.
6865 You may not propagate or modify a covered work except as expressly
6866 provided under this License. Any attempt otherwise to propagate or
6867 modify it is void, and will automatically terminate your rights
6868 under this License (including any patent licenses granted under the
6869 third paragraph of section 11).
6871 However, if you cease all violation of this License, then your
6872 license from a particular copyright holder is reinstated (a)
6873 provisionally, unless and until the copyright holder explicitly and
6874 finally terminates your license, and (b) permanently, if the
6875 copyright holder fails to notify you of the violation by some
6876 reasonable means prior to 60 days after the cessation.
6878 Moreover, your license from a particular copyright holder is
6879 reinstated permanently if the copyright holder notifies you of the
6880 violation by some reasonable means, this is the first time you have
6881 received notice of violation of this License (for any work) from
6882 that copyright holder, and you cure the violation prior to 30 days
6883 after your receipt of the notice.
6885 Termination of your rights under this section does not terminate
6886 the licenses of parties who have received copies or rights from you
6887 under this License. If your rights have been terminated and not
6888 permanently reinstated, you do not qualify to receive new licenses
6889 for the same material under section 10.
6891 9. Acceptance Not Required for Having Copies.
6893 You are not required to accept this License in order to receive or
6894 run a copy of the Program. Ancillary propagation of a covered work
6895 occurring solely as a consequence of using peer-to-peer
6896 transmission to receive a copy likewise does not require
6897 acceptance. However, nothing other than this License grants you
6898 permission to propagate or modify any covered work. These actions
6899 infringe copyright if you do not accept this License. Therefore,
6900 by modifying or propagating a covered work, you indicate your
6901 acceptance of this License to do so.
6903 10. Automatic Licensing of Downstream Recipients.
6905 Each time you convey a covered work, the recipient automatically
6906 receives a license from the original licensors, to run, modify and
6907 propagate that work, subject to this License. You are not
6908 responsible for enforcing compliance by third parties with this
6911 An "entity transaction" is a transaction transferring control of an
6912 organization, or substantially all assets of one, or subdividing an
6913 organization, or merging organizations. If propagation of a
6914 covered work results from an entity transaction, each party to that
6915 transaction who receives a copy of the work also receives whatever
6916 licenses to the work the party's predecessor in interest had or
6917 could give under the previous paragraph, plus a right to possession
6918 of the Corresponding Source of the work from the predecessor in
6919 interest, if the predecessor has it or can get it with reasonable
6922 You may not impose any further restrictions on the exercise of the
6923 rights granted or affirmed under this License. For example, you
6924 may not impose a license fee, royalty, or other charge for exercise
6925 of rights granted under this License, and you may not initiate
6926 litigation (including a cross-claim or counterclaim in a lawsuit)
6927 alleging that any patent claim is infringed by making, using,
6928 selling, offering for sale, or importing the Program or any portion
6933 A "contributor" is a copyright holder who authorizes use under this
6934 License of the Program or a work on which the Program is based.
6935 The work thus licensed is called the contributor's "contributor
6938 A contributor's "essential patent claims" are all patent claims
6939 owned or controlled by the contributor, whether already acquired or
6940 hereafter acquired, that would be infringed by some manner,
6941 permitted by this License, of making, using, or selling its
6942 contributor version, but do not include claims that would be
6943 infringed only as a consequence of further modification of the
6944 contributor version. For purposes of this definition, "control"
6945 includes the right to grant patent sublicenses in a manner
6946 consistent with the requirements of this License.
6948 Each contributor grants you a non-exclusive, worldwide,
6949 royalty-free patent license under the contributor's essential
6950 patent claims, to make, use, sell, offer for sale, import and
6951 otherwise run, modify and propagate the contents of its contributor
6954 In the following three paragraphs, a "patent license" is any
6955 express agreement or commitment, however denominated, not to
6956 enforce a patent (such as an express permission to practice a
6957 patent or covenant not to sue for patent infringement). To "grant"
6958 such a patent license to a party means to make such an agreement or
6959 commitment not to enforce a patent against the party.
6961 If you convey a covered work, knowingly relying on a patent
6962 license, and the Corresponding Source of the work is not available
6963 for anyone to copy, free of charge and under the terms of this
6964 License, through a publicly available network server or other
6965 readily accessible means, then you must either (1) cause the
6966 Corresponding Source to be so available, or (2) arrange to deprive
6967 yourself of the benefit of the patent license for this particular
6968 work, or (3) arrange, in a manner consistent with the requirements
6969 of this License, to extend the patent license to downstream
6970 recipients. "Knowingly relying" means you have actual knowledge
6971 that, but for the patent license, your conveying the covered work
6972 in a country, or your recipient's use of the covered work in a
6973 country, would infringe one or more identifiable patents in that
6974 country that you have reason to believe are valid.
6976 If, pursuant to or in connection with a single transaction or
6977 arrangement, you convey, or propagate by procuring conveyance of, a
6978 covered work, and grant a patent license to some of the parties
6979 receiving the covered work authorizing them to use, propagate,
6980 modify or convey a specific copy of the covered work, then the
6981 patent license you grant is automatically extended to all
6982 recipients of the covered work and works based on it.
6984 A patent license is "discriminatory" if it does not include within
6985 the scope of its coverage, prohibits the exercise of, or is
6986 conditioned on the non-exercise of one or more of the rights that
6987 are specifically granted under this License. You may not convey a
6988 covered work if you are a party to an arrangement with a third
6989 party that is in the business of distributing software, under which
6990 you make payment to the third party based on the extent of your
6991 activity of conveying the work, and under which the third party
6992 grants, to any of the parties who would receive the covered work
6993 from you, a discriminatory patent license (a) in connection with
6994 copies of the covered work conveyed by you (or copies made from
6995 those copies), or (b) primarily for and in connection with specific
6996 products or compilations that contain the covered work, unless you
6997 entered into that arrangement, or that patent license was granted,
6998 prior to 28 March 2007.
7000 Nothing in this License shall be construed as excluding or limiting
7001 any implied license or other defenses to infringement that may
7002 otherwise be available to you under applicable patent law.
7004 12. No Surrender of Others' Freedom.
7006 If conditions are imposed on you (whether by court order, agreement
7007 or otherwise) that contradict the conditions of this License, they
7008 do not excuse you from the conditions of this License. If you
7009 cannot convey a covered work so as to satisfy simultaneously your
7010 obligations under this License and any other pertinent obligations,
7011 then as a consequence you may not convey it at all. For example,
7012 if you agree to terms that obligate you to collect a royalty for
7013 further conveying from those to whom you convey the Program, the
7014 only way you could satisfy both those terms and this License would
7015 be to refrain entirely from conveying the Program.
7017 13. Use with the GNU Affero General Public License.
7019 Notwithstanding any other provision of this License, you have
7020 permission to link or combine any covered work with a work licensed
7021 under version 3 of the GNU Affero General Public License into a
7022 single combined work, and to convey the resulting work. The terms
7023 of this License will continue to apply to the part which is the
7024 covered work, but the special requirements of the GNU Affero
7025 General Public License, section 13, concerning interaction through
7026 a network will apply to the combination as such.
7028 14. Revised Versions of this License.
7030 The Free Software Foundation may publish revised and/or new
7031 versions of the GNU General Public License from time to time. Such
7032 new versions will be similar in spirit to the present version, but
7033 may differ in detail to address new problems or concerns.
7035 Each version is given a distinguishing version number. If the
7036 Program specifies that a certain numbered version of the GNU
7037 General Public License "or any later version" applies to it, you
7038 have the option of following the terms and conditions either of
7039 that numbered version or of any later version published by the Free
7040 Software Foundation. If the Program does not specify a version
7041 number of the GNU General Public License, you may choose any
7042 version ever published by the Free Software Foundation.
7044 If the Program specifies that a proxy can decide which future
7045 versions of the GNU General Public License can be used, that
7046 proxy's public statement of acceptance of a version permanently
7047 authorizes you to choose that version for the Program.
7049 Later license versions may give you additional or different
7050 permissions. However, no additional obligations are imposed on any
7051 author or copyright holder as a result of your choosing to follow a
7054 15. Disclaimer of Warranty.
7056 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
7057 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
7058 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
7059 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
7060 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
7061 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
7062 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
7063 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
7064 NECESSARY SERVICING, REPAIR OR CORRECTION.
7066 16. Limitation of Liability.
7068 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
7069 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
7070 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
7071 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
7072 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
7073 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
7074 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
7075 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
7076 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
7077 THE POSSIBILITY OF SUCH DAMAGES.
7079 17. Interpretation of Sections 15 and 16.
7081 If the disclaimer of warranty and limitation of liability provided
7082 above cannot be given local legal effect according to their terms,
7083 reviewing courts shall apply local law that most closely
7084 approximates an absolute waiver of all civil liability in
7085 connection with the Program, unless a warranty or assumption of
7086 liability accompanies a copy of the Program in return for a fee.
7088 END OF TERMS AND CONDITIONS
7089 ===========================
7091 How to Apply These Terms to Your New Programs
7092 =============================================
7094 If you develop a new program, and you want it to be of the greatest
7095 possible use to the public, the best way to achieve this is to make it
7096 free software which everyone can redistribute and change under these
7099 To do so, attach the following notices to the program. It is safest
7100 to attach them to the start of each source file to most effectively
7101 state the exclusion of warranty; and each file should have at least the
7102 "copyright" line and a pointer to where the full notice is found.
7104 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
7105 Copyright (C) YEAR NAME OF AUTHOR
7107 This program is free software: you can redistribute it and/or modify
7108 it under the terms of the GNU General Public License as published by
7109 the Free Software Foundation, either version 3 of the License, or (at
7110 your option) any later version.
7112 This program is distributed in the hope that it will be useful, but
7113 WITHOUT ANY WARRANTY; without even the implied warranty of
7114 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
7115 General Public License for more details.
7117 You should have received a copy of the GNU General Public License
7118 along with this program. If not, see <http://www.gnu.org/licenses/>.
7120 Also add information on how to contact you by electronic and paper
7123 If the program does terminal interaction, make it output a short
7124 notice like this when it starts in an interactive mode:
7126 PROGRAM Copyright (C) YEAR NAME OF AUTHOR
7127 This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
7128 This is free software, and you are welcome to redistribute it
7129 under certain conditions; type 'show c' for details.
7131 The hypothetical commands 'show w' and 'show c' should show the
7132 appropriate parts of the General Public License. Of course, your
7133 program's commands might be different; for a GUI interface, you would
7136 You should also get your employer (if you work as a programmer) or
7137 school, if any, to sign a "copyright disclaimer" for the program, if
7138 necessary. For more information on this, and how to apply and follow
7139 the GNU GPL, see <http://www.gnu.org/licenses/>.
7141 The GNU General Public License does not permit incorporating your
7142 program into proprietary programs. If your program is a subroutine
7143 library, you may consider it more useful to permit linking proprietary
7144 applications with the library. If this is what you want to do, use the
7145 GNU Lesser General Public License instead of this License. But first,
7146 please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.
7149 File: gdb.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Copying, Up: Top
7151 Appendix M GNU Free Documentation License
7152 *****************************************
7154 Version 1.3, 3 November 2008
7156 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
7159 Everyone is permitted to copy and distribute verbatim copies
7160 of this license document, but changing it is not allowed.
7164 The purpose of this License is to make a manual, textbook, or other
7165 functional and useful document "free" in the sense of freedom: to
7166 assure everyone the effective freedom to copy and redistribute it,
7167 with or without modifying it, either commercially or
7168 noncommercially. Secondarily, this License preserves for the
7169 author and publisher a way to get credit for their work, while not
7170 being considered responsible for modifications made by others.
7172 This License is a kind of "copyleft", which means that derivative
7173 works of the document must themselves be free in the same sense.
7174 It complements the GNU General Public License, which is a copyleft
7175 license designed for free software.
7177 We have designed this License in order to use it for manuals for
7178 free software, because free software needs free documentation: a
7179 free program should come with manuals providing the same freedoms
7180 that the software does. But this License is not limited to
7181 software manuals; it can be used for any textual work, regardless
7182 of subject matter or whether it is published as a printed book. We
7183 recommend this License principally for works whose purpose is
7184 instruction or reference.
7186 1. APPLICABILITY AND DEFINITIONS
7188 This License applies to any manual or other work, in any medium,
7189 that contains a notice placed by the copyright holder saying it can
7190 be distributed under the terms of this License. Such a notice
7191 grants a world-wide, royalty-free license, unlimited in duration,
7192 to use that work under the conditions stated herein. The
7193 "Document", below, refers to any such manual or work. Any member
7194 of the public is a licensee, and is addressed as "you". You accept
7195 the license if you copy, modify or distribute the work in a way
7196 requiring permission under copyright law.
7198 A "Modified Version" of the Document means any work containing the
7199 Document or a portion of it, either copied verbatim, or with
7200 modifications and/or translated into another language.
7202 A "Secondary Section" is a named appendix or a front-matter section
7203 of the Document that deals exclusively with the relationship of the
7204 publishers or authors of the Document to the Document's overall
7205 subject (or to related matters) and contains nothing that could
7206 fall directly within that overall subject. (Thus, if the Document
7207 is in part a textbook of mathematics, a Secondary Section may not
7208 explain any mathematics.) The relationship could be a matter of
7209 historical connection with the subject or with related matters, or
7210 of legal, commercial, philosophical, ethical or political position
7213 The "Invariant Sections" are certain Secondary Sections whose
7214 titles are designated, as being those of Invariant Sections, in the
7215 notice that says that the Document is released under this License.
7216 If a section does not fit the above definition of Secondary then it
7217 is not allowed to be designated as Invariant. The Document may
7218 contain zero Invariant Sections. If the Document does not identify
7219 any Invariant Sections then there are none.
7221 The "Cover Texts" are certain short passages of text that are
7222 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
7223 that says that the Document is released under this License. A
7224 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
7225 be at most 25 words.
7227 A "Transparent" copy of the Document means a machine-readable copy,
7228 represented in a format whose specification is available to the
7229 general public, that is suitable for revising the document
7230 straightforwardly with generic text editors or (for images composed
7231 of pixels) generic paint programs or (for drawings) some widely
7232 available drawing editor, and that is suitable for input to text
7233 formatters or for automatic translation to a variety of formats
7234 suitable for input to text formatters. A copy made in an otherwise
7235 Transparent file format whose markup, or absence of markup, has
7236 been arranged to thwart or discourage subsequent modification by
7237 readers is not Transparent. An image format is not Transparent if
7238 used for any substantial amount of text. A copy that is not
7239 "Transparent" is called "Opaque".
7241 Examples of suitable formats for Transparent copies include plain
7242 ASCII without markup, Texinfo input format, LaTeX input format,
7243 SGML or XML using a publicly available DTD, and standard-conforming
7244 simple HTML, PostScript or PDF designed for human modification.
7245 Examples of transparent image formats include PNG, XCF and JPG.
7246 Opaque formats include proprietary formats that can be read and
7247 edited only by proprietary word processors, SGML or XML for which
7248 the DTD and/or processing tools are not generally available, and
7249 the machine-generated HTML, PostScript or PDF produced by some word
7250 processors for output purposes only.
7252 The "Title Page" means, for a printed book, the title page itself,
7253 plus such following pages as are needed to hold, legibly, the
7254 material this License requires to appear in the title page. For
7255 works in formats which do not have any title page as such, "Title
7256 Page" means the text near the most prominent appearance of the
7257 work's title, preceding the beginning of the body of the text.
7259 The "publisher" means any person or entity that distributes copies
7260 of the Document to the public.
7262 A section "Entitled XYZ" means a named subunit of the Document
7263 whose title either is precisely XYZ or contains XYZ in parentheses
7264 following text that translates XYZ in another language. (Here XYZ
7265 stands for a specific section name mentioned below, such as
7266 "Acknowledgements", "Dedications", "Endorsements", or "History".)
7267 To "Preserve the Title" of such a section when you modify the
7268 Document means that it remains a section "Entitled XYZ" according
7271 The Document may include Warranty Disclaimers next to the notice
7272 which states that this License applies to the Document. These
7273 Warranty Disclaimers are considered to be included by reference in
7274 this License, but only as regards disclaiming warranties: any other
7275 implication that these Warranty Disclaimers may have is void and
7276 has no effect on the meaning of this License.
7280 You may copy and distribute the Document in any medium, either
7281 commercially or noncommercially, provided that this License, the
7282 copyright notices, and the license notice saying this License
7283 applies to the Document are reproduced in all copies, and that you
7284 add no other conditions whatsoever to those of this License. You
7285 may not use technical measures to obstruct or control the reading
7286 or further copying of the copies you make or distribute. However,
7287 you may accept compensation in exchange for copies. If you
7288 distribute a large enough number of copies you must also follow the
7289 conditions in section 3.
7291 You may also lend copies, under the same conditions stated above,
7292 and you may publicly display copies.
7294 3. COPYING IN QUANTITY
7296 If you publish printed copies (or copies in media that commonly
7297 have printed covers) of the Document, numbering more than 100, and
7298 the Document's license notice requires Cover Texts, you must
7299 enclose the copies in covers that carry, clearly and legibly, all
7300 these Cover Texts: Front-Cover Texts on the front cover, and
7301 Back-Cover Texts on the back cover. Both covers must also clearly
7302 and legibly identify you as the publisher of these copies. The
7303 front cover must present the full title with all words of the title
7304 equally prominent and visible. You may add other material on the
7305 covers in addition. Copying with changes limited to the covers, as
7306 long as they preserve the title of the Document and satisfy these
7307 conditions, can be treated as verbatim copying in other respects.
7309 If the required texts for either cover are too voluminous to fit
7310 legibly, you should put the first ones listed (as many as fit
7311 reasonably) on the actual cover, and continue the rest onto
7314 If you publish or distribute Opaque copies of the Document
7315 numbering more than 100, you must either include a machine-readable
7316 Transparent copy along with each Opaque copy, or state in or with
7317 each Opaque copy a computer-network location from which the general
7318 network-using public has access to download using public-standard
7319 network protocols a complete Transparent copy of the Document, free
7320 of added material. If you use the latter option, you must take
7321 reasonably prudent steps, when you begin distribution of Opaque
7322 copies in quantity, to ensure that this Transparent copy will
7323 remain thus accessible at the stated location until at least one
7324 year after the last time you distribute an Opaque copy (directly or
7325 through your agents or retailers) of that edition to the public.
7327 It is requested, but not required, that you contact the authors of
7328 the Document well before redistributing any large number of copies,
7329 to give them a chance to provide you with an updated version of the
7334 You may copy and distribute a Modified Version of the Document
7335 under the conditions of sections 2 and 3 above, provided that you
7336 release the Modified Version under precisely this License, with the
7337 Modified Version filling the role of the Document, thus licensing
7338 distribution and modification of the Modified Version to whoever
7339 possesses a copy of it. In addition, you must do these things in
7340 the Modified Version:
7342 A. Use in the Title Page (and on the covers, if any) a title
7343 distinct from that of the Document, and from those of previous
7344 versions (which should, if there were any, be listed in the
7345 History section of the Document). You may use the same title
7346 as a previous version if the original publisher of that
7347 version gives permission.
7349 B. List on the Title Page, as authors, one or more persons or
7350 entities responsible for authorship of the modifications in
7351 the Modified Version, together with at least five of the
7352 principal authors of the Document (all of its principal
7353 authors, if it has fewer than five), unless they release you
7354 from this requirement.
7356 C. State on the Title page the name of the publisher of the
7357 Modified Version, as the publisher.
7359 D. Preserve all the copyright notices of the Document.
7361 E. Add an appropriate copyright notice for your modifications
7362 adjacent to the other copyright notices.
7364 F. Include, immediately after the copyright notices, a license
7365 notice giving the public permission to use the Modified
7366 Version under the terms of this License, in the form shown in
7369 G. Preserve in that license notice the full lists of Invariant
7370 Sections and required Cover Texts given in the Document's
7373 H. Include an unaltered copy of this License.
7375 I. Preserve the section Entitled "History", Preserve its Title,
7376 and add to it an item stating at least the title, year, new
7377 authors, and publisher of the Modified Version as given on the
7378 Title Page. If there is no section Entitled "History" in the
7379 Document, create one stating the title, year, authors, and
7380 publisher of the Document as given on its Title Page, then add
7381 an item describing the Modified Version as stated in the
7384 J. Preserve the network location, if any, given in the Document
7385 for public access to a Transparent copy of the Document, and
7386 likewise the network locations given in the Document for
7387 previous versions it was based on. These may be placed in the
7388 "History" section. You may omit a network location for a work
7389 that was published at least four years before the Document
7390 itself, or if the original publisher of the version it refers
7391 to gives permission.
7393 K. For any section Entitled "Acknowledgements" or "Dedications",
7394 Preserve the Title of the section, and preserve in the section
7395 all the substance and tone of each of the contributor
7396 acknowledgements and/or dedications given therein.
7398 L. Preserve all the Invariant Sections of the Document, unaltered
7399 in their text and in their titles. Section numbers or the
7400 equivalent are not considered part of the section titles.
7402 M. Delete any section Entitled "Endorsements". Such a section
7403 may not be included in the Modified Version.
7405 N. Do not retitle any existing section to be Entitled
7406 "Endorsements" or to conflict in title with any Invariant
7409 O. Preserve any Warranty Disclaimers.
7411 If the Modified Version includes new front-matter sections or
7412 appendices that qualify as Secondary Sections and contain no
7413 material copied from the Document, you may at your option designate
7414 some or all of these sections as invariant. To do this, add their
7415 titles to the list of Invariant Sections in the Modified Version's
7416 license notice. These titles must be distinct from any other
7419 You may add a section Entitled "Endorsements", provided it contains
7420 nothing but endorsements of your Modified Version by various
7421 parties--for example, statements of peer review or that the text
7422 has been approved by an organization as the authoritative
7423 definition of a standard.
7425 You may add a passage of up to five words as a Front-Cover Text,
7426 and a passage of up to 25 words as a Back-Cover Text, to the end of
7427 the list of Cover Texts in the Modified Version. Only one passage
7428 of Front-Cover Text and one of Back-Cover Text may be added by (or
7429 through arrangements made by) any one entity. If the Document
7430 already includes a cover text for the same cover, previously added
7431 by you or by arrangement made by the same entity you are acting on
7432 behalf of, you may not add another; but you may replace the old
7433 one, on explicit permission from the previous publisher that added
7436 The author(s) and publisher(s) of the Document do not by this
7437 License give permission to use their names for publicity for or to
7438 assert or imply endorsement of any Modified Version.
7440 5. COMBINING DOCUMENTS
7442 You may combine the Document with other documents released under
7443 this License, under the terms defined in section 4 above for
7444 modified versions, provided that you include in the combination all
7445 of the Invariant Sections of all of the original documents,
7446 unmodified, and list them all as Invariant Sections of your
7447 combined work in its license notice, and that you preserve all
7448 their Warranty Disclaimers.
7450 The combined work need only contain one copy of this License, and
7451 multiple identical Invariant Sections may be replaced with a single
7452 copy. If there are multiple Invariant Sections with the same name
7453 but different contents, make the title of each such section unique
7454 by adding at the end of it, in parentheses, the name of the
7455 original author or publisher of that section if known, or else a
7456 unique number. Make the same adjustment to the section titles in
7457 the list of Invariant Sections in the license notice of the
7460 In the combination, you must combine any sections Entitled
7461 "History" in the various original documents, forming one section
7462 Entitled "History"; likewise combine any sections Entitled
7463 "Acknowledgements", and any sections Entitled "Dedications". You
7464 must delete all sections Entitled "Endorsements."
7466 6. COLLECTIONS OF DOCUMENTS
7468 You may make a collection consisting of the Document and other
7469 documents released under this License, and replace the individual
7470 copies of this License in the various documents with a single copy
7471 that is included in the collection, provided that you follow the
7472 rules of this License for verbatim copying of each of the documents
7473 in all other respects.
7475 You may extract a single document from such a collection, and
7476 distribute it individually under this License, provided you insert
7477 a copy of this License into the extracted document, and follow this
7478 License in all other respects regarding verbatim copying of that
7481 7. AGGREGATION WITH INDEPENDENT WORKS
7483 A compilation of the Document or its derivatives with other
7484 separate and independent documents or works, in or on a volume of a
7485 storage or distribution medium, is called an "aggregate" if the
7486 copyright resulting from the compilation is not used to limit the
7487 legal rights of the compilation's users beyond what the individual
7488 works permit. When the Document is included in an aggregate, this
7489 License does not apply to the other works in the aggregate which
7490 are not themselves derivative works of the Document.
7492 If the Cover Text requirement of section 3 is applicable to these
7493 copies of the Document, then if the Document is less than one half
7494 of the entire aggregate, the Document's Cover Texts may be placed
7495 on covers that bracket the Document within the aggregate, or the
7496 electronic equivalent of covers if the Document is in electronic
7497 form. Otherwise they must appear on printed covers that bracket
7498 the whole aggregate.
7502 Translation is considered a kind of modification, so you may
7503 distribute translations of the Document under the terms of section
7504 4. Replacing Invariant Sections with translations requires special
7505 permission from their copyright holders, but you may include
7506 translations of some or all Invariant Sections in addition to the
7507 original versions of these Invariant Sections. You may include a
7508 translation of this License, and all the license notices in the
7509 Document, and any Warranty Disclaimers, provided that you also
7510 include the original English version of this License and the
7511 original versions of those notices and disclaimers. In case of a
7512 disagreement between the translation and the original version of
7513 this License or a notice or disclaimer, the original version will
7516 If a section in the Document is Entitled "Acknowledgements",
7517 "Dedications", or "History", the requirement (section 4) to
7518 Preserve its Title (section 1) will typically require changing the
7523 You may not copy, modify, sublicense, or distribute the Document
7524 except as expressly provided under this License. Any attempt
7525 otherwise to copy, modify, sublicense, or distribute it is void,
7526 and will automatically terminate your rights under this License.
7528 However, if you cease all violation of this License, then your
7529 license from a particular copyright holder is reinstated (a)
7530 provisionally, unless and until the copyright holder explicitly and
7531 finally terminates your license, and (b) permanently, if the
7532 copyright holder fails to notify you of the violation by some
7533 reasonable means prior to 60 days after the cessation.
7535 Moreover, your license from a particular copyright holder is
7536 reinstated permanently if the copyright holder notifies you of the
7537 violation by some reasonable means, this is the first time you have
7538 received notice of violation of this License (for any work) from
7539 that copyright holder, and you cure the violation prior to 30 days
7540 after your receipt of the notice.
7542 Termination of your rights under this section does not terminate
7543 the licenses of parties who have received copies or rights from you
7544 under this License. If your rights have been terminated and not
7545 permanently reinstated, receipt of a copy of some or all of the
7546 same material does not give you any rights to use it.
7548 10. FUTURE REVISIONS OF THIS LICENSE
7550 The Free Software Foundation may publish new, revised versions of
7551 the GNU Free Documentation License from time to time. Such new
7552 versions will be similar in spirit to the present version, but may
7553 differ in detail to address new problems or concerns. See
7554 <http://www.gnu.org/copyleft/>.
7556 Each version of the License is given a distinguishing version
7557 number. If the Document specifies that a particular numbered
7558 version of this License "or any later version" applies to it, you
7559 have the option of following the terms and conditions either of
7560 that specified version or of any later version that has been
7561 published (not as a draft) by the Free Software Foundation. If the
7562 Document does not specify a version number of this License, you may
7563 choose any version ever published (not as a draft) by the Free
7564 Software Foundation. If the Document specifies that a proxy can
7565 decide which future versions of this License can be used, that
7566 proxy's public statement of acceptance of a version permanently
7567 authorizes you to choose that version for the Document.
7571 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
7572 World Wide Web server that publishes copyrightable works and also
7573 provides prominent facilities for anybody to edit those works. A
7574 public wiki that anybody can edit is an example of such a server.
7575 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
7576 site means any set of copyrightable works thus published on the MMC
7579 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
7580 license published by Creative Commons Corporation, a not-for-profit
7581 corporation with a principal place of business in San Francisco,
7582 California, as well as future copyleft versions of that license
7583 published by that same organization.
7585 "Incorporate" means to publish or republish a Document, in whole or
7586 in part, as part of another Document.
7588 An MMC is "eligible for relicensing" if it is licensed under this
7589 License, and if all works that were first published under this
7590 License somewhere other than this MMC, and subsequently
7591 incorporated in whole or in part into the MMC, (1) had no cover
7592 texts or invariant sections, and (2) were thus incorporated prior
7593 to November 1, 2008.
7595 The operator of an MMC Site may republish an MMC contained in the
7596 site under CC-BY-SA on the same site at any time before August 1,
7597 2009, provided the MMC is eligible for relicensing.
7599 ADDENDUM: How to use this License for your documents
7600 ====================================================
7602 To use this License in a document you have written, include a copy of
7603 the License in the document and put the following copyright and license
7604 notices just after the title page:
7606 Copyright (C) YEAR YOUR NAME.
7607 Permission is granted to copy, distribute and/or modify this document
7608 under the terms of the GNU Free Documentation License, Version 1.3
7609 or any later version published by the Free Software Foundation;
7610 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
7611 Texts. A copy of the license is included in the section entitled ``GNU
7612 Free Documentation License''.
7614 If you have Invariant Sections, Front-Cover Texts and Back-Cover
7615 Texts, replace the "with...Texts." line with this:
7617 with the Invariant Sections being LIST THEIR TITLES, with
7618 the Front-Cover Texts being LIST, and with the Back-Cover Texts
7621 If you have Invariant Sections without Cover Texts, or some other
7622 combination of the three, merge those two alternatives to suit the
7625 If your document contains nontrivial examples of program code, we
7626 recommend releasing these examples in parallel under your choice of free
7627 software license, such as the GNU General Public License, to permit
7628 their use in free software.
projects / platform / upstream / gdb.git / blob